implementation-planner

实施规划器

此技能可生成包含里程碑、任务和最佳实践约束的全面实施计划。

先决条件

• 已完成 business-requirements.yaml
• 已完成 technical-requirements.yaml
• 推荐：来自 style-anchors-collection 技能的 style-anchors/index.yaml

规划流程

阶段 0：选择排序策略

在分析需求或生成里程碑之前，询问用户希望采用哪种排序策略。逐字呈现以下提示：

---

在生成实施计划之前，我需要了解你希望如何排列里程碑。请选择一种策略：

1. 多 PR / 主干开发 — 每个里程碑都可独立发起 PR，并持续合并到 develop/main。每个里程碑本身都必须可交付。最适合采用主干开发的团队。
2. 单功能分支 — 所有里程碑都在同一个长期分支上，最后通过一个 PR 合并。排序完全依据技术依赖关系。最适合必须在完成前不接触 main 的独立功能。
3. 价值优先（演示驱动） — 重新排列里程碑，尽早呈现用户可见的功能，即使这意味着推迟部分基础设施工作。最适合需要尽早向利益相关者演示或获取反馈的项目。
4. 风险优先 — 优先处理不确定性最高或技术未知最多的里程碑，以便尽早发现阻碍。最适合存在重大未知因素的项目。
5. 纵向切片 / 行走骨架 — 第一个里程碑交付一个贯穿所有架构层的精简端到端切片。后续里程碑再逐步完善各个领域。最适合尽早验证架构。
6. 基础优先（顺序式） — 先搭建基础设施和工具，再开发功能，最后打磨。严格按顺序推进。最适合需求明确的全新项目。

或者回复 “推荐一种”，我会根据你的需求选择。

---

将用户的选择记录为 ordering_strategy。如果用户回复“推荐一种”，请分析需求并选择最合适的策略，同时解释理由。在阶段 2（里程碑识别）中，始终应用相应的排序规则。

各策略对应的排序规则：

• 多 PR / 主干开发：每个里程碑都必须有一个“可交付”成功标准，且不能依赖任何其他尚在进行中（未合并）的里程碑。里程碑应按顺序排列，使每个都可独立审查和合并。
• 单功能分支：完全按照技术依赖关系排序。不要求每个里程碑都可独立交付。
• 价值优先：按面向用户的影响从高到低排列里程碑。将必需的基础工作作为前置设置环节，纳入第一个里程碑。
• 风险优先：按不确定性／风险评分从高到低排列。高风险里程碑排在 m0 或 m1；尽早降低风险。
• 纵向切片：第一个里程碑涵盖某个精简功能的所有架构层（例如，一个 API 端点 + UI + 持久化）。其余里程碑按功能领域分组。
• 基础优先：采用当前默认排序。基础设施 → 核心功能 → 高级功能 → 打磨／发布。

阶段 0.5：选择目标受众

用户选择排序策略后，询问该计划面向哪些受众：

---

此实施计划的主要受众是谁？

1. AI Agent — 提供完整的实施细节，包括分步说明、代码示例和明确的约束。适用于 Claude Code 或其他由 AI 驱动的开发工作流。

2. 人类开发者 — 提供高层级的任务描述、目标、风格锚点参考和成功标准。由开发者自行决定实施方式。最适合需要规划结构、但不需要规定具体步骤的资深团队。

3. 混合受众 — 详细程度适中。包含关键实施指导和模式参考，但日常决策由开发者自主处理。最适合团队成员背景多元的团队、与 AI 结对编程，或用作交接文档。

---

将用户的选择记录为 target_audience: "ai" | "human" | "hybrid"。

默认值： 如果用户不确定，自主开发会话建议选择 "ai"，资深开发者团队则建议选择 "human"。

输入分析

1. 加载需求

   • 解析业务需求，确定功能范围
   • 解析技术需求，确定架构决策
   • 从 {base_directory}/artifacts/style-anchors/index.yaml 加载风格锚点（如果存在）
   • 识别依赖项和约束

2. 确定里程碑

   • 将相关功能归为逻辑上的里程碑
   • 安排里程碑顺序和设置 dependencies 时，应用所选 ordering_strategy 的排序规则
   • 确定依赖顺序
   • 定义里程碑交付物

3. 生成任务

   • 将里程碑拆分为原子任务
   • 应用任务规模规则（30m - 2.5h）
   • 定义任务依赖项
   • 根据任务类型和文件模式，从 index.yaml 中选择相关风格锚点
   • 在任务说明中嵌入风格锚点参考
   • 为每个里程碑添加最终代码审查任务

