autonomous-dev

TDD 开发工作流

一套完整的开发工作流，严格执行测试驱动开发、Git 工作树隔离、代码审查、CI 验证和 E2E 测试。支持两种模式：交互模式（默认），用于由人工引导的会话；以及自主模式，用于全程无人值守地实现 GitHub issue。

不可妥协的规则——每个标记为 MANDATORY 的步骤都必须执行。 不要跳过、推迟这些步骤，也不要询问用户是否运行这些步骤。请将它们作为工作流的一部分自动执行。包括创建 PR、等待 CI、运行 E2E 测试，以及处理审查者提出的问题。

---

模式检测

交互模式（默认）

开发者在场时使用。工作流将：

• 在开始实施前询问用户是否批准设计
• 展示设计画布并等待反馈
• 在关键决策点暂停，等待用户输入
• 汇报最终状态，由用户决定何时合并

自主模式

在 scripts/autonomous-dev.sh 包装脚本中运行时触发。工作流将：

• 自主做出所有决策（请参阅下文的“决策制定指南”）
• 向 GitHub issue 发布进度评论，而不是提问
• 创建设计文档，但跳过交互式审批
• 在验证后停止——不进行合并（由审查 Agent 负责）
• 随工作进展，在 issue 正文中勾选需求复选框

---

跨平台说明

此技能适用于支持 skills.sh 的 IDE。请将本文档中的通用动词映射到你的 IDE 工具（Claude Code 的 Bash → Cursor 中的终端等）。基于 Hook 的强制执行适用于 Claude Code、Codex CLI 和 Kiro CLI；对于未安装 Hook 的客户端，请手动遵循各个步骤——要求保持不变。

完整的 IDE 表格和动词到工具的映射请参阅 references/cross-platform.md。

---

开发工作流概览

所有功能开发和 Bug 修复都遵循此工作流：

Step 1:  DESIGN CANVAS (Pencil MCP, if available)
Step 2:  CREATE GIT WORKTREE (MANDATORY)
Step 3:  WRITE TEST CASES (TDD)
Step 4:  IMPLEMENT CHANGES
Step 5:  LOCAL VERIFICATION
Step 6:  CODE SIMPLIFICATION
Step 7:  COMMIT AND CREATE PR          -- MANDATORY
Step 8:  PR REVIEW AGENT               -- MANDATORY
Step 9:  WAIT FOR ALL CI CHECKS        -- MANDATORY
Step 10: ADDRESS REVIEWER BOT FINDINGS -- MANDATORY
Step 11: ITERATE UNTIL NO BLOCKING FINDINGS
Step 12: E2E TESTS & READY FOR MERGE   -- MANDATORY
Step 13: CLEANUP WORKTREE

---

第 1 步：设计画布

对于新的 UI 工作、面向用户的功能、架构决策和复杂数据流，请创建设计画布。对于不会改变行为的简单修复或重构，可跳过此步骤。

• 支持 Pencil MCP 的 IDE：创建 docs/designs/<feature>.pen。
• 不支持 Pencil MCP 的 IDE：创建 docs/designs/<feature>.md。

完整的 Pencil MCP 调用顺序、Markdown 画布模板，以及按模式（交互模式与自主模式）划分的审批关卡，请参阅 references/design-canvas.md。

---

第 2 步：创建 Git 工作树（MANDATORY）

每项变更都必须在隔离的 Git 工作树中开发。切勿直接在主工作区中开发。

如果安装了 Hook，则由 block-commit-outside-worktree.sh Hook 强制执行。工作树之外的提交会被自动阻止。block-push-to-main.sh 会阻止直接推送到 main。

为什么要使用工作树？

• 隔离：每项功能或修复都拥有自己的目录，避免交叉影响
• 并行工作：可以同时开展多项功能
• 保持主工作区干净：主检出始终位于 main，随时可进行快速检查
• 安全回滚：丢弃工作树不会影响主工作区

创建工作树的流程

在终端中执行：

