feature-plan
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseFeature Plan Skill
Feature Plan Skill
Purpose
用途
Transform a design document into a wave-ordered implementation plan with tasks assigned to domain agents. Phase 2 of the feature lifecycle (design → plan → implement → validate → release).
将设计文档转换为按阶段(Wave)排序的实现计划,并为任务分配领域Agent。这是功能生命周期的第2阶段(设计 → 规划 → 实现 → 验证 → 发布)。
Operator Context
操作规则上下文
Hardcoded Behaviors (Always Apply)
硬编码行为(始终适用)
- CLAUDE.md Compliance: Read and follow repository CLAUDE.md
- Design Doc Required: CANNOT plan without a design document in
.feature/state/design/ - State Management via Script: All state operations through
python3 ~/.claude/scripts/feature-state.py - Wave Ordering: Tasks grouped by dependency wave; Wave N must complete before Wave N+1
- Domain Agent Assignment: Every implementation task MUST specify which domain agent handles it
- Parallel Safety Analysis: Flag which tasks in the same wave can run in parallel
- CLAUDE.md 合规性:阅读并遵循仓库中的CLAUDE.md
- 必须提供设计文档:若目录下无设计文档,则无法进行规划
.feature/state/design/ - 通过脚本管理状态:所有状态操作需通过执行
python3 ~/.claude/scripts/feature-state.py - 阶段排序:任务按依赖关系分为不同阶段;必须完成第N阶段才能开始第N+1阶段
- 领域Agent分配:每个实现任务必须指定由哪个领域Agent负责
- 并行安全分析:标记同一阶段中可并行执行的任务
Default Behaviors (ON unless disabled)
默认行为(默认开启,可关闭)
- Context Loading: Read L0, L1, and design artifact at prime
- Task Duration Targeting: Each task scoped to 2-5 minutes of agent work
- File Conflict Detection: Detect tasks that modify the same files and sequence them
- 上下文加载:初始化时读取L0、L1及设计工件
- 任务时长目标:每个任务的Agent工作时长控制在2-5分钟
- 文件冲突检测:检测修改同一文件的任务并调整执行顺序
Optional Behaviors (OFF unless enabled)
可选行为(默认关闭,需开启)
- Auto-approve plan: Skip human approval gate
- 自动批准计划:跳过人工审批环节
What This Skill CAN Do
本Skill可实现的功能
- Read design documents and decompose into tasks
- Assign domain agents from our system to each task
- Detect file conflicts and resequence waves
- Produce structured plan artifacts
- 读取设计文档并拆解为任务
- 为每个任务分配系统中的领域Agent
- 检测文件冲突并调整阶段顺序
- 生成结构化的计划工件
What This Skill CANNOT Do
本Skill无法实现的功能
- Create plans without a design document
- Implement code (that's feature-implement)
- Skip plan approval gate without configuration
- Override domain agent routing
- 无设计文档时创建计划
- 编写代码(该功能由feature-implement负责)
- 未配置时跳过计划审批环节
- 覆盖领域Agent的路由规则
Instructions
操作说明
Phase 0: PRIME
阶段0:PRIME
-
Check feature state:bash
python3 ~/.claude/scripts/feature-state.py status FEATUREVerify current phase isandplanis in completed phases.design -
Load design artifact:bash
ls .feature/state/design/*-FEATURE.mdRead the design document. -
Load L1 plan context:bash
python3 ~/.claude/scripts/feature-state.py context-read FEATURE L1 --phase plan
Gate: Design doc loaded. Feature in plan phase. Proceed.
-
检查功能状态:bash
python3 ~/.claude/scripts/feature-state.py status FEATURE验证当前阶段为且plan阶段已完成。design -
加载设计工件:bash
ls .feature/state/design/*-FEATURE.md读取设计文档。 -
加载L1规划上下文:bash
python3 ~/.claude/scripts/feature-state.py context-read FEATURE L1 --phase plan
准入条件:已加载设计文档,且功能处于规划阶段。方可继续。
Phase 1: EXECUTE (Task Decomposition)
阶段1:执行(任务拆解)
Step 1: Identify Components
From the design document, extract:
- Components to build/modify
- Dependencies between components
- Domain agents assigned in design
Step 2: Create Wave-Ordered Tasks
Group tasks by dependency wave:
markdown
undefined步骤1:识别组件
从设计文档中提取:
- 需要构建/修改的组件
- 组件间的依赖关系
- 设计阶段分配的领域Agent
步骤2:创建按阶段排序的任务
按依赖关系将任务分组为不同阶段:
markdown
undefinedImplementation Plan: [Feature Name]
实现计划:[功能名称]
Wave 1 (no dependencies)
Wave 1(无依赖)
T1: [Task title]
T1: [任务标题]
- Agent: golang-general-engineer
- Duration: 3 min
- Files: /absolute/path/to/file.go
- Operations: [specific changes]
- Verification: exits 0
go build ./... - Parallel-safe: true (no file conflicts with T2)
- Agent: golang-general-engineer
- Duration: 3 min
- Files: /absolute/path/to/file.go
- Operations: [具体修改内容]
- Verification: 执行返回0
go build ./... - Parallel-safe: true(与T2无文件冲突)
T2: [Task title]
T2: [任务标题]
- Agent: typescript-frontend-engineer
- Duration: 4 min
- Files: /absolute/path/to/component.tsx
- Operations: [specific changes]
- Verification: exits 0
npm run typecheck - Parallel-safe: true
- Agent: typescript-frontend-engineer
- Duration: 4 min
- Files: /absolute/path/to/component.tsx
- Operations: [具体修改内容]
- Verification: 执行返回0
npm run typecheck - Parallel-safe: true
Wave 2 (depends on Wave 1)
Wave 2(依赖Wave 1)
T3: [Task title]
T3: [任务标题]
- Agent: golang-general-engineer
- Dependencies: T1
- Duration: 5 min
- Files: /absolute/path/to/handler.go
- Operations: [specific changes]
- Verification: exits 0
go test ./... - Parallel-safe: false (shares files with T4)
**Step 3: File Conflict Analysis**
For each wave, check if any two tasks modify the same files:
- If yes: mark `Parallel-safe: false` and add ordering constraint
- If no: mark `Parallel-safe: true`
**Step 4: Agent Routing Verification**
For each task, verify the assigned agent exists in our system:
- Check against known agent triggers
- If uncertain, default to the closest domain agent
- Log routing decisions
**Step 5: Define Goal-Backward Success Criteria**
Before moving to validation, define "What must be TRUE when this is complete?" as **observable behaviors**, not implementation tasks. Success criteria are the verification target — they define *when you're done*. Implementation tasks define *how you get there*. Conflating the two means "all tasks complete" can diverge from "goal achieved."
Each plan MUST include a `## Success Criteria` section with observable outcomes:
```markdown- Agent: golang-general-engineer
- Dependencies: T1
- Duration: 5 min
- Files: /absolute/path/to/handler.go
- Operations: [具体修改内容]
- Verification: 执行返回0
go test ./... - Parallel-safe: false(与T4存在文件冲突)
**步骤3:文件冲突分析**
对每个阶段,检查是否有两个任务修改同一文件:
- 若是:标记`Parallel-safe: false`并添加顺序约束
- 若否:标记`Parallel-safe: true`
**步骤4:Agent路由验证**
对每个任务,验证分配的Agent是否存在于系统中:
- 对照已知的Agent触发器进行检查
- 若不确定,默认选择最接近的领域Agent
- 记录路由决策
**步骤5:定义基于目标的反向成功标准**
进入验证阶段前,需定义「完成后必须满足哪些条件?」,且这些条件需为**可观察的行为**,而非实现任务。成功标准是验证的目标——定义了「何时完成」,而实现任务定义了「如何完成」。若混淆两者,可能出现「所有任务完成但未达成目标」的情况。
每个计划必须包含`## 成功标准`章节,列出可观察的结果:
```markdownSuccess Criteria
成功标准
<!-- What must be TRUE when this plan is fully implemented? -->
<!-- Each criterion must be observable/verifiable — not an implementation task -->
- [Observable behavior 1]
- [Observable behavior 2]
- [Observable behavior 3]
| Bad (implementation-focused) | Good (behavior-focused) |
|------------------------------|------------------------|
| "Implement resetPassword function" | "Users can reset their password via email link" |
| "Add database migration" | "The users table has a reset_token column with TTL" |
| "Write unit tests" | "All new functions have tests that pass, covering happy path and error cases" |
| "Refactor the handler" | "The /api/orders endpoint returns responses in under 200ms for 1000 concurrent users" |
| "Update the config" | "The service reads database credentials from environment variables, not hardcoded values" |
**Why behavior-focused**: An executor can complete every implementation task perfectly and still miss the goal if the tasks were wrong. Behavior-focused criteria catch that gap — they're the acceptance test for the plan itself.
**Step 6: Apply Deep Work Rules to Every Task**
Every task in the plan must satisfy three rules. These exist because vague tasks create a hidden cost: the executor spends time interpreting the task instead of executing it, asks clarifying questions that block progress, or worse — guesses wrong and builds the wrong thing.
**Rule 1: Concrete Actions Only**
No vague verbs ("align," "ensure," "handle," "improve") without specifying what concretely happens. If the task description doesn't tell the executor exactly what to do, it's not a task — it's a wish.
| Rejected (vague) | Accepted (concrete) |
|-------------------|---------------------|
| "Align the API response" | "Add `created_at` field to the API response struct and populate it from the database timestamp" |
| "Ensure error handling" | "Wrap the `fetchUser` call in try/catch, return 404 for UserNotFound, 500 for all other errors" |
| "Handle edge cases" | "Add nil-check for `user.Profile` before accessing `user.Profile.Avatar`; return default avatar URL if nil" |
| "Improve performance" | "Add database index on `orders.user_id` column; batch the N+1 query in `listOrders` into a single JOIN" |
**Rule 2: Self-Contained Execution**
The executor should be able to complete the task from the action text alone, without needing to ask clarifying questions. If a task requires context not present in the task description, that context must be added.
Test: Can a domain agent with no prior conversation context execute this task? If not, add the missing context.
**Rule 3: Observable Completion**
Each task has a way to verify it's done. If you can't describe how to check whether the task is complete, the task is too vague.
| Verifiable | Not Verifiable |
|------------|----------------|
| "Add route to router" — check route table | "Improve code quality" — no measurable criterion |
| "Add `user_id` column to orders table" — check schema | "Clean up the module" — what does "clean" mean? |
| "Return 429 when rate limit exceeded" — test with curl | "Make it more robust" — robust against what? |
**Gate**: Tasks decomposed with waves, agents, parallel safety flags, success criteria defined, and all tasks pass deep work rules.<!-- 本计划完全实现后必须满足哪些条件? -->
<!-- 每条标准必须可观察/可验证——而非实现任务 -->
- [可观察行为1]
- [可观察行为2]
- [可观察行为3]
| 错误示例(聚焦实现) | 正确示例(聚焦行为) |
|------------------------------|------------------------|
| "实现resetPassword函数" | "用户可通过邮件链接重置密码" |
| "添加数据库迁移脚本" | "users表包含带TTL的reset_token字段" |
| "编写单元测试" | "所有新函数的测试均通过,覆盖正常流程和异常场景" |
| "重构处理器" | "/api/orders端点在1000并发用户下响应时间小于200ms" |
| "更新配置文件" | "服务从环境变量读取数据库凭证,而非硬编码值" |
**为何聚焦行为**:执行者可能完美完成所有实现任务,但如果任务本身存在偏差,仍无法达成目标。聚焦行为的标准可发现这种偏差——它是对计划本身的验收测试。
**步骤6:为所有任务应用深度工作规则**
计划中的每个任务必须满足三条规则。模糊的任务会产生隐性成本:执行者需花费时间解读任务、提出澄清问题,甚至可能误解需求而构建错误内容。
**规则1:仅包含具体操作**
禁止使用模糊动词(如「对齐」「确保」「处理」「优化」)而不说明具体操作。若任务描述未明确告知执行者具体要做什么,则它不是任务,而是愿望。
| 被拒绝(模糊) | 可接受(具体) |
|-------------------|---------------------|
| "对齐API响应" | "为API响应结构体添加`created_at`字段,并从数据库时间戳中填充值" |
| "确保错误处理" | "为`fetchUser`调用添加try/catch,UserNotFound时返回404,其他错误返回500" |
| "处理边缘情况" | "在访问`user.Profile.Avatar`前添加`user.Profile`的空值检查;若为空则返回默认头像URL" |
| "优化性能" | "为`orders.user_id`列添加数据库索引;将`listOrders`中的N+1查询批量处理为单次JOIN查询" |
**规则2:任务可独立执行**
执行者应仅通过任务描述即可完成任务,无需提出澄清问题。若任务需要描述中未包含的上下文,则必须补充该上下文。
测试标准:无对话上下文的领域Agent能否执行该任务?若不能,需补充缺失的上下文。
**规则3:完成状态可观察**
每个任务必须有验证完成的方法。若无法描述如何检查任务是否完成,则任务过于模糊。
| 可验证 | 不可验证 |
|------------|----------------|
| "为路由器添加路由" — 检查路由表 | "提升代码质量" — 无衡量标准 |
| "为orders表添加`user_id`列" — 检查数据库 schema | "清理模块" — "清理"的定义是什么? |
| "触发速率限制时返回429" — 用curl测试 | "增强健壮性" — 针对什么场景增强? |
**准入条件**:任务已按阶段分组、分配Agent、标记并行安全状态、定义成功标准,且所有任务通过深度工作规则检查。Phase 2: VALIDATE
阶段2:验证
Check gate:
python3 ~/.claude/scripts/feature-state.py gate FEATURE plan.plan-approvalStep 1: Requirements Coverage Gate
Before running the rest of validation, verify that every stated requirement is covered by at least one task. An uncovered requirement is a blocker, not a warning — partial coverage guarantees partial delivery.
The coverage check works as follows:
- Extract requirements from the design document's goal statement and any requirements/acceptance-criteria sections
- Map each requirement to the task(s) that address it
- Report unmapped requirements as plan defects that must be resolved before proceeding
markdown
undefined检查准入条件:
python3 ~/.claude/scripts/feature-state.py gate FEATURE plan.plan-approval步骤1:需求覆盖检查
在进行其他验证前,需确认每条明确的需求至少被一个任务覆盖。未被覆盖的需求是阻塞问题,而非警告——部分覆盖必然导致功能交付不完整。
覆盖检查流程如下:
- 提取需求:从设计文档的目标声明、需求/验收标准章节中提取需求
- 映射需求:将每条需求与对应的任务关联
- 报告未映射需求:作为计划缺陷,必须解决后方可继续
markdown
undefinedRequirements Coverage Matrix
需求覆盖矩阵
| # | Requirement | Covered By | Status |
|---|---|---|---|
| R1 | [requirement from design] | T1, T3 | COVERED |
| R2 | [requirement from design] | T2 | COVERED |
| R3 | [requirement from design] | — | UNCOVERED |
**Coverage must be 100%**. If any requirement is UNCOVERED:
- Add tasks to cover the missing requirement, OR
- Explicitly document why the requirement is deferred (with a follow-up ticket reference)
- Do NOT proceed to approval with uncovered requirements
**Why 100% is non-negotiable**: A plan that covers 8 of 10 requirements looks "mostly done" but delivers an incomplete feature. The missing requirements are discovered during implementation or — worse — after release. Catching gaps here costs minutes; catching them later costs hours or days.
**Step 2: Structural Validation Checklist**
Validation checklist:
- [ ] Every task has an assigned domain agent
- [ ] Every task has absolute file paths
- [ ] Every task has a verification command
- [ ] Every task is scoped to 2-5 minutes
- [ ] Wave ordering respects dependencies
- [ ] File conflicts are sequenced correctly
- [ ] Design components are fully covered by tasks
- [ ] Requirements coverage is 100% (from Step 1)
- [ ] Success criteria are behavior-focused, not implementation-focused
- [ ] Every task passes deep work rules (concrete actions, self-contained, observable completion)
**Step 3: Deep Work Rules Audit**
Scan every task in the plan against the three deep work rules:
| Rule | Check | Rejection Signal |
|------|-------|-----------------|
| Concrete actions | Does the task specify exactly what to do? | Vague verbs: "align," "ensure," "handle," "improve," "clean up" without concrete details |
| Self-contained | Can the assigned agent execute without asking questions? | References to "the discussion," "as mentioned," or context not in the task text |
| Observable completion | Is there a way to verify the task is done? | No verification command, no observable outcome described |
If any task fails a rule, rewrite it before proceeding. Do not approve plans with vague tasks — they create execution debt that compounds across waves.
If gate is `human`: present plan to user for approval.
If gate is `auto`: verify all checklist items pass.
**Gate**: Requirements 100% covered. All tasks pass deep work rules. Plan approved. Proceed to Checkpoint.| # | 需求 | 覆盖任务 | 状态 |
|---|---|---|---|
| R1 | [来自设计文档的需求] | T1, T3 | 已覆盖 |
| R2 | [来自设计文档的需求] | T2 | 已覆盖 |
| R3 | [来自设计文档的需求] | — | 未覆盖 |
**覆盖度必须达到100%**。若存在未覆盖的需求:
- 添加任务以覆盖缺失的需求,或
- 明确说明为何延迟该需求(需引用后续工单)
- 未解决未覆盖需求前,不得进入审批环节
**为何100%覆盖不可协商**:覆盖8/10需求的计划看似「基本完成」,但交付的是不完整的功能。未覆盖的需求可能在实现阶段甚至发布后才被发现,此时修复的成本是前期修复的数倍。
**步骤2:结构验证检查清单**
验证检查清单:
- [ ] 每个任务均分配了领域Agent
- [ ] 每个任务均包含绝对文件路径
- [ ] 每个任务均有验证命令
- [ ] 每个任务的时长控制在2-5分钟
- [ ] 阶段排序符合依赖关系
- [ ] 文件冲突已正确排序
- [ ] 设计组件已被任务完全覆盖
- [ ] 需求覆盖度为100%(来自步骤1)
- [ ] 成功标准聚焦行为而非实现
- [ ] 所有任务通过深度工作规则检查
**步骤3:深度工作规则审计**
扫描计划中的每个任务,检查是否符合三条深度工作规则:
| 规则 | 检查内容 | 拒绝信号 |
|------|-------|-----------------|
| 具体操作 | 任务是否明确说明了具体要做什么? | 使用模糊动词:「对齐」「确保」「处理」「优化」「清理」且未说明具体内容 |
| 可独立执行 | 分配的Agent能否无需额外上下文执行任务? | 引用「讨论内容」「会议决定」等任务描述中未包含的上下文 |
| 完成状态可观察 | 是否有方法验证任务已完成? | 无验证命令,未描述可观察的结果 |
若任何任务未通过规则检查,需重写后方可继续。不得批准包含模糊任务的计划——它们会在各阶段产生执行债务并不断累积。
若准入条件为`human`:将计划提交给用户审批。
若准入条件为`auto`:验证所有检查清单项均已通过。
**准入条件**:需求覆盖度100%,所有任务通过深度工作规则检查,计划已批准。方可进入 checkpoint 阶段。Phase 3: CHECKPOINT
阶段3:CHECKPOINT
-
Save plan artifact:bash
echo "PLAN_CONTENT" | python3 ~/.claude/scripts/feature-state.py checkpoint FEATURE plan -
Record learnings — if this phase produced non-obvious insights, record them:bash
python3 ~/.claude/scripts/learning-db.py record TOPIC KEY "VALUE" --category design -
Advance:bash
python3 ~/.claude/scripts/feature-state.py advance FEATURE -
Suggest next step:
Plan complete. Run /feature-implement to begin execution.
-
保存计划工件:bash
echo "PLAN_CONTENT" | python3 ~/.claude/scripts/feature-state.py checkpoint FEATURE plan -
记录经验 — 若本阶段产生了非显而易见的见解,需记录:bash
python3 ~/.claude/scripts/learning-db.py record TOPIC KEY "VALUE" --category design -
推进阶段:bash
python3 ~/.claude/scripts/feature-state.py advance FEATURE -
建议下一步操作:
计划已完成。执行/feature-implement开始实现。
Error Handling
错误处理
| Error | Cause | Solution |
|---|---|---|
| No design doc found | Design phase not completed | Run /feature-design first |
| Feature not in plan phase | Phase mismatch | Check status, advance if needed |
| Agent not found | Invalid agent assignment | Check agents/INDEX.json, use closest match |
| 错误 | 原因 | 解决方案 |
|---|---|---|
| 未找到设计文档 | 设计阶段未完成 | 先执行/feature-design |
| 功能未处于规划阶段 | 阶段不匹配 | 检查状态,必要时推进阶段 |
| 未找到Agent | Agent分配无效 | 检查agents/INDEX.json,使用最匹配的Agent |
Anti-Patterns
反模式
| Anti-Pattern | Why Wrong | Do Instead |
|---|---|---|
| Plan without design | No requirements to decompose | Complete /feature-design first |
| Vague task descriptions | Can't be executed by subagent | Specify exact files, operations, verification |
| All tasks in one wave | Loses parallelization opportunity | Group by actual dependencies |
| Skip file conflict analysis | Parallel execution causes corruption | Analyze every wave for conflicts |
| Uncovered requirements | Guarantees partial delivery — gaps discovered during implementation or after release | Run requirements coverage matrix; 100% coverage before approval |
| Implementation-focused success criteria | "All tasks done" can diverge from "goal achieved" — tasks might be wrong | Define success as observable behaviors, not task completion |
| Vague verbs in tasks ("align," "ensure," "handle") | Executor guesses what to do, builds wrong thing or blocks asking questions | Rewrite with concrete actions: what exactly changes, where, how to verify |
| Tasks that reference external context | "As discussed" or "per the meeting" — agent has no access to that context | Make every task self-contained with all needed context inline |
| 反模式 | 错误原因 | 正确做法 |
|---|---|---|
| 无设计文档时进行规划 | 无需求可拆解 | 先完成/feature-design |
| 模糊的任务描述 | 子Agent无法执行 | 明确指定具体文件、操作和验证方法 |
| 所有任务放在同一阶段 | 失去并行执行的机会 | 按实际依赖关系分组 |
| 跳过文件冲突分析 | 并行执行会导致数据损坏 | 分析每个阶段的冲突 |
| 需求未完全覆盖 | 必然导致交付不完整——缺口会在实现阶段或发布后才被发现 | 执行需求覆盖矩阵;审批前确保100%覆盖 |
| 成功标准聚焦实现 | 「所有任务完成」可能与「达成目标」脱节——任务本身可能有误 | 将成功定义为可观察的行为,而非任务完成 |
| 任务中使用模糊动词(如「对齐」「确保」「处理」) | 执行者会猜测需求,构建错误内容或因疑问而阻塞 | 重写为具体操作:明确修改内容、位置及验证方法 |
| 任务引用外部上下文 | 「如讨论所述」「根据会议决定」——Agent无法访问该上下文 | 确保每个任务包含所有必要的上下文 |
References
参考资料
- Gate Enforcement
- Retro Loop
- State Conventions
- Pipeline Architecture
- Gate Enforcement
- Retro Loop
- State Conventions
- Pipeline Architecture