4. 应用最佳实践

   • TDD 要求
   • 风格锚点参考
   • 质量约束
   • 防止偏离规则
   • 全面的代码审查

最佳实践（内嵌）

核心原则

分层验证

模型会进行局部优化；通过分层验证强制落实全局约束（提示词 → IDE → 提交 → CI → 运行时）。

风格锚点

• 始终包含 2-3 个示例文件作为模板
• 引用准确的路径和行号
• 优先使用仓库中的具体示例（代码 + 测试 + README）
• 尽早落实锚点，防止架构偏离

任务规模

• 将工作拆分为 30m–2.5h 的原子任务（30–150 分钟为最佳）
• 将范围限制在特定文件内
• 每完成一项小任务就提交
• 一旦出现偏离，立即回退
• 如果任务少于 30m，则增加预估时长，或说明理由后将其拆分

肯定式指令

• 明确说明允许执行的操作
• 避免使用否定式表述
• 使用“仅使用 X、Y、Z”，而不是“不要使用 A、B、C”

分层规则

• 全局：用户偏好（格式、语言、长度）
• 项目：CLAUDE.md 或 .cursor/rules/ 中的持久规则
• 上下文感知：根据目录或文件模式自动附加的规则

质量约束

以 TDD 为核心

• 实施前必须提供 TDD 检查清单
• 测试 → 最少量代码 → 更多测试 → 重构
• 测试失败时，返回失败输出，并附上指示：“修改实现以通过此测试，同时保留所有此前已通过的测试。不要修改测试。不要添加依赖。”

偏移处理

• 遇到意外依赖或不熟悉的模式时，立即停止并回退
• 不要在执行过程中修复
• 每次会话后记录经验并更新持久化规则

提示词位置

• 将关键规格、风格锚点和硬性规则放在开头
• 在提示词末尾重申这些内容
• 避免将要求埋在中间

外部数据验证

• 绝不对外部数据使用类型断言
• 使用适当的错误处理验证所有外部输入
• 使用架构验证，而非运行时断言

输出格式

里程碑结构

生成 milestones.yaml，其中包含版本、项目元数据、meta 部分（排序策略、目标受众）以及 milestones 数组。meta 部分包含 ordering_strategy、ordering_rationale 和 target_audience（ai/human/hybrid）。每个里程碑包含：id（m0、m1...）、name、description、dependencies、estimated_duration、tasks_file 和 success_criteria。可选字段包括 acceptance_criteria（functional、non_functional、testing、documentation）和 exit_checklist。

完整文档规范（包含所有字段、排序策略和可选字段）请参阅 references/milestones-spec.md。

完整示例请参阅 references/milestones-example.yaml。

可选字段说明：

• success_criteria（必需）：高层级规划验收标准
• acceptance_criteria（可选）：详细交付标准，包含需求追踪、测试要求和文档预期。需要严格的里程碑签核时使用。
• exit_checklist（可选）：用于代码审查的二元放行/不放行检查清单。需要正式的关卡驱动流程时使用。

大多数项目只使用 success_criteria。在以下情况下添加详细验收标准：

• 项目需要可用于审计的需求可追溯性
• 多个利益相关方需要明确的签核标准
• QA 团队需要每个里程碑的明确测试要求
• 代码审查流程需要详细的检查清单

**生成后添加详细标准：**运行 /definition-of-done，根据需求为 milestones.yaml 添加 acceptance_criteria 和 exit_checklist 字段。

任务结构

生成 milestone-m*.tasks.yaml，其中包含 task_summaries、风格锚点、全局约束、质量关卡以及 tasks 数组。

必需部分：

• task_summaries（映射）：任务 ID 到 1-2 句简明英文摘要的映射。放在顶部，便于快速浏览。每条摘要应为 20-300 个字符，使用主动语态，侧重说明做什么/为什么，而非怎么做。示例：m1-001: "Creates core User model with validation rules for all user operations."
• global_constraints：允许的模式、禁止的模式、TDD 要求、任务最长时长、提交策略
• quality_gates：任务前、提交前、任务完成、里程碑完成、推送前阶段
• tasks：任务对象数组

每个任务包含：id（mN-NNN 格式）、name、description、estimate_minutes（30-150）、type（code/test/docs/config）、dependencies、files（create/modify/touch_only）、style_anchor_refs 和详细的 instructions。