# 1. Determine branch name based on change type
#    feat/<name>, fix/<name>, refactor/<name>, etc.
BRANCH_NAME="feat/my-feature"

# 2. Create worktree with new branch from main
git worktree add .worktrees/$BRANCH_NAME -b $BRANCH_NAME

# 3. Enter the worktree
cd .worktrees/$BRANCH_NAME

# 4. Install dependencies (use your project's package manager)
npm install  # or: bun install, yarn install, pnpm install

# 5. Verify clean baseline
npm run build && npm test

目录约定

项目	值
工作树根目录	.worktrees/（项目本地，已加入 gitignore）
路径格式	.worktrees/<branch-name>
示例	.worktrees/feat/user-authentication

安全检查

创建任何工作树之前，请确认 .worktrees/ 已加入 .gitignore：

git check-ignore -q .worktrees 2>/dev/null || echo "WARNING: .worktrees not in .gitignore!"

后续所有步骤均在工作树内执行

创建工作树后，所有开发命令（测试、lint、构建、提交、推送）都在工作树目录内执行。清理前不会触碰主工作区。

进行交互式工作时，可先使用通用技能的 scripts/session-knowledge.sh begin 开始知识评估（适用时使用 --task issue-<N>）。 自主执行的包装器会自动开始评估。交接前，评估并记录新验证的事实，或说明无需更新的原因；阅读 ../autonomous-common/references/session-knowledge.md。 Stop 钩子会检查是否完成评估，但不会要求记录经验或更新文件。

---

第 3 步：编写测试用例（TDD）

编写任何实现代码之前：

1. 阅读设计画布和需求
2. 确定所有用户场景、边界情况和错误处理路径
3. 创建或编辑测试用例文档：docs/test-cases/<feature>.md
   • 列出所有测试场景（正常路径、边界情况、错误处理）
   • 分配测试 ID（例如，TC-AUTH-001）
   • 定义预期结果和验收标准
4. 创建单元测试框架
5. 如适用，创建 E2E 测试用例

---

第 4 步：实现变更

• 按照测试用例编写代码（在工作树内）
• 为新功能编写新的单元测试
• 如果行为发生变化，更新现有测试
• 确保实现覆盖所有测试场景

---

第 5 步：本地验证

在首次推送前以及修复阻塞问题后，先在本地运行可行的检查。 阅读仓库的测试命令和 CI 配置。先运行有针对性的回归测试，然后运行相关的 lint、类型检查、构建和集成检查。 共享行为发生变化或仓库策略要求时，运行范围更广的测试套件。CI 用于确认候选版本；对于可在本地运行的检查，不应首次尝试就放在 CI 中。 对于仅涉及文档的变更，应运行相关的文档和工作流检查，而不是无关的应用构建。

在 PR 测试计划中记录命令、退出状态、测试的修订版本/目录树和覆盖范围。如果凭据、服务或工具导致无法在本地执行某项检查，请记录具体限制，并将该检查留待 CI 执行。切勿将未运行的检查报告为已通过。仅当输入和环境未变时，才可复用成功的验证结果；修复后，重新运行受影响的检查，并仅在影响范围需要时扩大检查范围。

Node 项目示例（请使用项目实际的命令）：

timeout 1800 bash -lc 'npm run build && npm run test' > /tmp/verify.log 2>&1; rc=$?; [ $rc -ne 0 ] && tail -100 /tmp/verify.log; exit $rc

继续之前先修复本地检查失败的问题。在可行时运行本地功能/E2E 检查；仅当项目要求且授权时才执行部署。

如何运行耗时较长的验证

运行项目的构建/测试套件时，使用一条同步命令并设置充足的超时时间——绝不要将其放入后台，然后在不同轮次间轮询：

1. 使用明确且充足的超时时间，同步运行顶层套件命令。 使用一次阻塞调用（或少数几次顺序执行的阻塞调用，例如先构建再测试），并在本轮中返回完整结果。捕获输出，仅在失败时回显末尾部分：

   timeout 1800 bash -lc '<your project's build & test command>' > /tmp/verify.log 2>&1; rc=$?; [ $rc -ne 0 ] && tail -100 /tmp/verify.log; exit $rc
   

