implementation-planning

实施计划

这是严格的指南。 请严格遵循以下规则。

用于创建和管理可跨会话保留的实施计划的说明。

---

结构

实施计划遵循以下目录结构：

docs/planning/implementation/
  {feature-name}/
    index.md              # Navigation hub with progress tracking
    phase-0-*.md          # Prerequisite/setup phase
    phase-1-*.md          # First implementation phase
    phase-2-*.md          # Second implementation phase
    ...
    post-implementation.md # Validation, handoff, troubleshooting

（用户对计划位置的偏好优先于此默认设置。）

阶段与步骤

阶段 = 一份包含相关工作的文档

• 每个阶段都有自己的文件：phase-N-descriptive-name.md
• 阶段保持在 500 行以内 — 这样每个阶段都能与正在编辑的代码一起放入大模型上下文中
• 阶段按数字顺序执行（0、1、2，……）
• 重命名阶段文件时，必须更新 index.md 中的所有引用

步骤 = 阶段中的一个小型工作单元

• 每个步骤都要编号：Step N.1、Step N.2 等（其中 N 是阶段编号）
• 阶段内的步骤按顺序执行
• 每个步骤都应：
  • 能通过一次专注的操作完成（几分钟，而不是几小时）
  • 可独立测试
  • 可提交（使代码库保持可正常工作的状态）

示例：

phase-1-api-endpoints.md contains:
  - Step 1.1: Write failing test for GET /items
  - Step 1.2: Run test to verify it fails
  - Step 1.3: Implement GET /items handler
  - Step 1.4: Run test to verify it passes
  - Step 1.5: Commit

phase-2-database-setup.md contains:
  - Step 2.1: Write failing test for table access
  - Step 2.2: Run test to verify it fails
  - Step 2.3: Define DynamoDB table in CDK
  - Step 2.4: Run test to verify it passes
  - Step 2.5: Commit

编号规则

• 阶段编号连续：0、1、2、3，……
• 阶段 0 始终用于前置条件/设置
• 步骤格式：{phase}.{step} — 阶段 1 的步骤：1.1、1.2、1.3
• 阶段内的步骤必须按顺序执行
• 使用 post-implementation.md 进行验证和交接

---

文件映射

在阶段中定义步骤之前，先列出将要创建或修改的文件及其各自职责。这可以提前确定任务分解方案。

**Files:**
- Create: `src/handlers/get-items.ts` — GET /items Lambda handler
- Create: `tests/handlers/get-items.test.ts` — handler tests
- Modify: `infrastructure/api.ts:45-60` — add route

规则：

• 始终使用准确的文件路径
• 每个文件只承担一项明确职责
• 需要一起更改的文件应放在一起
• 在现有代码库中，遵循既定模式

---

步骤内容

步骤必须包含执行 Agent 所需的一切内容 — 不得使用占位符或含糊其辞。

每个代码步骤都必须包含：

• 完整代码（不是存根或伪代码）
• 要运行的准确命令及预期输出
• 继续之前需要验证的内容

以下内容会导致计划失败 — 绝不可这样写：

• “TBD”、“TODO”、“稍后实现”、“补充详细信息”
• “添加适当的错误处理”/“添加验证”
• “为上述内容编写测试”（但不提供实际测试代码）
• “与步骤 N.1 类似”（应重复相关内容 — Agent 可能会独立加载各个阶段）
• 只描述要做什么，却不说明如何做的步骤

TDD 节奏（适用时）：

1. 编写失败的测试
2. 运行测试，确认其失败
3. 编写能通过测试的最简实现
4. 运行测试，确认其通过
5. 提交

并非每个步骤都需要 TDD（配置更改、CDK 基础设施等），但代码步骤应尽可能遵循这一节奏。

---

索引文件结构

index.md 是唯一的导航和进度跟踪中心：

# {Feature Name} - Implementation Guide

**Last Updated**: YYYY-MM-DD

---

## Quick Navigation

| Phase | Document |
|-------|----------|
| Phase 0 | [Phase Name](./phase-0-*.md) |
| Phase 1 | [Phase Name](./phase-1-*.md) |
| Phase 2 | [Phase Name](./phase-2-*.md) |

---

## Overview

Brief description of what this implementation achieves.

### Prerequisites

Before starting:
- Requirement 1
- Requirement 2

### Implementation Principles

- Key principle 1
- Key principle 2

---

## Progress Tracking

**Current Step**: Phase X, Step X.X - {Step Name}

### Phase 0: {Name}
- [ ] Step 0.1: Description
- [ ] Step 0.2: Description

### Phase 1: {Name}
- [ ] Step 1.1: Description
- [ ] Step 1.2: Description

---

阶段文档结构

## Phase {N}: {Phase Name}