完整文档规范（包含任务结构、质量关卡和 TDD 检查清单）请参阅 references/milestone-tasks-spec.md。

完整示例请参阅 references/milestone-tasks-example.yaml。

任务规模指南

最佳任务时长

• 最短：30 分钟
  • 如果任务时长更短，请记录理由
  • 考虑与相关任务合并
• 最佳：30-150 分钟
  • 变更原子化且范围明确
  • 可在一次工作时段内完成
  • 成功标准明确
• 最长：150 分钟（2.5 小时）
  • 如果任务时长更长，请拆分为较小的任务
  • 确定自然的拆分点
  • 为子任务创建依赖关系

任务规模示例

太小（< 30 分钟）

- id: m1-001
  name: Add export statement
  estimate_minutes: 10
  rationale: "Simple addition but critical for module system"

最佳（30-150 分钟）

- id: m1-002
  name: Implement user authentication service
  estimate_minutes: 90
  dependencies: [m1-001]

太大（> 150 分钟）— 拆分

# BEFORE (too large):
- id: m1-003
  name: Build complete API layer
  estimate_minutes: 300

# AFTER (properly split):
- id: m1-003
  name: Define API interface and types
  estimate_minutes: 60

- id: m1-004
  name: Implement API routes
  estimate_minutes: 90
  dependencies: [m1-003]

- id: m1-005
  name: Add API middleware and error handling
  estimate_minutes: 60
  dependencies: [m1-004]

任务指令详细程度

任务指令会根据 Phase 0.5 中选择的目标受众，以不同的详细程度生成：

AI Agent 受众（完整详细程度）

结构：

• 目标： 清晰说明要构建的内容
• 风格锚点： 带行号的模式文件链接
• 参考文件： 代码库中的具体示例
• 实施步骤： 编号且有明确要求的步骤（1、2、3……）
• 约束： 明确说明“只能使用”和“绝不能使用”
• TDD 检查清单： 逐步列出测试优先的要求
• 验证： 精确的命令及预期输出
• 偏离策略： 何时停止并回退

示例：

