subagent-driven-development

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Subagent-Driven Development Skill

Subagent驱动式开发技能

Operator Context

操作者上下文

This skill operates as an operator for plan execution workflows, configuring Claude's behavior for disciplined task dispatch with mandatory quality gates. It implements the Controller-Worker architectural pattern -- controller extracts context, workers execute in isolation, reviewers verify -- with Two-Stage Review ensuring both ADR compliance and code quality.

本技能作为计划执行工作流的操作者，配置Claude的行为以实现带强制质量关卡的规范化任务调度。它采用Controller-Worker架构模式——控制器提取上下文，工作者独立执行，审核者进行验证——并通过两阶段审核确保ADR合规性与代码质量。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

CLAUDE.md Compliance: Read and follow repository CLAUDE.md before executing any task
Over-Engineering Prevention: Implement only what the ADR requires. No speculative improvements, no "while I'm here" changes
ADR Compliance Before Quality: NEVER run code quality review before ADR compliance passes
Full Context Injection: NEVER make a subagent read the plan file; provide full task text in the dispatch
Review Gates Mandatory: NEVER mark a task complete until both reviews pass
Sequential Tasks Only: NEVER dispatch multiple implementation subagents in parallel (causes file conflicts)
BASE_SHA Capture: Run
```
git rev-parse HEAD
```
BEFORE dispatching the first implementer

CLAUDE.md合规性：执行任何任务前，阅读并遵循仓库中的CLAUDE.md
防止过度设计：仅实现ADR要求的内容。不进行投机性改进，不添加“顺便做的”变更
ADR合规优先于质量：在ADR合规性审核通过前，绝不进行代码质量审核
完整上下文注入：绝不让子代理读取计划文件；在调度时提供完整的任务文本
审核关卡强制要求：在两阶段审核均通过前，绝不标记任务完成
仅支持顺序任务：绝不并行调度多个实现子代理（会导致文件冲突）
BASE_SHA捕获：在调度第一个实现子代理前，执行
```
git rev-parse HEAD
```
命令

Default Behaviors (ON unless disabled)

默认行为（默认启用，可关闭）

Fresh Subagent Per Task: Each task gets a clean subagent with no cross-task context pollution
Scene-Setting Context: Gather branch status, code patterns, and conventions before dispatch
Q&A Before Implementation: Answer subagent questions before they start coding
Review Fix Loops: When reviewer finds issues, implementer fixes and reviewer re-reviews
Max 3 Review Retries: Escalate to user after 3 failed review cycles per stage
Final Integration Review: After all tasks, dispatch a holistic reviewer for the full changeset
TodoWrite Tracking: Create TodoWrite with all tasks upfront for progress visibility

单任务分配独立新子代理：每个任务分配一个全新的子代理，避免跨任务上下文污染
场景上下文收集：在调度前收集分支状态、代码模式与约定
实施前问答环节：子代理开始编码前，先解答其疑问
审核修复循环：当审核者发现问题时，由实现者修复后重新提交审核
最多3次审核重试：每个阶段的审核重试超过3次后，升级至用户处理
最终集成审核：所有任务完成后，调度审核者对完整变更集进行整体审核
TodoWrite进度跟踪：提前创建TodoWrite记录所有任务，便于进度可视化

Optional Behaviors (OFF unless enabled)

可选行为（默认禁用，可开启）

Parallel Research: Pre-gather codebase context for all tasks in parallel before execution
Auto PR Creation: Run pr-sync automatically after final review passes
Custom Reviewer Prompts: Override default reviewer prompt templates

并行调研：执行前并行收集所有任务的代码库上下文
自动创建PR：最终审核通过后自动运行
```
pr-sync
```
命令
自定义审核者提示词：覆盖默认的审核者提示词模板

What This Skill CAN Do

本技能可实现的功能

Execute multi-task plans with quality gates between each task
Dispatch fresh subagents that implement, test, and commit independently
Enforce ADR compliance before allowing code quality review
Escalate to user when review loops exceed retry limits
Track progress across tasks with TodoWrite

执行带任务间质量关卡的多任务计划
调度独立子代理完成任务的实现、测试与提交
强制在代码质量审核前完成ADR合规性审核
当审核循环超过重试次数时，自动升级至用户处理
通过TodoWrite跟踪多任务进度

What This Skill CANNOT Do

本技能不可实现的功能

Execute without an existing implementation plan (use workflow-orchestrator first)
Run tasks in parallel (file conflicts make this unsafe)
Skip either stage of the two-stage review
Fix review issues itself (the implementer subagent must fix)
Replace user judgment on ADR ambiguity (escalates instead)

