feature-plan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Feature 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

  1. Check feature state:
    bash
    python3 ~/.claude/scripts/feature-state.py status FEATURE
    Verify current phase is
    plan
    and
    design
    is in completed phases.
  2. Load design artifact:
    bash
    ls .feature/state/design/*-FEATURE.md
    Read the design document.
  3. 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.
  1. 检查功能状态:
    bash
    python3 ~/.claude/scripts/feature-state.py status FEATURE
    验证当前阶段为
    plan
    design
    阶段已完成。
  2. 加载设计工件:
    bash
    ls .feature/state/design/*-FEATURE.md
    读取设计文档。
  3. 加载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
undefined

Implementation 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:
    go build ./...
    exits 0
  • Parallel-safe: true (no file conflicts with T2)
  • Agent: golang-general-engineer
  • Duration: 3 min
  • Files: /absolute/path/to/file.go
  • Operations: [具体修改内容]
  • Verification:
    go build ./...
    执行返回0
  • 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:
    npm run typecheck
    exits 0
  • Parallel-safe: true
  • Agent: typescript-frontend-engineer
  • Duration: 4 min
  • Files: /absolute/path/to/component.tsx
  • Operations: [具体修改内容]
  • Verification:
    npm run typecheck
    执行返回0
  • 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:
    go test ./...
    exits 0
  • 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:
    go test ./...
    执行返回0
  • Parallel-safe: false(与T4存在文件冲突)

**步骤3:文件冲突分析**

对每个阶段,检查是否有两个任务修改同一文件:
- 若是:标记`Parallel-safe: false`并添加顺序约束
- 若否:标记`Parallel-safe: true`

**步骤4:Agent路由验证**

对每个任务,验证分配的Agent是否存在于系统中:
- 对照已知的Agent触发器进行检查
- 若不确定,默认选择最接近的领域Agent
- 记录路由决策

**步骤5:定义基于目标的反向成功标准**

进入验证阶段前,需定义「完成后必须满足哪些条件?」,且这些条件需为**可观察的行为**,而非实现任务。成功标准是验证的目标——定义了「何时完成」,而实现任务定义了「如何完成」。若混淆两者,可能出现「所有任务完成但未达成目标」的情况。

每个计划必须包含`## 成功标准`章节,列出可观察的结果:

```markdown

Success Criteria

成功标准

<!-- What must be TRUE when this plan is fully implemented? --> <!-- Each criterion must be observable/verifiable — not an implementation task -->
  1. [Observable behavior 1]
  2. [Observable behavior 2]
  3. [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. [可观察行为1]
  2. [可观察行为2]
  3. [可观察行为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-approval
Step 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:
  1. Extract requirements from the design document's goal statement and any requirements/acceptance-criteria sections
  2. Map each requirement to the task(s) that address it
  3. 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:需求覆盖检查
在进行其他验证前,需确认每条明确的需求至少被一个任务覆盖。未被覆盖的需求是阻塞问题,而非警告——部分覆盖必然导致功能交付不完整。
覆盖检查流程如下:
  1. 提取需求:从设计文档的目标声明、需求/验收标准章节中提取需求
  2. 映射需求:将每条需求与对应的任务关联
  3. 报告未映射需求:作为计划缺陷,必须解决后方可继续
markdown
undefined

Requirements Coverage Matrix

需求覆盖矩阵

#RequirementCovered ByStatus
R1[requirement from design]T1, T3COVERED
R2[requirement from design]T2COVERED
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

  1. Save plan artifact:
    bash
    echo "PLAN_CONTENT" | python3 ~/.claude/scripts/feature-state.py checkpoint FEATURE plan
  2. Record learnings — if this phase produced non-obvious insights, record them:
    bash
    python3 ~/.claude/scripts/learning-db.py record TOPIC KEY "VALUE" --category design
  3. Advance:
    bash
    python3 ~/.claude/scripts/feature-state.py advance FEATURE
  4. Suggest next step:
    Plan complete. Run /feature-implement to begin execution.
  1. 保存计划工件:
    bash
    echo "PLAN_CONTENT" | python3 ~/.claude/scripts/feature-state.py checkpoint FEATURE plan
  2. 记录经验 — 若本阶段产生了非显而易见的见解,需记录:
    bash
    python3 ~/.claude/scripts/learning-db.py record TOPIC KEY "VALUE" --category design
  3. 推进阶段:
    bash
    python3 ~/.claude/scripts/feature-state.py advance FEATURE
  4. 建议下一步操作:
    计划已完成。执行/feature-implement开始实现。

Error Handling

错误处理

ErrorCauseSolution
No design doc foundDesign phase not completedRun /feature-design first
Feature not in plan phasePhase mismatchCheck status, advance if needed
Agent not foundInvalid agent assignmentCheck agents/INDEX.json, use closest match
错误原因解决方案
未找到设计文档设计阶段未完成先执行/feature-design
功能未处于规划阶段阶段不匹配检查状态,必要时推进阶段
未找到AgentAgent分配无效检查agents/INDEX.json,使用最匹配的Agent

Anti-Patterns

反模式

Anti-PatternWhy WrongDo Instead
Plan without designNo requirements to decomposeComplete /feature-design first
Vague task descriptionsCan't be executed by subagentSpecify exact files, operations, verification
All tasks in one waveLoses parallelization opportunityGroup by actual dependencies
Skip file conflict analysisParallel execution causes corruptionAnalyze every wave for conflicts
Uncovered requirementsGuarantees partial delivery — gaps discovered during implementation or after releaseRun requirements coverage matrix; 100% coverage before approval
Implementation-focused success criteria"All tasks done" can diverge from "goal achieved" — tasks might be wrongDefine 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 questionsRewrite 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 contextMake 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