instructions: |
  **Objective:**
  Define Project and Milestone domain models using Model.Class.

  **Style Anchors:**
  Follow these established patterns:
  - See `artifacts/style-anchors/SA-002.md` — Model.Class with makeRepository
  - See `artifacts/style-anchors/SA-006.md` — Effect Schema domain types

  Reference files:
  - `~/Sites/ai/effect/packages/sql/src/Model.ts:82-157` — Model.Class definition
  - `~/Sites/ai/EffectPatterns/packages/pipeline-state/src/schemas.ts:1-234` — domain patterns

  **Implementation Steps:**
  1. Create `packages/shared/src/schemas/project.ts`:
     - PipelineStatus: Schema.Literal union of all pipeline stages (intake through archived)
     - Priority: Schema.Literal("low", "medium", "high", "critical")
     - Project model using Model.Class with fields:
       id (Model.Generated), slug, name, description, pipelineStatus,
       assignedPeople (Model.JsonFromString array), tags (Model.JsonFromString array),
       priority, createdAt (DateTimeInsert), updatedAt (DateTimeUpdate)
  2. Create `packages/shared/src/schemas/milestone.ts`:
     - MilestoneStatus: Schema.Literal("pending", "in-progress", "blocked", "complete")
     - Milestone model using Model.Class with fields:
       id, projectId, name, description, status, orderIndex, estimatedDays,
       acceptanceCriteria, createdAt, updatedAt
  3. Export all types and schemas from each file
  4. Update schemas/index.ts barrel export

  **Constraints:**
  - ONLY use: Model.Class, Schema.Literal, Schema.Struct
  - Follow **SA-002** for Model.Class structure with variant schemas (insert, update, select)
  - Follow **SA-006** for Schema.Literal enum patterns
  - NEVER use: TypeScript enum keyword or plain interfaces
  - NEVER use: type assertions (as) on external data
  - Include proper JSDoc comments for all exported types

  **TDD Checklist:**
  Before writing implementation:
  - [ ] Write failing test for Project.insert.make() constructor
  - [ ] Write failing test for Milestone.insert.make() constructor
  - [ ] Write failing test for Schema.decodeUnknown validation (valid cases)
  - [ ] Write failing test for Schema.decodeUnknown rejection (invalid cases)

  After implementation:
  - [ ] All tests pass
  - [ ] TypeScript inference works without explicit types
  - [ ] Variant schemas (insert, update, select) generate correctly

  **Validation:**
  ```bash
  pnpm test packages/shared/src/schemas/project.test.ts
  pnpm test packages/shared/src/schemas/milestone.test.ts
  pnpm run typecheck
  pnpm run lint

预期：所有测试通过，没有类型错误，也没有 lint 错误

偏离策略： 出现以下情况时立即停止：

• 实施需要使用约束中未列出的依赖项
• 测试失败，且你考虑修改测试
• 需要修改的意外文件超过 3 个
• 无法在列出的文件中解决类型错误

### Human Developer Audience (High-Level)

**Structure:**
- **Objective:** Clear statement of what to build with key requirements
- **Style Anchors:** Links to pattern files for reference
- **Key Requirements:** Bullet list of essential features/fields
- **Constraints:** Technology choices and architectural patterns only
- **Success Criteria:** Measurable outcomes without prescribing approach

**Example:**
```yaml
instructions: |
  **Objective:**
  Define Project and Milestone domain models using Model.Class with insert, update,
  and select variants. Include pipeline status enum, priority levels, and proper
  field constraints.

  **Style Anchors:**
  - See `artifacts/style-anchors/SA-002.md` — Model.Class with makeRepository pattern
  - See `artifacts/style-anchors/SA-006.md` — Effect Schema domain types

  **Key Requirements:**

  *Project Model:*
  - Fields: id, slug, name, description, pipelineStatus, assignedPeople (JSON array),
    tags (JSON array), priority, timestamps
  - PipelineStatus enum: intake → analysis → planning → development → review → qa →
    deploy → complete → archived
  - Priority: low, medium, high, critical
  - Use Model.Generated for id, Model.JsonFromString for JSON arrays

  *Milestone Model:*
  - Fields: id, projectId, name, description, status, orderIndex, estimatedDays,
    acceptanceCriteria, timestamps
  - MilestoneStatus: pending, in-progress, blocked, complete

  **Constraints:**
  - Use Model.Class, Schema.Literal, Schema.Struct only
  - Follow SA-002 for variant schemas (insert, update, select)
  - No TypeScript enums or plain interfaces
  - All fields must support runtime validation via Effect Schema

  **Success Criteria:**
  - Models compile with full type inference
  - insert.make(), update.make() constructors available
  - Schema.decodeUnknown validates correctly for valid and invalid inputs
  - Tests pass, no type errors, no lint errors

混合受众（中等详细程度）

结构：

• 目标： 清晰说明要构建的内容
• 风格锚点： 模式文件链接
• 实施方法： 高层次方法及关键决策点
• 约束： 技术和模式要求
• 验证： 用于确认成功的命令

示例：

instructions: |
  **Objective:**
  Define Project and Milestone domain models using Model.Class.

  **Style Anchors:**
  - See `artifacts/style-anchors/SA-002.md` — Model.Class pattern
  - See `artifacts/style-anchors/SA-006.md` — Schema.Literal patterns

  **Implementation Approach:**
  1. Create project.ts:
     - Define PipelineStatus as Schema.Literal union covering all stages
     - Define Priority as Schema.Literal("low", "medium", "high", "critical")
     - Define Project using Model.Class with: id (Generated), slug, name, description,
       pipelineStatus, assignedPeople (JsonFromString), tags (JsonFromString),
       priority, timestamps

  2. Create milestone.ts:
     - Define MilestoneStatus as Schema.Literal union
     - Define Milestone using Model.Class with: id, projectId, name, description,
       status, orderIndex, estimatedDays, acceptanceCriteria, timestamps

  3. Update schemas/index.ts to export both schemas

  **Constraints:**
  - Use Model.Class for entities, Schema.Literal for enums
  - Follow SA-002 variant schema pattern (insert, update, select)
  - No TypeScript enum keyword
  - Include JSDoc for exported types

  **Validation:**
  Run tests and typecheck to verify:
  - Model constructors (insert.make, update.make) work correctly
  - Schema.decodeUnknown validates and rejects appropriately
  - Full type inference without explicit type annotations

实施逻辑

生成任务时，根据 target_audience 确定指令的详细程度：

• AI 受众：包含所有章节，并提供最详尽的信息（步骤、TDD、偏离策略、明确的验证）
• Human 受众：仅包含目标、风格锚点、关键要求、约束和成功标准
• Hybrid 受众：包含目标、风格锚点、实施方法（高层次步骤）、约束和验证命令

