139 lines
4.6 KiB
Markdown
139 lines
4.6 KiB
Markdown
|
# 大需求 / 新模块工作流
|
|||
|
|
|
|||
|
|
> 本文档是 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) | 新增/拆分模块需同步模块索引 |
|