UnityAI/rules/60-新特性工作流.md

大需求 / 新模块工作流

本文档是 UnityAI / StrayFog 框架知识库的长期规则，为 Codex (AGENTS.md) 和 Claude Code (CLAUDE.md) 共同引用。

---

总体流程

判断任务类型
    |
    ├── 简单修复 ────────────────→ 直接处理 → 归档检查
    |
    ├── 旧模块修复 ──────────────→ 分析后修复 → 归档检查
    |
    └── Spec 任务 ───────────────→ OpenSpec 流程
            |
            v
    新模块 / 已有模块大改
            |
            v
    实现 → 验证 → archive → 同步文档

---

三种任务类型判定

类型	判定标准
简单修复	查询、解释、小范围修改、用户已给出明确实现方式
旧模块修复	已有框架模块的局部修复，不新增模块、不调整架构
Spec 任务	新增框架模块、调整架构/目录/依赖、批量迁移、用户未明确方案

---

创建 OpenSpec Change

当任务被判定为 Spec 任务时：

1. 分析目标、影响范围、风险和依赖。
2. 给出 2-3 个方案，让用户选择。
3. 用户确认后创建 OpenSpec change：
   • Claude Code：/opsx:propose "需求描述"
   • CLI 通用：openspec new change "change-name"
4. 生成 proposal.md、design.md、tasks.md。

---

新模块操作清单

适用于在 StrayFog 框架知识库中新增一个框架模块，例如：

• 新增“相机系统”模块文档
• 新增“配置生成”模块文档
• 新增“网络系统”模块文档

操作步骤：

1. 在 模块索引 中登记模块。
2. 创建模块文档 modules/frameworks/<module>.md（简单模块）或 modules/frameworks/<module>/业务参考总入口.md（复杂模块）。
3. 如为复杂模块，创建 progress.md 和 tasks.md。
4. 在 架构说明 中补充该模块的分层位置和依赖方向。
5. 更新相关模块的文档关联表。
6. 如新增模块影响开发规则，更新 开发规则。
7. 按 design/tasks 完成内容编写。
8. 验证文档链接、格式、关联表完整性。
9. 归档 OpenSpec change。
10. 同步更新模块索引、架构说明、相关模块文档。

---

已有模块大改操作清单

适用于对已有框架模块进行较大调整，例如：

• 重构实体系统文档结构
• 调整 UI 窗口系统的生命周期描述
• 合并/拆分对象池相关文档

操作步骤：

1. 读取现有模块文档和模块索引。
2. 在 OpenSpec design.md 中说明变更原因、影响范围、新结构。
3. 更新模块 模块索引.md。
4. 更新模块 progress.md，记录本次变更。
5. 更新模块 tasks.md，记录后续待办。
6. 同步更新 模块索引。
7. 如影响架构或依赖方向，更新 架构说明。
8. 验证文档关联表一致性。
9. 归档 OpenSpec change。

---

实现与验证

• 按 tasks.md 逐项完成。
• 每完成一项，在 tasks.md 中标记。
• 验证方式包括：
  • Markdown 链接检查
  • 文档关联表完整性检查
  • 人工阅读关键章节
  • 运行 hooks/archive-check.ps1 检查关联文档

---

归档与联动更新

归档 OpenSpec change 后，必须同步更新：

• specs/openspec/<change-name>/
• 相关模块 模块索引.md、progress.md、tasks.md
• rules/10-架构说明.md（如涉及架构变化）
• modules/模块索引.md（如新增模块）
• rules/30-模块登记规则.md（如改变模块分类、状态定义或登记规则）

---

禁止事项

• 不要在没有 OpenSpec 的情况下进行大模块新增或架构调整。
• 不要把临时讨论写进长期文档。
• 不要创建没有从模块索引链接过去的孤儿文档。
• 不要把外部项目专属内容混入框架核心文档。

---

文档关联

当本文档发生变更时，应同步检查以下关联文档，避免信息不一致。

文档	关联原因
rules/项目规则入口.md	新特性工作流是项目规则入口索引的关键规则
rules/40-工作流清单.md	工作流清单与新特性工作流互相引用
rules/50-归档规则.md	归档规则与新特性工作流互相引用
specs/openspec/OpenSpec归档.md	OpenSpec 归档说明与新特性工作流互相引用
modules/模块索引.md	新增/拆分模块需同步模块索引