所有受众使用相同的任务结构和元数据（id、name、description、estimate、type、dependencies、files、style_anchor_refs）。只有 instructions 字段的内容会因详细程度而异。

代码审查任务要求

最后一个里程碑任务

重要：每个里程碑都必须将代码审查任务作为最后一个任务。此任务可在进入下一个里程碑前确保质量控制，并确认与风格锚点保持一致。

代码审查任务模板

- id: [milestone]-[last-number]
  name: Comprehensive code review for [milestone-name]
  description: |
    Conduct a thorough code review of all work completed in this milestone.
    Review against style anchors, architectural decisions, and best practices.
    Document findings and create actionable recommendations.
  estimate_minutes: 60
  type: code-review
  dependencies: [all other tasks in this milestone]
  files:
    create:
      - code-reviews/[yyyy-mm-dd]-{n}-code-review.yaml
    modify: []
    touch_only: [all files created/modified in this milestone]
  instructions: |
    **Objective:**
    Review all code, tests, and documentation created or modified during this milestone
    for quality, consistency, and alignment with project standards.

    **Review Checklist:**
    1. **Style Anchor Compliance:**
       - [ ] Code follows patterns defined in style anchors
       - [ ] Naming conventions are consistent
       - [ ] File structure matches established patterns
       - [ ] Import organization follows standards

    2. **Code Quality:**
       - [ ] No code duplication or unnecessary complexity
       - [ ] Clear, meaningful variable and function names
       - [ ] Appropriate use of types (no any, proper generics)
       - [ ] Error handling is comprehensive and consistent
       - [ ] No magic numbers or hardcoded values

    3. **Testing:**
       - [ ] All new code has corresponding tests
       - [ ] Tests follow TDD patterns from style anchors
       - [ ] Edge cases are covered
       - [ ] Test names are descriptive

    4. **Architecture:**
       - [ ] Follows technical requirements decisions
       - [ ] Service patterns are consistent
       - [ ] Dependencies are properly injected
       - [ ] No circular dependencies

    5. **Documentation:**
       - [ ] JSDoc comments for public APIs
       - [ ] Complex logic is explained
       - [ ] README updated if needed
       - [ ] Examples are accurate

    **Review Process:**
    1. Review each file modified in this milestone
    2. Compare against referenced style anchors
    3. Run all quality gates (lint, typecheck, tests)
    4. Document problems with specific file:line references
    5. Provide recommended solutions with code examples
    6. Create code-reviews/[yyyy-mm-dd]-{n}-code-review.yaml

    **Output Format:**
    ```yaml
    milestone: [milestone-id]
    milestone_name: [milestone-name]
    review_date: [yyyy-mm-dd]
    reviewer: claude-code

    summary:
      files_reviewed: [count]
      issues_found: [count]
      critical_issues: [count]
      overall_quality: [excellent|good|fair|needs-improvement]

    style_anchor_compliance:
      - anchor: [path/to/anchor:lines]
        status: [compliant|partial|non-compliant]
        notes: |
          [Specific observations]

    issues:
      - severity: [critical|major|minor]
        category: [style|architecture|testing|documentation|security]
        file: [path:line]
        description: |
          [Clear description of the problem]
        recommendation: |
          [Specific solution with code example if applicable]
        related_anchor: [path/to/anchor:lines]

      - severity: major
        category: testing
        file: src/example.ts:45
        description: |
          Missing error case test for invalid input scenario
        recommendation: |
          Add test case:
          ```typescript
          it.effect("should reject invalid input", () =>
            Effect.gen(function* () {
              const result = yield* service.process({ invalid: true })
              expect(result).toMatchError(ValidationError)
            })
          )
          ```
        related_anchor: test/example.test.ts:20-35

    strengths:
      - [What was done well]
      - [Good patterns observed]

    recommendations:
      - priority: [high|medium|low]
        action: |
          [Specific action to take]
        impact: |
          [Why this matters]

    sign_off:
      ready_for_next_milestone: [yes|no|with-fixes]
      blocking_issues: [list of critical issues that must be fixed]
      notes: |
        [Additional context or observations]
    ```

    **Constraints:**
    - ONLY review code from this milestone
    - Reference specific style anchors when citing issues
    - Provide actionable, specific recommendations
    - Include code examples in recommendations when possible

    **Validation:**
    ```bash
    # Ensure all quality gates pass
    npm run lint
    npm run typecheck
    npm test

    # Verify review file is created
    ls code-reviews/[yyyy-mm-dd]-*.yaml
    ```
    Expected: All quality gates pass, review file exists with complete analysis

    **Drift Policy:**
    If critical issues are found that violate style anchors or architectural
    decisions, mark as blocking and recommend fixes before proceeding to next milestone.

  validation:
    commands:
      - npm run lint
      - npm run typecheck
      - npm test
    expected_output: All quality gates pass
    on_failure: Document failures in review and mark milestone as needing fixes