2. 绝不要将顶层套件放入后台（不要使用 & 或后台任务模式——无论宿主 CLI 如何称呼，例如 run_in_background），然后跨 Agent 轮次轮询其日志。每次轮询都会产生一次完整的模型往返；累积的轮询开销可能比套件本身的运行时间高出多个数量级。
3. 如果工具的最大超时时间确实不足以覆盖套件运行时间，请按目录/前缀拆分为少数几次顺序执行的同步调用——仍然不要轮询。
4. 如果项目提供了并行运行器，优先使用。

范围：此禁令针对的是将顶层验证命令放入后台。测试/脚本内部启动的子进程或本地服务不受影响；真正由事件驱动的等待也不受影响（第 9 步中的 CI 检查、第 10-11 步中的机器人评审）。

步骤 6：简化代码

1. 使用能力最强的原生选项，独立进行一轮简化审查：
   • Codex CLI：请 Codex 启动一个原生审查子 Agent，重点检查不必要的复杂性、重复内容和仓库规范。子 Agent 仅提供建议；由主会话应用任何更改。
   • Claude Code：如果已安装插件，请使用 code-simplifier:code-simplifier。
   • 其他客户端：使用可用的审查子 Agent，或手动执行同样的审查。
2. 根据下方的阻塞策略对建议进行分类。命名、风格和可选重构仅供参考；仅在当前范围内确有帮助时才应用。 不要仅为消除参考性意见而开启新一轮审查。
3. 同一个独立审查者可以在一轮中同时审查代码简化和步骤 8 的正确性。记录两项结果；无需对相同代码再进行一轮完整差异审查。编辑后，审查修复内容及受影响的契约。
4. 标记为已完成（如果已安装钩子）：

   hooks/state-manager.sh mark code-simplifier
   

---

步骤 7：提交并创建 PR（必须）

首次推送前，先完成步骤 8 的独立审查。集中处理相关的阻塞问题，完成本地验证，然后只推送一次已验证的候选版本。对于未发生变更的提交，在最终未提交的代码树上进行的审查仍然有效。

提交

在终端中执行：

git add <files>
git commit -m "type(scope): description"
git push -u origin <branch-name>

创建 PR

GitHub 流程（CODE_HOST=github）——以下示例使用 GitHub CLI。在 GitLab 流程中，封装器通过 chp_create_pr 提供方接口创建合并请求；Agent 不会自行编写平台 API 调用。如果必须直接调用 CLI，请替换为 glab mr create --title … --description …。

gh pr create --title "type(scope): description" --body "$(cat <<'EOF'
## Summary
<1-3 bullet points describing the change>

## Design
- [ ] Design canvas created (`docs/designs/<feature>.pen`)
- [ ] Design approved

## Test Plan
- [ ] Test cases documented (`docs/test-cases/<feature>.md`)
- [ ] Build passes (`npm run build`)
- [ ] Unit tests pass (`npm run test`)
- [ ] CI checks pass
- [ ] Code simplification review passed
- [ ] PR review agent review passed
- [ ] Blocking bot findings resolved; advisory findings recorded
- [ ] E2E tests pass

## Checklist
- [ ] New unit tests written for new functionality
- [ ] E2E test cases updated if needed
- [ ] Documentation updated if needed
EOF
)"

更新 PR 检查清单

完成每个步骤后，更新 PR/MR 描述。获取当前正文，将相应项目标记为 [x]，然后写回。

# GitHub lane (CODE_HOST=github):
gh pr view {pr_number} --json body --jq '.body' > /tmp/pr_body.md
# Edit the checklist (mark items as [x])
gh pr edit {pr_number} --body "$(cat /tmp/pr_body.md)"

# GitLab lane (CODE_HOST=gitlab):
glab mr view {mr_number} -F json | jq -r .description > /tmp/pr_body.md
# Edit the checklist (mark items as [x])
glab mr update {mr_number} --description "$(cat /tmp/pr_body.md)"

