Hua.Todo/.trae/rules/全局/05-研发工单规则.md

研发工单同步规则汇总（Dev Work Item Rules）

适用范围：本规则属于 全局规则（跨项目通用），关注智能体如何拆分编码工作。

⚠️ 术语澄清（必读）

本项目存在两类"任务"概念，必须严格区分，避免命名混淆：

术语	含义	适用范围
研发工单（Dev Work Item）	智能体 / 开发者执行的编码工作项（拆分需求、并行开发、集成等）	本规则文档的全部内容
Todo 待办项（Todo Item）	Hua.Todo 项目业务领域中用户创建的待办事项（数据库实体、API 资源、UI 列表项）	业务代码、产品需求文档、技术设计文档

本文档中所有"研发工单 / 工单 / 子工单"均指编码工作项，与业务侧的 Todo 待办项无关。 在代码、文档与对话中，凡涉及编码侧拆分时，必须使用"研发工单"或"工单"，禁止再使用"任务"二字以避免与 Todo 待办项混淆。

业务侧由于历史原因仍保留 Task / SubTask 等代码标识符（API、实体、UI），这些属于 Todo 待办项语义，不在本规范替换范围内。

本汇总文件是 06-研发工单拆分规范.md 与 07-并行窗口冲突规约.md 的对外索引，详细规则以这两份源文件为准。

---

一、研发工单拆分规范

适用时机

• 当需求需要先通读项目/产品/技术文档再开始实现时，必须先输出研发工单拆分文档

输出要求

1. 先读完所有相关文档：包括 docs/、docs/project/ 下与本次需求相关的内容
2. 先写工单拆分，再动手实现：研发工单拆分产出是后续执行的入口与对齐依据
3. 新增专属文件夹：在 docs/project 下新建 研发工单-<主题>-<日期或版本> 文件夹
4. 可并行工单拆分：能同步执行的工单必须拆到不同 Markdown 文件中
5. 文件带序号：按执行顺序编号（01-xxx.md、02-xxx.md）

每个研发工单文件必须包含

• 目标 / 范围（做什么、不做什么）
• 前置条件（依赖哪些结论 / 接口 / 文档）
• 验收标准（可执行的验证点）
• 风险与回滚（如有）

子工单完成标记要求

• 子工单完成后，必须在 00-工单总览.md 中标注"已完成"
• 维护"待验证表"，记录每个子工单的"待验证 / 已验证"状态

---

二、并行窗口冲突规约

核心原则

1. 先声明后修改：修改前先声明 Touch List 与共享文件策略
2. 文件所有权唯一：同一时段内一个文件只能由一个窗口修改
3. 共享文件单点修改：高耦合 / 共享入口的改动集中到集成窗口完成
4. 绿线优先：任何可落盘的变更必须保持可编译

Touch List 要求

• 精确到文件路径
• 标注修改类型（新增 / 小改 / 重构 / 接口变更 / 配置变更）
• 标注是否为共享文件
• 使用相对路径：src\<module>\<file>

共享文件判定标准（满足其一即为共享）

• 项目入口 / 启动逻辑、依赖注入注册、全局路由
• 公共配置、公共协议与 DTO、公共组件 / 样式
• 解决方案文件（.sln、.csproj）、锁文件、全局配置

Writer 约束

• 非 Writer 窗口不得编辑共享文件
• 非 Writer 只能提供"差异建议"给 Writer 落盘

协调目录

固定目录：.trae\coordination\

• 01-ownership.md：文件所有权登记表
• 02-shared-files.md：共享文件清单（集成窗口维护）
• handoff\：差异建议 / 交接说明
• wip\：编译中途状态说明

编译绿线规则

• 不得提交破坏编译的变更
• 临时隔离手段（按优先级）：
  1. 新功能先放在新文件中，不在入口路径启用
  2. 通过显式开关控制，默认关闭
  3. 通过依赖注入分支或特性开关隔离
• 接口演进采用"双写 / 兼容期"策略

---

三、推荐文档结构

docs/project/研发工单-<主题>-<版本>/
├── 00-工单总览.md      # 背景、目标、关键决策、并行分组、待验证表
├── 01-并行工单A.md
├── 02-并行工单B.md
└── 03-串行工单C.md

注意：上述目录与文件名中的"工单"指研发工单，与业务侧 Todo 待办项无关。

---

四、检查清单

研发工单拆分检查

1. 是否已阅读完所有相关文档？
2. 是否在 docs/project 下新建了专属文件夹（命名以"研发工单-"开头）？
3. 是否产出 00-工单总览.md？
4. 是否将可并行工单拆分为不同 md 文件？
5. 是否所有 md 文件都带有连续序号？
6. 子工单完成后是否在总览中标注"已完成"并更新待验证表？

并行冲突检查

1. 每个研发工单 md 是否已写 Touch List（精确到文件）？
2. Touch List 中的共享文件是否指定了唯一 Writer？
3. 是否避免了对共享文件的无意义格式化 / 重排？
4. 当前改动是否保持可编译（绿线）？
5. 若涉及接口演进，是否采用兼容期策略？

---

五、与业务侧 Todo 待办项的边界

• 代码、注释、提交信息中描述编码工作时：使用"研发工单 / 工单 / 子工单"
• 代码、注释、提交信息中描述业务功能时：使用"Todo 待办项 / Todo Item / 父子任务（业务实体）"
• 文档命名前缀：
  • 编码侧：研发工单-<主题>-<版本>/
  • 业务侧（如有）：遵循 docs/ 既有命名习惯，禁止使用"研发工单"前缀
• 提交信息示例：
  • ✅ feat(todo): 新增 Todo 待办项截止日期字段（研发工单 02-后端模型）
  • ❌ feat: 完成任务 02（"任务"歧义，禁用）