代码审查命名约定

代码审查文件应按以下规则命名：

• 日期：审查进行日期，格式为 YYYY-MM-DD
• 序号：同一天进行多次审查时递增编号
• 格式：code-reviews/YYYY-MM-DD-{n}-code-review.yaml

示例：

• code-reviews/2025-01-27-1-code-review.yaml（1 月 27 日的第一次审查）
• code-reviews/2025-01-27-2-code-review.yaml（同一天的第二次审查）
• code-reviews/2025-01-28-1-code-review.yaml（次日的第一次审查）

与里程碑流程集成

1. 规划里程碑时：

   • 统计为里程碑规划的任务总数
   • 将代码审查任务添加为最后一个任务
   • 将所有其他任务设为其依赖项

2. 开发期间：

   • 完成所有实施任务
   • 执行最后的代码审查任务
   • 解决发现的所有阻塞问题
   • 确认里程碑完成

3. 进入下一个里程碑前：

   • 确认代码审查签署结果为“yes”或“with-fixes”
   • 如果结果为“with-fixes”，先解决阻塞问题
   • 只有达到质量标准后才能继续

风格锚点集成

加载风格锚点

如果 {base_directory}/artifacts/style-anchors/index.yaml 存在：

1. 加载索引：

   Read {base_directory}/artifacts/style-anchors/index.yaml
   

2. 解析锚点数据：

   • 提取类别和锚点
   • 加载 usage_matrix，用于映射模式
   • 按任务类型和文件模式构建查找表

3. 针对生成的每项任务：

   • 确定任务类型（代码/测试/文档/配置）
   • 将任务中的文件模式与锚点的 applies_to 规则进行匹配
   • 查询 usage_matrix，获取推荐的锚点
   • 选择最相关的前 2–3 个锚点

风格锚点选择逻辑

按任务类型：

task.type == "code" → usage_matrix.task_types[type="code"].recommended_anchors
task.type == "test" → usage_matrix.task_types[type="test"].recommended_anchors
task.type == "api"  → usage_matrix.task_types[type="api"].recommended_anchors

按文件模式：

For each anchor in anchors:
  For each pattern in anchor.applies_to.file_patterns:
    If task.files match pattern:
      Include this anchor

按里程碑类型：

For each anchor in anchors:
  If milestone.type in anchor.applies_to.milestone_types OR "all" in milestone_types:
    Consider this anchor

在任务说明中嵌入锚点

生成任务 YAML 时，加入风格锚点引用：

instructions: |
  **Objective:**
  [Task objective]

  **Style Anchors:**
  Follow these established patterns:
  - See `artifacts/style-anchors/[anchor-id].md` - [anchor.name]
  - See `artifacts/style-anchors/[anchor-id].md` - [anchor.name]

  Reference files:
  - `[anchor.source.path]:[anchor.source.lines]` - [what it demonstrates]

  **Implementation Steps:**
  1. [Step 1]
  2. [Step 2]

  **Constraints:**
  - ONLY use: [specific libraries/approaches]
  - Follow pattern in: [anchor reference]
  - File scope: ONLY modify listed files

  [Rest of task instructions...]

优秀风格锚点的特点

1. 具体 - 使用真实文件路径，而非抽象描述
2. 明确 - 提供行号以确保精确
3. 完整 - 包含代码、测试和文档
4. 当前 - 体现当前最佳实践
5. 典范 - 正确展示相应模式

不存在风格锚点时

如果 {base_directory}/artifacts/style-anchors/index.yaml 不存在：

• 显示警告："⚠️ 未找到风格锚点。生成的任务不会包含具体代码示例。建议先运行 /style-anchors-collection，以降低偏差风险。"
• 改用通用最佳实践生成任务
• 在任务说明中加入风格锚点占位符：

  instructions: |
    **Style Anchors:**
    (No style anchors collected. Follow general best practices from technical requirements)
  

质量门禁配置

提交前钩子