---

步骤 8：PR 审查 Agent（必须）

在步骤 7 首次推送前完成此审查。如果步骤 6 已对同一代码树进行过独立的正确性审查，则复用该结果。之后的审查应验证修复内容和受影响的行为；只有在变更或新证据确有必要时，才重复完整差异审查。

1. 进行独立的开发侧审查：
   • Codex CLI：使用原生审查子 Agent；或者在首次提交前运行 codex review --uncommitted，并对已提交分支差异运行 codex review --base <base-branch>。
   • Claude Code：如果已安装插件，请使用 /pr-review-toolkit:review-pr。
   • 其他客户端：使用可用的审查 Agent，或手动审查完整差异。
2. 遵循 autonomous.conf 或封装器交付策略中的 REVIEW_BLOCKING_SEVERITY。默认值 P1 要求修复第一轮中的 P0/P1 问题。 P2 和 P3 选择固定的、更严格的阈值；adaptive 则沿用旧阈值：第 1–2 轮为 P3，第 3–4 轮为 P2，第 5 轮及之后为 P1。无效值将触发警告并采用严格的 P3。推迟处理未标注级别的正确性问题前，先对其进行分类。P0/P1、强制验收标准、安全控制、未通过的必要检查以及合并门禁始终属于阻塞项。严重级别应反映已证实的影响，而非清理偏好。 将较低严重级别的问题记录为参考意见，无需修改代码。
3. 标记为已完成（如果已安装钩子）：

   hooks/state-manager.sh mark pr-review
   

---

第 9 步：等待所有 CI 检查完成（必须执行——不得跳过）

在终端中执行。在 GitHub 流程中使用 GitHub CLI；在 GitLab 流程中使用 glab（或使用流水线的 chp_ci_status 接口，它会将两种主机的状态统一为 green/pending/failed/none）。

# GitHub lane (CODE_HOST=github):
gh pr checks {pr_number} --watch --interval 30

# GitLab lane (CODE_HOST=gitlab):
glab ci status {mr_number}   # add `--live` on newer glab for continuous updates

所有检查都必须通过：Lint、单元测试、构建、部署预览、E2E 测试。

CI 运行期间，在这些工作可以独立进行时，检查现有评审反馈并更新验证证据。使用提供方的监视命令，而不是反复读取状态。不要仅为重新触发评审而创建空提交或推送；只有在支持且适当时，才重新触发失败的作业。

如果任何检查失败：分析日志、修复、推送并重新监视。在所有检查都显示“通过”之前，不得继续。

需要监视的检查

检查	说明	失败时的操作
CI / build-and-test	构建 + 单元测试	修复代码或更新快照
Security Scan	SAST、npm audit	修复安全问题
已配置的 REVIEW_BOTS	各项目的机器人评审员（q、codex、claude、自定义项）	处理发现的问题，通过 gh-as-user.sh 重新触发
其他评审机器人	各类检查	处理发现的问题，根据各机器人的文档重新触发

---

第 10 步：处理评审机器人发现的问题（当 REVIEW_BOTS 非空时必须执行）

如果项目的 autonomous.conf 声明了 REVIEW_BOTS（以空格分隔的短名称，例如 q codex claude），请按照第 8 步的阻断策略对每个已配置机器人的发现进行分类。修复阻断问题；对于误报或建议性发现，回复一次并说明原因和严重程度。只有在记录处理结果且仓库策略允许时，才解决延后处理的建议性讨论串。不要将延后处理的发现描述为已修复。仅在相关代码发生更改或缺少必要评审时重新触发。

如果 REVIEW_BOTS=""（或未设置该变量），则完全跳过此步骤——项目不强制要求任何外部机器人评审。

内置机器人的触发方式：

短名称	触发语	机器人登录名（筛选 user.login）
q	/q review	amazon-q-developer[bot]
codex	/codex review	codex[bot]
claude	@claude review	claude[bot]