无现成实施计划时无法执行（需先使用workflow-orchestrator）
无法并行执行任务（文件冲突风险高）
无法跳过两阶段审核中的任意一个
无法自行修复审核发现的问题（需由实现子代理修复）
无法替代用户对ADR歧义的判断（会升级至用户处理）

Instructions

操作说明

Phase 1: SETUP

阶段1：设置

Goal: Extract all tasks and establish project context before any implementation begins.

Step 1: Read plan and extract tasks

Read the plan file ONCE. Extract every task with full text:

markdown

undefined

目标：提取所有任务并建立项目上下文，为后续实施做准备。

步骤1：读取计划并提取任务

仅读取一次计划文件。提取所有任务的完整文本：

markdown

undefined

Tasks Extracted from Plan

从计划中提取的任务

Task 1: [Title] Full text: [Complete task description from plan] Files: [List of files to create/modify] Verification: [How to verify this task]

Task 2: [Title] ...


**Step 2: Create TodoWrite**

Create TodoWrite with ALL tasks:

[pending] Task 1: [Title]
[pending] Task 2: [Title]
[pending] Task 3: [Title]


**Step 3: Gather scene-setting context**
- Current branch status (`git status`)
- Capture BASE_SHA: `git rev-parse HEAD`
- Relevant existing code patterns
- Project conventions from CLAUDE.md
- Dependencies and setup requirements

This context gets passed to EVERY subagent.

**Gate**: All tasks extracted with full text. BASE_SHA captured. Scene-setting context gathered. Proceed only when gate passes.

任务1：[标题] 完整文本：[来自计划的完整任务描述] 文件：[需创建/修改的文件列表] 验证方式：[任务验证方法]

任务2：[标题] ...


**步骤2：创建TodoWrite**

创建包含所有任务的TodoWrite：

[pending] 任务1：[标题]
[pending] 任务2：[标题]
[pending] 任务3：[标题]


**步骤3：收集场景上下文**
- 当前分支状态（`git status`）
- 捕获BASE_SHA：执行`git rev-parse HEAD`命令
- 相关现有代码模式
- 来自CLAUDE.md的项目约定
- 依赖项与设置要求

该上下文将传递给**所有**子代理。

**关卡要求**：所有任务的完整文本已提取，BASE_SHA已捕获，场景上下文已收集。仅当满足要求时方可进入下一阶段。

Phase 2: EXECUTE (Per-Task Loop)

阶段2：执行（单任务循环）

Goal: Implement each task with a fresh subagent, then verify through two-stage review.

Step 1: Mark task in_progress

Update TodoWrite status for the current task.

Step 2: Dispatch implementer subagent

Use the Task tool with the prompt template from

./implementer-prompt.md

. Include:

Full task text (NEVER say "see plan")
Scene-setting context
Clear deliverables
Permission to ask questions

If the implementer asks questions: answer clearly and completely. Provide additional context. Re-dispatch with answers. Do NOT rush them into implementation.

The implementer MUST:

Understand the task fully
Ask questions if unclear (BEFORE implementing)
Implement following TDD where appropriate
Run tests
Self-review code
Commit changes

Step 3: Dispatch ADR compliance reviewer subagent

Use the prompt template from

./adr-reviewer-prompt.md

. The ADR compliance reviewer checks:

Does implementation match the ADR EXACTLY?
Is anything MISSING from requirements?
Is anything EXTRA that was not requested?

If ADR compliance reviewer finds issues: dispatch new implementer subagent with fix instructions. ADR compliance reviewer reviews again. Repeat until ADR compliance passes.

Max retries: 3 -- After 3 failed ADR compliance reviews, STOP and escalate:

"ADR compliance failing after 3 attempts. Issues: [list]. Need human decision."

Step 4: Dispatch code quality reviewer subagent

Use the prompt template from

./code-quality-reviewer-prompt.md

. The code quality reviewer checks:

Code is well-structured
Tests are meaningful
Error handling is appropriate
No obvious bugs

If quality reviewer finds issues: implementer fixes Critical and Important issues (Minor issues are optional). Quality reviewer reviews again.

Max retries: 3 -- After 3 failed quality reviews, STOP and escalate:

"Quality review failing after 3 attempts. Issues: [list]. Need human decision."

Step 5: Mark task complete

Only when BOTH reviews pass:

Task [N]: [Title] -- COMPLETE
  ADR compliance: PASS
  Code quality: PASS