quality_gates:
  - stage: pre-commit
    commands:
      - npm run lint
      - npm run typecheck
      - npm test
    must_pass: true

CI 流水线

quality_gates:
  - stage: ci
    commands:
      - npm run lint
      - npm run typecheck
      - npm test
      - npm run test:integration
    coverage_threshold: 80

任务完成

quality_gates:
  - stage: task-completion
    criteria:
      - All tests passing
      - No lint errors
      - No type errors
      - Code formatted
      - Documentation updated
      - Commit message follows convention

用法

生成实施计划：

/implementation-planner [base-directory]

如果未提供目录，则在当前目录中查找 requirements/business-requirements.yaml 并自动检测目录。

如果未找到，则提示用户："你的需求文档位于哪里？"

等待用户提供路径后再继续。将其保存为 base_directory。

该技能将：

1. 请用户选择里程碑排序策略（阶段 0）
2. 从 {base_directory}/requirements/ 加载并分析两份需求文档
3. 从 {base_directory}/artifacts/style-anchors/index.yaml 加载风格锚点（如果存在）
4. 根据功能确定逻辑里程碑，并按所选策略排序
5. 创建按依赖关系排序的里程碑分解
6. 针对每个里程碑：
   • 生成详细的任务分解
   • 创建 task_summaries 映射，为每项任务编写 1–2 句通俗易懂的摘要，便于人工浏览
   • 根据任务类型和文件模式选择并嵌入相关风格锚点引用
   • 应用任务规模规则
   • 添加 TDD 和质量约束
   • 将最终代码审查任务作为最后一项任务
7. 将 milestones.yaml 输出到 {base_directory}/implementation/
8. 将 milestone-m*.tasks.yaml 文件输出到 {base_directory}/implementation/tasks/
9. 如果生成，则将 FEATURE_FLAGS.md 和 UPDATES.md 输出到 {base_directory}/artifacts/

规划最佳实践

识别里程碑

1. 从基础开始 - 首先处理基础设施和工具
2. 纵向构建 - 端到端地完成各项功能
3. 尽量减少依赖 - 尽可能并行开展工作
4. 尽早交付价值 - 在早期里程碑交付可运行的软件
5. 遵守约束 - 时间线、资源和复杂度

任务分解

1. 单一职责 - 每项任务只做一件事
2. 明确依赖 - 明确任务顺序
3. 可测试 - 每项任务都有验证标准
4. 范围受限 - 限制文件数量和复杂度
5. 可逆 - 需要时便于还原

依赖管理

1. 尽量缩短关键路径 - 尽可能并行处理
2. 明确接口 - 明确定义任务间的契约
3. 记录假设 - 说明每项任务对前序任务的预期
4. 为失败做好计划 - 明确依赖失败时的应对措施

工作流示例

输入文件

project/
├── business-requirements.yaml
├── technical-requirements.yaml
└── examples/
    ├── service.ts
    ├── service.test.ts
    └── schema.ts

命令

/implementation-planner \
  business-requirements.yaml \
  technical-requirements.yaml \
  --style-anchors ./examples

输出文件

如果目录不存在，则创建目录：

mkdir -p {base_directory}/implementation/tasks
mkdir -p {base_directory}/artifacts

输出结构：

{base_directory}/
├── implementation/
│   ├── milestones.yaml
│   └── tasks/
│       ├── milestone-m0.tasks.yaml  # Foundation
│       ├── milestone-m1.tasks.yaml  # Core features
│       ├── milestone-m2.tasks.yaml  # Advanced features
│       └── milestone-m3.tasks.yaml  # Polish & release
└── artifacts/
    ├── FEATURE_FLAGS.md     # If generated
    ├── UPDATES.md          # If generated
    └── style-anchor-references.yaml  # If generated

审查与差距分析

生成里程碑和任务文件后，自动执行差距分析：

完整性检查

里程碑结构：

• 所有里程碑都有明确的交付成果
• 依赖关系顺序正确
• 没有循环依赖
• 时间安排切实可行
• 成功标准可测试

任务分解：

• 所有需求均由任务覆盖
• 任务规模符合 30-150 分钟规则
• 任务之间的依赖关系明确
• 文件范围定义清晰
• 每项任务都有验证标准

任务质量：

• 指令清晰且可执行
• 约束明确
• 代码任务包含 TDD 检查清单
• 指定了验证命令
• 说明了偏离处理策略

一致性检查

业务需求：

• 所有功能需求都映射到任务
• 优先级与业务优先级一致
• MVP 范围定义清晰
• 成功标准可验证

