UnityAI/rules/40-工作流清单.md

工作流清单

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

---

任务分类

类型	特征	处理方式
简单修复	查询、解释、小范围修改、影响面低、用户已给出明确方式	直接处理，完成后验证并归档检查
旧模块修复	已有框架模块的 bug 修复、逻辑补全、局部优化	读取模块文档，分析影响范围后修复，验证并归档
Spec 任务	新增框架模块、调整架构/目录/依赖、批量修改迁移	走 OpenSpec 流程

---

简单修复流程

1. 确认任务范围。
2. 读取相关模块文档。
3. 直接修改。
4. 验证（如可运行测试、检查链接、预览 Markdown）。
5. 执行归档检查。
6. 简短说明结果。

---

旧模块修复流程

1. 定位已有模块文档和相关内容。
2. 简短分析影响范围和风险。
3. 直接修复。
4. 验证。
5. 按 50-归档规则.md 同步相关模块文档。

---

Spec 任务流程

大需求 / 新模块统一走 OpenSpec：

1. 分析目标、影响范围、风险和依赖。
2. 给出 2-3 个方案。
3. 用户确认后创建 OpenSpec change。
4. 生成 proposal.md、design.md、tasks.md。
5. 实现。
6. 验证。
7. 归档并同步文档。

详见 60-新特性工作流.md。

---

开发流程

1. 文档学习

根据任务类型阅读对应模块文档：

任务类型	必读文档
UI 开发	UI 窗口系统
UI 界面设计	UI 界面拼接设计指南
相机控制	相机系统
实体开发	实体系统
事件使用	事件系统
资源加载	资源管理

2. 需求分析

1. 明确需求：理解业务需求，确定需要实现的功能。
2. 评估复杂度：判断是否需要核心库支持或扩展。
3. 设计方案：规划代码结构和调用关系。

3. 代码编写

1. 在 GameFunction/ 下按职责创建模块目录。
2. 遵循编码规范，使用核心库提供的 API。
3. 在 Unity 中测试功能正确性。

4. 代码审查

1. 自我检查：检查是否符合规范，是否有潜在问题。
2. 团队审查：提交代码进行团队审查。
3. 修复问题：根据审查意见修改代码。

5. 集成测试

1. 模块测试：测试单个模块功能。
2. 集成测试：测试模块间交互。
3. 回归测试：确保不影响现有功能。

---

文档变更联动检查

修改任何文档前，确认它是否被其他文档引用：

• 模块文档变更 → 同步检查模块索引、模块登记规则、架构说明。
• 架构/目录变更 → 同步检查模块索引、相关模块 README、架构说明。
• 规则文件变更 → 同步检查 rules/项目规则入口.md、ai/AI接入入口.md、AGENTS.md、CLAUDE.md、RULES.md。
• spec/change 完成 → 同步更新相关模块 progress.md，并建立 specs/openspec/ 归档。

---

提交前检查

提交信息格式

推荐格式：

[模块][类型]: 简短描述

- 详细说明 1
- 详细说明 2

类型：feat、fix、docs、refactor、test、chore。

模块名示例：framework、entity、ui、event、resource、docs、rules、hooks。

示例：

[entity][docs]: 补充实体池索引机制说明

- 添加 onlyid -> entity 映射说明
- 补充 HFBasicPool/HFEnemyPool/HFHumanityPool 边界

历史格式说明：早期文档使用 【操作原因】具体操作内容（如 【修复】xxx）。该格式已弃用，新提交统一使用 [module][type]: description。

分支管理

分支名称	用途
master	主分支，稳定版本
develop	开发分支，日常开发
feature/*	功能分支，开发新功能
bugfix/*	Bug 修复分支

Git 操作原则

• 执行 Git 操作前确认当前操作路径是否正确。
• 遵循项目既定的分支策略。
• 使用语义化提交信息，清晰描述更改内容。
• 重要功能提交前建议先创建分支进行测试。
• 开发完成后及时推送到远程仓库。

提交前检查项

• 文档链接可点击且指向正确。
• 文档关联表已更新。
• 模块索引已同步（如新增/拆分了模块）。
• 无拼写或明显格式错误。
• 未引入外部项目专属内容。
• 业务参考内容只出现在 business-reference/ 下。

---

新增内容流程

新增框架模块

1. 在 模块索引 中登记。
2. 创建 modules/frameworks/<module>.md；复杂模块可拆分为 modules/frameworks/<module>/README.md 加子文档。
3. 在 架构说明 中补充依赖方向。
4. 更新相关模块的文档关联表。

新增编辑器工具

1. 在 模块索引 中登记。
2. 创建 modules/editor-tools/<tool>.md 或补充汇总文档。
3. 说明使用入口、生成输出、依赖项。

新增业务参考

1. 放入 business-reference/<project>/。
2. 不进入 modules/模块索引.md 主索引。
3. 在 business-reference/<project>/业务框架映射接口.md 中补充映射关系。

---

生成/构建流程

若项目使用 StrayFog 框架配套的生成工具：

• 优先修改源表、proto 或 schema，而不是生成输出。
• 生成后检查输出目录，确认变更符合预期。
• 缺失的生成步骤记录到对应模块文档。

---

文档关联

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

文档	关联原因
rules/项目规则入口.md	工作流清单是项目规则入口索引的关键规则
rules/50-归档规则.md	归档规则与工作流清单互相引用
rules/60-新特性工作流.md	新特性工作流是工作流清单的延伸
rules/20-开发规则.md	提交格式与开发规则互相引用
modules/模块索引.md	新增模块登记需同步模块索引
hooks/commit-check.ps1	提交检查脚本需与本文件格式一致