Return to Step 1 for the next task.

Gate: Both ADR compliance and code quality reviews pass. Task marked complete in TodoWrite. Proceed only when gate passes.

目标：为每个任务分配独立子代理完成实现，然后通过两阶段审核验证。

步骤1：标记任务为进行中

更新TodoWrite中当前任务的状态。

步骤2：调度实现子代理

使用Task工具，调用

./implementer-prompt.md

中的提示词模板。需包含：

完整任务文本（绝不使用“详见计划”此类表述）
场景上下文
明确的交付物要求
允许子代理提出疑问

如果实现子代理提出疑问：清晰完整地解答所有问题，提供额外上下文，附带答案重新调度。绝不催促其开始实施。

实现子代理必须完成以下操作：

完全理解任务要求
如有疑问，在开始实施前提出
酌情遵循TDD（测试驱动开发）模式实现
运行测试
自行审核代码
提交变更

步骤3：调度ADR合规性审核子代理

使用

./adr-reviewer-prompt.md

中的提示词模板。ADR合规性审核者将检查：

实现是否完全符合ADR要求？
是否遗漏了任何需求？
是否添加了未被要求的额外内容？

如果ADR合规性审核者发现问题：调度新的实现子代理并提供修复说明，由ADR合规性审核者重新审核。重复此过程直至ADR合规性审核通过。

最大重试次数：3次——若ADR合规性审核3次未通过，立即停止并升级至用户：

"ADR合规性审核3次未通过。问题：[列表]。需人工决策。"

步骤4：调度代码质量审核子代理

使用

./code-quality-reviewer-prompt.md

中的提示词模板。代码质量审核者将检查：

代码结构是否清晰
测试是否有意义
错误处理是否得当
无明显bug

如果质量审核者发现问题：实现子代理需修复严重与重要问题（次要问题可选修复），然后由质量审核者重新审核。

最大重试次数：3次——若质量审核3次未通过，立即停止并升级至用户：

"质量审核3次未通过。问题：[列表]。需人工决策。"

步骤5：标记任务为已完成

仅当两阶段审核均通过时，执行：

任务[N]：[标题] -- 已完成
  ADR合规性：通过
  代码质量：通过

返回步骤1处理下一个任务。

关卡要求：ADR合规性与代码质量审核均通过，任务在TodoWrite中标记为已完成。仅当满足要求时方可进入下一任务。

Phase 3: FINALIZE

阶段3：收尾

Goal: Verify the full implementation works together and complete the workflow.

Step 1: Final integration review

Dispatch a reviewer subagent for the entire changeset (diff from BASE_SHA to HEAD):

All tests pass together
No integration issues between tasks
No conflicting patterns or redundant code

Step 2: Complete development workflow

Use the appropriate completion path:

```
/pr-sync
```
to create PR
Manual merge
Keep branch for further work

Gate: Final review passes. All tests pass. Integration verified. Proceed only when gate passes.

目标：验证完整实现的协同工作能力，完成工作流。

步骤1：最终集成审核

调度审核子代理对完整变更集（从BASE_SHA到HEAD的差异）进行审核：

所有测试可协同通过
任务间无集成问题
无冲突模式或冗余代码

步骤2：完成开发工作流

选择合适的完成路径：

执行
```
/pr-sync
```
创建PR
手动合并
保留分支用于后续开发

关卡要求：最终审核通过，所有测试通过，集成验证完成。仅当满足要求时方可完成工作流。

Error Handling

错误处理

Error: "Subagent Asks Questions Mid-Implementation"

错误：子代理在实施过程中提出疑问

Cause: Insufficient context in the dispatch prompt Solution:

Answer all questions clearly and completely
Add the missing context to the scene-setting for future tasks
Re-dispatch implementer with answers included

原因：调度提示词中上下文不足解决方案：

清晰完整地解答所有疑问
将缺失的上下文添加到后续任务的场景上下文中
附带答案重新调度实现子代理

Error: "Review Loop Exceeds 3 Retries"

错误：审核循环超过3次重试

Cause: ADR ambiguity, fundamental misunderstanding, or unreasonable review criteria Solution:

STOP the loop immediately
Summarize all issues and attempted fixes for the user
Ask user to clarify ADR or adjust requirements
Resume only after user provides direction

原因：ADR存在歧义、理解偏差或审核标准不合理解决方案：

立即停止循环
向用户汇总所有问题与已尝试的修复方案
请求用户澄清ADR或调整需求
仅在用户提供指导后恢复执行

Error: "Subagent File Conflicts"