**Goal**: Single sentence describing what this phase achieves.

**Files:**
- Create: `exact/path/to/file.ts`
- Modify: `exact/path/to/existing.ts`
- Test: `tests/exact/path/to/test.ts`

---

### Step {N}.1: {Step Name}

**Goal**: What this step accomplishes.

[Full code, exact commands, expected output]

**Verify**: How to confirm this step worked.

**Commit**: `type: description`

---

### Step {N}.2: {Step Name}

...

限制：

• 阶段文档总长度保持在 500 行以内
• 如果接近 500 行，说明阶段太大 — 应拆分为多个目标明确的阶段
• 不要随意拆分 — 应重新组织工作，使每个阶段都只有一个明确、专注的目标

---

实施工作流

黄金法则：始终遵循计划

未经检查计划，绝不编写代码。

执行 Agent 只加载 index.md 和当前阶段，无需在上下文中加载整个计划。

1. 阅读 index.md — 确认当前进行到哪一步
2. 加载当前阶段 — 严格遵循步骤
3. 如果需要偏离计划 → 停止并进入规划模式

规划模式

当你发现：

• 当前步骤无法按现有写法奏效
• 存在更好的方法
• 缺少依赖项
• 某个假设有误

立即进入规划模式：

1. 停止编写代码
2. 与开发者讨论问题
3. 更新计划，采用新方法
4. 检查后续步骤——这会造成影响吗？
5. 根据原则验证——这是否符合核心原则和模式？
6. 更新 index.md——反映进度跟踪中的任何变更
7. 获得确认后再恢复实施

更新计划时：

• 具体说明：准确记录变更内容及原因
• 不要删除旧方法——将其标记为已被取代
• 保持 index.md 最新

---

一致性检查

每个步骤完成后、提交前进行一次轻量级合理性检查。及时发现偏离——即那些单独看来可行、但无助于实现功能目标的变更。

流程

1. 快速浏览 index.md——概述、实施原则、当前阶段目标。快速检查，无需深入阅读。
2. 根据以下问题检查未提交的差异：
   • 目标一致性：这是否有助于实现功能目标，还是偏离了目标？
   • 架构契合度：是否遵循项目模式？
   • 架构文档：项目是否有架构或设计文档（例如 docs/architecture/、ADR、设计决策）？如果有，此变更是否与任何已记录的决策相矛盾？只检查与变更区域相关的文档——不要重新阅读所有内容。
   • 范围蔓延：此步骤是否引入了计划之外的内容？
3. 结论：
   • ✅ 符合计划——提交。
   • 🟡 轻微偏离——在 index.md 中注明问题，提交，并在阶段结束时复查。
   • 🔴 偏离方向——不要提交。进入规划模式。

规则：

• 仅检查当前步骤的差异，而非整个代码库。
• 这不是完整的代码审查，只检查方向是否正确。
• 🟡 必须在 index.md 中该步骤的复选框旁添加一行说明。

---

阶段完成

阶段完成时：

• 所有步骤均已成功执行
• 所有一致性检查均已通过（解决所有 🟡 标记）
• 所有测试均已通过
• 变更已提交
• Index.md 已更新至下一阶段
• 已验证下一阶段的前置条件

---

范围检查

如果规范涵盖多个相互独立的子系统，建议拆分为多个计划，每个子系统一个计划。每个计划都应独立产出可运行、可测试的软件。

---

创建新的实施计划

1. 范围检查——每个子系统一个计划
2. 创建 index.md——用于导航和进度跟踪
3. 拆分阶段——每个阶段对应一份文档，专注于一个目标
4. 按阶段映射文件——明确路径和职责
5. 将阶段拆分为步骤——步骤应小而可测试、可提交，并包含完整代码
6. 自我审查——检查规范覆盖范围、占位符，并确保各阶段的类型一致
7. 按顺序编号——阶段：0、1、2；步骤：1.1、1.2；2.1、2.2

---

何时创建实施计划

适用于：

• 需要协作、耗时多天的功能
• 包含多个依赖阶段的功能
• 需要谨慎安排顺序的功能
• 需要跨会话跟踪进度的功能

不适用于：

• 单文件变更
• 简单的缺陷修复
• 常规维护任务
• 单步操作

---

调整工作顺序

调整某阶段内的步骤顺序：

1. 更新阶段文档中的步骤编号
2. 更新 index.md 中的引用
3. 确认没有步骤会因顺序调整而受阻

插入新阶段：

1. 创建新的阶段文件
2. 重新编号后续阶段文件及其内部步骤
3. 更新 index.md 中的所有引用

---

持续改进

如果开发者纠正了本技能本应避免的行为，请建议对本技能进行具体修订，以防止今后再次出现同样的问题。