Workflow Skill

Workflow Skill

本 skill 的唯一设计来源是仓库根目录的 WORKFLOW.md。执行时必须优先遵守 WORKFLOW.md，并参考 BUG_REP.md 中记录的已知问题。不要把本文件理解成命令实现；它是 Claude/Codex 执行项目开发流程时的操作规约。

基本原则

• 全程使用用户使用的语言；用户使用中文时，全程中文。
• 任何 feature 都必须按阶段推进：研究 -> 确认 -> 规划 -> 标注 -> API 文档决策/审阅 -> 执行 -> 反馈。
• 未完成当前阶段的确认门禁前，不得提前进入下一阶段。
• 执行代码前必须已有被用户认可的 plan.md；如涉及 API 变动，还必须已有被用户认可的 api.md。
• 如果 task/ 模板与 WORKFLOW.md 不一致，以 WORKFLOW.md 为准，在 feature 工作副本中补全缺失章节。
• 反馈要短。方向错误时，根据用户明确指示回滚并重写计划。

任务文件规则

新建任务时：

1. 在目标项目中创建 feature/[YYYY]/。
2. 从 skill 的 task/ 目录复制 research.md、plan.md、api.md 到 feature/[YYYY]/。
3. 将文件重命名为能对应本次任务的名称。推荐格式：
   • feature/[YYYY]/[YYYYMMDD]-[task-name]-research.md
   • feature/[YYYY]/[YYYYMMDD]-[task-name]-plan.md
   • feature/[YYYY]/[YYYYMMDD]-[task-name]-api.md
4. 只允许先填写 research 文件。plan 和 api 文件可以先创建，但不得在研究确认前填写方案。

如果用户或项目已有命名规范，优先沿用已有规范，但必须保证三类文件可互相关联。

阶段 1: 研究

目标：填满 research 文件，验证 agent 是否真正理解代码库和需求。

必须完成：

• 阅读需求、相关代码、依赖关系、已有约束。
• 在 research 文件中记录：
  • 代码库深读范围：涉及模块/文件、依赖关系、已知约束。
  • 深度分析结果：核心流程、关键数据结构。
  • 风险点：潜在破坏点、兼容性问题。
  • 待确认问题：所有需要人工确认或进一步调研的假设。
  • 下一步：确认后才进入 plan 编写。
• 如果 task/research.md 缺失上述章节，在 feature 副本里按 WORKFLOW.md 补全。

研究完成后必须停下，使用 AskUserQuestion 或等价方式向用户确认待确认问题。确认完成前，不得生成或填写 plan。

阶段 2: 规划和标注

只有研究阶段被用户确认后，才能填写 plan 文件。

plan 文件必须包含：

• 方案概述：目标、候选方案、最终选择和理由。
• 实现细节：修改文件清单、关键逻辑片段或伪代码。
• 内联标注区：用于用户反复纠正假设、拒绝方案、添加约束。
• API 文档阶段决策：明确是否涉及 API 变动。
• Todo 清单：颗粒度极细，每项可在 5-15 分钟内完成。
• 执行指令：供执行阶段复制给执行 agent。
• 反馈记录和最终状态。

标注规则：

• 用户标注后，只更新 research/plan/api 文档，不执行代码。
• 可以循环 1-6 次或更多，直到用户明确认可。
• 批准前绝不执行。
• 如果 task/plan.md 缺失上述章节，在 feature 副本里按 WORKFLOW.md 补全。

阶段 3: API 文档决策和审阅

在 plan 标注结束后，判断是否涉及 API 变动。

• 不涉及 API 变动：在 plan 中明确记录“跳过 API 文档阶段”，然后进入执行审批。
• 涉及 API 变动：填写 api 文件，并进入 API 文档审阅。

API 文档必须至少包含：

• 功能概述。
• API 列表。
• 每个接口的路径、方法、功能描述。
• 请求参数、请求示例。
• 响应参数、响应示例。
• 错误码。

API 审阅规则：

• 用户未批准前，不得执行代码。
• API 设计变更可能影响 plan；如发生变更，必须同步更新 plan，并重新进入标注直到用户认可。

阶段 4: 执行

执行只能在以下条件全部满足后开始：

• research 已完成并被确认。
• plan 已完成标注并被批准。
• 如涉及 API，api 已完成审阅并被批准。

执行方式：

1. 将 plan 中的执行指令复制给 plan-executor subagent。
2. 要求执行 agent 完成全部 Todo，并在 plan 中标记完成状态。
3. 要求执行 agent 不做无关改动，不添加无必要注释。
4. 执行期间持续运行适合项目的检查，例如 typecheck、lint、test。
5. 如果当前平台没有 plan-executor，明确告知用户该限制；只有用户同意后，才由当前 agent 执行。

推荐执行指令：

implement it all.
mark completed in plan.
do not stop until all done.
no unnecessary comments.
continuously run typecheck...

阶段 5: 反馈

执行完成后：

• 用最短句子反馈完成情况。
• 在 plan 的反馈记录和最终状态中记录结果。
• 如用户指出方向错误，按用户明确指示执行 git revert，然后回到计划阶段重写方案。

BUG_REP.md 使用

• 开始任务时读取 BUG_REP.md，确认是否有会影响本次流程的已知问题。
• 如果执行中发现 workflow 层面的 bug 或反复踩坑，记录到 BUG_REP.md，包含问题、触发条件、解决方案。
• 当前 BUG_REP.md 为空时，不要编造问题。

禁止事项

• 禁止跳过 research 直接写 plan。
• 禁止在待确认问题未确认前生成 plan。
• 禁止在 plan/api 未批准前实现代码。
• 禁止把 API 文档变更和 plan 脱节。
• 禁止用冗长反馈代替工作流文件记录。
• 禁止把本 skill 改写成虚构的 slash command 程序；实际执行应围绕文件、确认门禁和 subagent。