# 大需求 / 新模块工作流

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

---

## 总体流程

```text
判断任务类型
    |
    ├── 简单修复 ────────────────→ 直接处理 → 归档检查
    |
    ├── 旧模块修复 ──────────────→ 分析后修复 → 归档检查
    |
    └── 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. 在 [模块索引](../modules/模块索引.md) 中登记模块。
2. 创建模块文档 `modules/frameworks/<module>.md`（简单模块）或 `modules/frameworks/<module>/业务参考总入口.md`（复杂模块）。
3. 如为复杂模块，创建 `progress.md` 和 `tasks.md`。
4. 在 [架构说明](../rules/10-架构说明.md) 中补充该模块的分层位置和依赖方向。
5. 更新相关模块的文档关联表。
6. 如新增模块影响开发规则，更新 [开发规则](../rules/20-开发规则.md)。
7. 按 design/tasks 完成内容编写。
8. 验证文档链接、格式、关联表完整性。
9. 归档 OpenSpec change。
10. 同步更新模块索引、架构说明、相关模块文档。

---

## 已有模块大改操作清单

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

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

操作步骤：

1. 读取现有模块文档和模块索引。
2. 在 OpenSpec `design.md` 中说明变更原因、影响范围、新结构。
3. 更新模块 `模块索引.md`。
4. 更新模块 `progress.md`，记录本次变更。
5. 更新模块 `tasks.md`，记录后续待办。
6. 同步更新 [模块索引](../modules/模块索引.md)。
7. 如影响架构或依赖方向，更新 [架构说明](../rules/10-架构说明.md)。
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](项目规则入口.md) | 新特性工作流是项目规则入口索引的关键规则 |
| [rules/40-工作流清单.md](40-工作流清单.md) | 工作流清单与新特性工作流互相引用 |
| [rules/50-归档规则.md](50-归档规则.md) | 归档规则与新特性工作流互相引用 |
| [specs/openspec/OpenSpec归档.md](../specs/openspec/OpenSpec归档.md) | OpenSpec 归档说明与新特性工作流互相引用 |
| [modules/模块索引.md](../modules/模块索引.md) | 新增/拆分模块需同步模块索引 |