使用 scripts/gh-as-user.sh 重新触发机器人评审。 所有三个内置机器人都会拒绝由 GitHub App 机器人账号发布的触发评论；该封装脚本会以真实用户身份发布评论。

完整的重新触发命令、回复模式和讨论串解决规则，请参阅 references/review-threads.md。

---

第 11 步：迭代直至没有阻断问题

仅在仍有阻断问题时重复以下步骤：

1. 确认问题仍然存在；合并重复项，并批量修复相关问题。
2. 推送前运行受影响的本地测试，并评审变更后的行为。
3. 回复每个可采取行动的讨论串，并在记录处理结果后将其解决。
4. 必要时，针对新的候选版本重新触发受影响的已配置评审员，每位仅触发一次。
5. 使用可用的状态信号和有限轮询等待评审完成。
6. 按照相同的阈值对新发现的问题进行分类。保留可见的建议性备注，但不要仅因出现新的非阻断备注而修改代码或重新启动评审。
7. 当不存在阻断问题且所有必需检查均已满足时，继续进行。

---

第 12 步：端到端测试并准备合并（必须执行，不得跳过）

1. 在已部署的预览环境中运行所需的端到端测试。在自主模式下，如果评审封装程序负责配置的端到端测试，则在本地功能验证和所需 CI 完成后移交；封装程序会运行一次最终端到端测试，分发式评审者则使用其证据。只有在 HEAD、目标环境和所需场景覆盖范围均匹配时，才可复用现有的端到端测试证据。最终端到端测试尚未运行时，应保持待处理状态，不要标记为已完成。

2. 只有在当前候选版本的端到端测试确实通过后，才标记为已完成（如果已安装钩子）。封装程序负责的端到端测试仍待处理时，请保持此状态未设置：

   hooks/state-manager.sh mark e2e-tests
   

3. 更新 PR 检查清单，反映已完成的检查以及封装程序负责的任何待处理端到端测试

4. 到此为止：向用户报告状态（交互模式），或在 issue 上发布摘要评论（自主模式）。在自主模式下，须通过项目内置的封装程序发布，以便评论归属于配置的身份（应用模式下为机器人，令牌模式下为主机用户）：

   # GitHub lane (CODE_HOST=github):
   bash scripts/gh issue comment <ISSUE_NUMBER> --body "<summary>"
   

   不要直接调用 gh issue comment——Agent 的 Bash 工具无法可靠地通过封装程序注入的 PATH 解析 gh，因此直接调用会退回到系统中的 gh，并以主机操作员的身份发布评论。完整规则请参阅 references/autonomous-mode.md。

   GitLab 流程（CODE_HOST=gitlab）——同样的原则也适用：封装程序／itp_post_comment 提供程序接口会使用配置的身份发布评论。Agent 不要自行拼接 glab issue note 或 REST API；该接口会处理身份验证和身份信息。

5. 由用户或评审 Agent 决定何时合并

---

第 13 步：合并后的知识整理与清理

PR 合并或关闭后，在终端中执行：

对于已合并的 PR，在移除工作树之前，完成所有待处理的知识回写。评审封装程序会自动执行此操作。手动合并时，使用 scripts/distill-knowledge.sh --issue <N> --pr <merged-pr>；独立任务可以使用通用参考中介绍的本地 apply 构建块。有价值的变更会生成单独的文档提交／PR；如果没有新增或更正的事实，则不会生成提交。已关闭但未合并的 PR 不会发布其候选内容。

# Return to main workspace
cd $(git rev-parse --show-toplevel)

# Remove the worktree
git worktree remove .worktrees/<branch-name>

# Prune stale worktree references
git worktree prune

---

参考资料

详细命令和约定请参阅：

• references/commit-conventions.md——分支命名和提交消息约定
• references/review-commands.md——完整的 gh CLI 和 GraphQL 命令参考
• references/review-threads.md——评审线程管理、回复模式和快速参考命令
• references/autonomous-mode.md——决策、恢复意识、需求跟踪、既有变更、机器人评审集成和错误恢复（仅自主模式）