技术需求：

• 架构决策体现在结构中
• 技术选择通过约束落实
• 已实施测试策略
• 已处理安全需求

任务规模分析

检查是否违规：

• 少于 30 分钟的任务——合并或说明理由
• 超过 150 分钟的任务——拆分为更小的任务
• 关键路径上的任务规模是否合适

生成规模分析报告：

task_sizing_analysis:
  total_tasks: [count]
  average_duration: [minutes]

  too_small:
    - task_id: [id]
      estimate: [minutes]
      rationale: [why it's small]
      recommendation: [merge with X or accept]

  too_large:
    - task_id: [id]
      estimate: [minutes]
      recommendation: [split into X, Y, Z]

  optimal_range:
    count: [number]
    percentage: [%]

依赖关系分析

关键路径：

• 确定贯穿各里程碑的关键路径
• 检查可并行执行的机会
• 确认没有不必要的依赖关系
• 确保依赖关系最少但足够

依赖图验证：

dependency_analysis:
  critical_path: [m0 → m1 → m3 → m5]
  critical_path_duration: [time]

  parallel_opportunities:
    - [m2 and m3 can run in parallel]
    - [m4 can start after m1]

  dependency_issues:
    - task: [id]
      issue: [unnecessary dependency / missing dependency]
      recommendation: [fix]

差距识别

要检查的常见差距：

• 缺少基础设施任务（设置、工具）
• 缺少测试任务
• 缺少文档任务
• 缺少错误处理任务
• 缺少配置任务
• 缺少部署/发布任务
• 任务中存在未记录的假设
• 新模式缺少风格锚点
• 任务没有明确的文件边界
• 组件之间缺少集成任务

覆盖范围分析

需求覆盖矩阵：

requirement_coverage:
  functional_requirements:
    FR-1: [m1-001, m1-002] # Tasks covering this requirement
    FR-2: [m1-003]
    FR-3: [gap] # Not covered!

  non_functional_requirements:
    performance: [m2-001, m2-002]
    security: [m1-005]
    usability: [gap] # Not covered!

风格锚点验证

• 风格锚点引用现有文件（如果已提供）
• 风格锚点展示了正确的模式
• 行号准确
• 描述有帮助

审查输出

生成全面的差距分析报告：

gap_analysis:
  completeness_score: [1-10]
  alignment_score: [1-10]
  feasibility_score: [1-10]

  critical_gaps:
    - category: [category]
      issue: [description]
      impact: [high/medium/low]
      affected_requirements: [FR-1, FR-2, etc]
      recommendation: [how to fix]

  missing_coverage:
    requirements:
      - [FR-X not covered]
      - [NFR-Y not covered]

    task_types:
      - [Missing: integration tests]
      - [Missing: documentation]

  sizing_issues:
    too_small_count: [n]
    too_large_count: [n]
    recommendations: [list]

  dependency_issues:
    - [description]

  strong_areas:
    - [what's well-planned]

  optimization_opportunities:
    - [parallel execution: m2 and m3]
    - [combine tasks: m1-002 and m1-003]

  suggestions:
    - [improvement suggestions]

  ready_for_development: [yes/no/with-modifications]

  estimated_timeline:
    optimistic: [time]
    realistic: [time]
    pessimistic: [time]

如果发现关键差距，请询问：

“我在实施计划中发现了一些差距：

关键问题：

• [问题 1]
• [问题 2]

覆盖缺失：

• [需求 FR-X 未覆盖]
• [未规划集成测试]

你希望如何处理：

1. 立即添加缺失任务（我会生成这些任务）
2. 审查并手动调整计划
3. 继续开发（按需处理差距）”

与开发集成

开始一个里程碑

# Load milestone tasks into context
Read milestone-m1.tasks.yaml

# Review style anchors
Read examples/service.ts:10-50
Read examples/service.test.ts:1-40

# Begin first task
# Task m1-001: Implement core service

完成一项任务

1. 运行验证命令
2. 确认满足所有标准
3. 提交更改
4. 更新任务状态
5. 转到下一项任务

处理偏离

如果遇到意外模式：

1. 停止——不要继续
2. 记录——说明遇到了什么意外情况
3. 回退——返回到最近的已知良好状态
4. 报告——请求指导
5. 更新——添加规则以防止再次发生

示例

请参阅 references/milestones-example.yaml 和 references/milestone-tasks-example.yaml，查看输出文件示例。