错误：子代理文件冲突

Cause: Multiple subagents modifying overlapping files (usually from parallel dispatch) Solution:

Resolve conflicts manually
Re-run the affected review stage
Enforce sequential dispatch going forward -- NEVER parallelize implementers

原因：多个子代理修改重叠文件（通常由并行调度导致）解决方案：

手动解决冲突
重新运行受影响的审核阶段
后续严格执行顺序调度——绝不并行调度实现子代理

Anti-Patterns

反模式

Anti-Pattern 1: Skipping ADR Compliance Review for "Obvious" Tasks

反模式1：为“显而易见”的任务跳过ADR合规性审核

What it looks like: "This task is straightforward, code quality review is enough" Why wrong: Even simple tasks can miss requirements or add unrequested scope Do instead: Run both review stages for every task. No exceptions.

表现：“这个任务很简单，代码质量审核就够了” 问题所在：即使简单任务也可能遗漏需求或添加未被要求的内容 正确做法：为每个任务运行两阶段审核，无例外。

Anti-Pattern 2: Controller Fixing Issues Directly

反模式2：控制器直接修复问题

What it looks like: Controller edits code instead of dispatching a fix subagent Why wrong: Pollutes controller context. Controller should orchestrate, not implement. Do instead: Dispatch a new implementer subagent with specific fix instructions.

表现：控制器直接编辑代码，而非调度修复子代理 问题所在：污染控制器上下文。控制器应负责编排，而非实现。 正确做法：调度新的实现子代理并提供具体的修复说明。

Anti-Pattern 3: Bundling Multiple Tasks Into One Subagent

反模式3：将多个任务捆绑分配给单个子代理

What it looks like: "Tasks 2 and 3 are related, I'll combine them" Why wrong: Defeats isolation. Review becomes unclear. Rollback is impossible. Do instead: One task per subagent. Always.

表现：“任务2和3相关，我把它们合并” 问题所在：破坏隔离性，审核变得模糊，无法回滚单个任务。 正确做法：始终为每个任务分配独立子代理。

Anti-Pattern 4: Proceeding With Unresolved Questions

反模式4：带着未解决的疑问继续执行

What it looks like: "The subagent will figure it out from the code" Why wrong: Subagent builds the wrong thing. Review catches it late. Wasted cycles. Do instead: Answer every question before implementation begins.

表现：“子代理会从代码中自行理解” 问题所在：子代理实现错误内容，审核后期才发现，浪费时间。 正确做法：在开始实施前解答所有疑问。

References

参考资料

This skill uses these shared patterns:

Anti-Rationalization - Prevents shortcut rationalizations
Verification Checklist - Pre-completion checks

本技能使用以下共享模式：

反合理化 - 防止找借口走捷径
验证清单 - 完成前检查

Domain-Specific Anti-Rationalization

领域特定反合理化

Rationalization	Why It's Wrong	Required Action
"This task is simple, skip ADR review"	Simple tasks still miss requirements	Run both review stages
"Subagent can read the plan itself"	File reading wastes tokens, context pollution	Provide full task text in dispatch
"Reviews passed, skip final integration check"	Per-task reviews miss cross-task issues	Run final integration review
"I'll fix this small issue myself instead of dispatching"	Controller context pollution breaks orchestration	Dispatch fix subagent
"Tasks 2 and 3 are related, combine them"	Combined tasks break isolation and review clarity	One task per subagent, always

合理化借口	问题所在	要求操作
“这个任务很简单，跳过ADR审核”	简单任务仍可能遗漏需求	运行两阶段审核
“子代理可以自行读取计划”	文件读取浪费Token，导致上下文污染	在调度时提供完整任务文本
“审核已通过，跳过最终集成检查”	单任务审核无法发现跨任务问题	运行最终集成审核
“我自己修复这个小问题，不调度子代理”	控制器上下文污染破坏编排逻辑	调度修复子代理
“任务2和3相关，合并它们”	合并任务破坏隔离性与审核清晰度	始终为每个任务分配独立子代理

Prompt Templates

提示词模板

```
implementer-prompt.md
```
: Dispatch template for implementation subagents
```
adr-reviewer-prompt.md
```
: Dispatch template for ADR compliance review
```
code-quality-reviewer-prompt.md
```
: Dispatch template for code quality review

```
implementer-prompt.md
```
：实现子代理的调度模板
```
adr-reviewer-prompt.md
```
：ADR合规性审核子代理的调度模板
```
code-quality-reviewer-prompt.md
```
：代码质量审核子代理的调度模板