Code Implement

---
name: code-implement
description: 从代码骨架（design-to-code 产出）系统化地填充方法实现、解决 TODO 标记。按骨架批次依赖顺序分批编码，每批先读取骨架契约注释 + 调研结果 + 依赖文档作为参考上下文再补全方法体，同批并行加速。编码完成后验证实现是否满足骨架契约。适用于"骨架编码"、"按骨架实现代码"、"填充骨架"、"implement skeleton"、"开始编码"等场景，或 design-to-code 完成后用户选择"开始编码实施"时触发。
---

# Code Implement（骨架编码实施）

## 概述

**目的**：系统化地从代码骨架填充方法实现、解决 TODO 标记，确保实现与骨架契约一致，并与项目现有代码风格统一。

**核心问题**：design-to-code 生成了骨架+契约注释后，AI 编码是"无结构的"——打开文件就写，没有上下文准备、没有批次策略、没有契约验证，容易偏离设计意图或与现有代码风格不一致。

**解决方案**：按骨架批次的依赖顺序分批编码，每批编码前先读取骨架契约注释 + code-survey 调研结果 + dependency-docs 依赖文档作为参考上下文，再就地补全方法体、解决 TODO 标记。编码完成后验证实现是否满足骨架契约。

## 定位

```
design-craft → ... → design-to-code → code-implement → implementation-report
   设计产出         骨架+契约注释        系统化填充实现      归档实现结果
```

- **输入**：design-to-code 产出的骨架文件 + skeleton-status.md + code-survey 调研结果 + dependency-docs 依赖文档
- **输出**：已实现的代码文件（方法体已填充、TODO 已解决、契约注释保留为实施参考）
- **边界**：只管"按骨架契约填充实现"，不管"骨架怎么生成"（design-to-code 负责）和"实现后怎么归档"（implementation-report 负责）

## 核心原则

1. **契约优先**：编码前必须读取骨架中的契约注释，理解每个方法的参数、返回值、异常、预期行为
2. **上下文准备**：每批编码前先读取 code-survey 调研结果 + dependency-docs 依赖文档 + 设计文档（按需），确保实现与项目风格一致
3. **依赖拓扑序**：复用骨架生成的批次顺序（依赖 DAG），被依赖的批次先编码
4. **分批编码 + 并行加速**：复用骨架批次的依赖结构，顺序无关批次自动调用 task-dispatch 并行编码
5. **TODO 就地解决**：修改文件的 TODO 标记在编码时就地解决，不集中处理
6. **契约验证**：编码完成后验证实现是否满足骨架契约（签名一致、异常覆盖、行为完整）
7. **骨架注释为准**：当骨架契约注释与设计文档内容不一致时，**以骨架中的契约注释为准**——骨架是 design-to-code 对设计文档的精确转译，如果转译过程中有调整（如接口签名微调、异常场景补充），骨架注释才是编码 AI 应遵循的最终契约

## 工作流总览

```
阶段 0：定位骨架与参考文档 → 读取 skeleton-status.md + code-survey + dependency-docs + 设计文档
阶段 1：编码上下文构建     → 从参考文档提取编码所需的风格、模式、依赖信息
阶段 2：编码批次规划       → 复用骨架批次结构，确定编码顺序和并行策略
阶段 3：分批编码实施       → 顺序无关批次调用 task-dispatch 并行；依赖批次串行
阶段 4：实现契约验证       → 比对实现代码与骨架契约，检查遗漏或偏差
阶段 5：落盘与状态更新     → 更新 skeleton-status.md，标记已实现方法
```

**未得到用户对当前阶段的确认前，不进入下一阶段。**

---

## 阶段 0：定位骨架与参考文档

### 输入来源

按优先级尝试：
1. **用户指定**：用户直接提供骨架文件目录或 skeleton-status.md 路径
2. **默认位置**：`.requirements/{YYYY-MM-DD}-{功能名称}/design/skeleton-status.md`

**骨架文件定位**：从 skeleton-status.md 的"骨架文件清单"表中读取每个骨架文件的项目相对路径，结合项目根目录（从用户指定或 workspace 根推断）计算出绝对路径。子 agent 编码时需使用绝对路径读取骨架文件。

### 读取内容

| 文件 | 内容 | 作用 |
|------|------|------|
| `skeleton-status.md` | 骨架生成状态：批次结构、文件清单、一致性验证结果 | 确定编码批次、定位骨架文件 |
| 骨架文件组 | 含契约注释的代码骨架文件 | 编码的直接目标 |
| `reference/code-survey.md` | 代码调研结果：风格、架构、模式、惯例（code-survey 产出） | 编码时参考项目现有风格和模式 |
| `dependencies/` 目录 | 第三方依赖文档（dependency-docs 产出） | 实现调用外部 API/SDK 时查阅接口细节 |
| `DESIGN.md` + 子文档 | 设计文档（按需深查） | 契约注释不够详细时回查设计原文 |

### 参考文档检测

逐一检测参考文档是否存在，不存在则跳过：

| 参考文档 | 检测位置 | 不存在时的处理 |
|----------|---------|---------------|
| code-survey | 设计文档目录下 `reference/code-survey.md` | 跳过，编码时凭骨架注释+现有代码推断风格 |
| dependency-docs | 设计文档目录下 `dependencies/README.md` | 跳过，编码时凭骨架注释中的依赖标注自行查阅 |
| 设计文档 | 设计文档目录下 `DESIGN.md` | 跳过，仅依赖骨架契约注释 |

### 输出格式

```text
📂 骨架与参考文档定位

骨架状态：skeleton-status.md（{路径}）
参考文档：
  - code-survey：✅ 已定位 / ⚠️ 未检测到
  - dependency-docs：✅ 已定位（N 个依赖文档） / ⚠️ 未检测到
  - 设计文档：✅ 已定位 / ⚠️ 未检测到

骨架规模：X 个文件（新增 Y / 修改 Z）、A 个类、B 个方法、C 个 TODO 标记

确认后进入阶段 1 构建编码上下文。
```

---

## 阶段 1：编码上下文构建

从参考文档中提取编码所需的**风格、模式、依赖信息**。只提取与当前骨架相关的信息，不泛读全文。

### 时效性检测

先比对参考文档与骨架生成的时间顺序：
- **code-survey 的时间早于 design-to-code**（从 skeleton-status.md 生成时间判断）：⚠️ code-survey 可能已过时（骨架文件已写入项目，代码状态变化），编码时优先参考骨架文件中的契约注释和现有代码实际状态
- **code-survey 的时间晚于或等于 design-to-code**：✅ code-survey 反映最新代码状态，可正常参考

### 提取维度

| 来源 | 提取内容 | 编码用途 |
|------|----------|----------|
| code-survey | 代码风格、错误处理模式、测试模式、API 约定 | 确保实现与项目风格一致 |
| dependency-docs | 每个骨架注释中引用的依赖文档路径 → 读取对应依赖文档的接口清单、认证方式、限流策略 | 实现调用外部 API/SDK 时使用正确接口 |
| 骨架契约注释 | 方法签名、参数/返回值/异常/预期行为、依赖文档引用 | 编码的直接契约依据 |
| 设计文档（按需） | 契约注释不够详细时的补充信息 | 深入理解设计意图 |

### 提取策略

- **code-survey**：全文读取，提取所有维度（文件不长，全读成本可控）
- **dependency-docs**：只读取骨架注释中明确引用的依赖文档（按需读取，不全读）
- **设计文档**：仅当骨架契约注释中的信息不足以完成编码时，按锚点定位回查

### 输出格式

```text
🔍 编码上下文提取

风格参考（来自 code-survey）：
  - 代码风格：{简述}
  - 错误处理：{简述}
  - API 约定：{简述}

依赖参考（来自 dependency-docs）：
  - {依赖1}：接口清单 N 个，认证方式 {...}
  - {依赖2}：接口清单 M 个，限流策略 {...}

契约核心（来自骨架注释）：
  - S-01：{N} 个方法需实现，{M} 个 TODO 需解决
  - S-02：{K} 个方法需实现，{L} 个 TODO 需解决

确认上下文充分，有无遗漏。
```

---

## 阶段 2：编码批次规划

**直接复用骨架生成的批次结构**，不重新排序。

### 复用规则

- 从 `skeleton-status.md` 的"批次状态"表读取批次划分
- 从设计文档的依赖 DAG 读取批次间依赖关系
- 顺序无关批次 → 可并行编码（task-dispatch）
- 依赖批次 → 串行编码（主 agent）

### 额外考量

骨架批次规划已考虑了依赖关系，但编码时还需注意：

| 场景 | 额外处理 |
|------|----------|
| 同一文件跨批次修改 | 后批编码时需读取前批已实现的代码，避免覆盖 |
| TODO 标记跨子需求分布 | 按 TODO 所属子需求分配到对应批次。同一文件跨批次修改时，后批编码前必须读取前批已实现的最新版本 |
| 骨架文件已被手动修改 | 读取最新文件内容，不依赖 skeleton-status.md 的快照 |

### 输出格式

```text
🔗 编码批次规划

复用骨架批次结构：
  第 1 批 [顺序无关]：S-01（X 方法 / Y TODO）→ task-dispatch 并行编码
  第 2 批 [依赖前批]：S-03（K 方法 / L TODO）→ 主 agent 串行编码

跨批次注意：
  - {文件} 被 S-01 和 S-03 共同修改 → 第 2 批编码时需读取第 1 批实现结果

确认批次规划合理。
```

---

## 阶段 3：分批编码实施

核心阶段。**每批独立编码 + 独立验证**。

### 执行策略

```
┌─ 子需求 < 3：单批次 ───────────────────────┐
│  主 agent 直接编码全部骨架 → 验证 → 落盘      │
└─────────────────────────────────────────────┘

┌─ 子需求 ≥ 3：分批次 ─────────────────────────────────┐
│                                                       │
│  第 1 批 [顺序无关] → task-dispatch 并行 ← 加速！     │
│       ↓                                               │
│  第 2 批 [顺序无关] → task-dispatch 并行 ← 加速！     │
│       ↓                                               │
│  第 2 批 [依赖前批] → 主 agent 串行                    │
│       ↓                                               │
│  ... 直到全部完成 → 阶段 4 全局契约验证                │
└─────────────────────────────────────────────────────────┘
```

### 并行判定

| 当前批次特征 | 策略 |
|-----------|------|
| 仅 1 个子需求 | 主 agent 直接编码 |
| ≥ 2 个子需求（顺序无关） | 调用 `task-dispatch` skill 并行编码 |
| 有依赖关系 | 主 agent 串行编码 |

### task-dispatch 调度要点

**task-name**：`implement-{功能简称}`（如 `implement-user-system`）

**子任务拆分**：每个顺序无关的子需求拆为一个子任务：

```text
| 编号 | 子任务 | 子需求 | 涉及文件 | 待实现方法 | 待解决 TODO |
|------|--------|--------|----------|-----------|-------------|
| I-01 | S-01 编码 | 用户服务 | user_service.py | 3 方法 | 1 TODO |
| I-02 | S-02 编码 | 订单服务 | order_service.py | 4 方法 | 0 TODO |
```

独立性校验：各子需求之间无文件交集（由骨架批次规划保证），可同批并行。

**子 agent prompt 要点**：

```
你是子 agent，负责编码子需求 S-{NN}：{名称} 的方法实现 + 解决 TODO 标记。

## 骨架文件
{列出该子需求涉及的骨架文件路径，子 agent 需先读取这些文件}

## 编码上下文

### 风格参考（来自 code-survey）
{从阶段 1 提取的风格参考信息}

### 依赖参考（来自 dependency-docs）
{从阶段 1 提取的、与该子需求相关的依赖文档信息}

依赖文档路径（子 agent 需读取原文以获取接口细节）：
  - dependencies/{依赖1名称}.md → {文件绝对路径}
  - dependencies/{依赖2名称}.md → {文件绝对路径}

## 输出目录
产出：.codebuddy/task-dispatch/implement-{功能简称}/subtasks/I-{NN}/code/
  - 代码按项目相对路径摆放（如 src/services/user_service.py）
报告：.codebuddy/task-dispatch/implement-{功能简称}/subtasks/I-{NN}/report.md

## 编码步骤

按顺序执行：
1. 读取骨架文件，理解契约注释（方法签名、参数、返回值、异常、预期行为）
   ⚠️ **骨架注释为准**：若骨架契约注释与设计文档内容不一致，以骨架注释为准——骨架是设计文档的精确转译，编码遵循骨架中的最终契约
2. 读取 code-survey 调研结果，确保实现符合项目风格
3. 若契约注释引用了依赖文档，读取对应 dependency-docs 了解接口细节
4. 按契约注释就地补全方法体（替换占位符为实现代码）
5. 就地解决 TODO 标记（替换/修改/删除，按变更类型处理）
6. 保留契约注释（不删除，作为实施参考留存）

## 编码原则

### 新增方法编码
- 读取契约注释理解预期行为
- 按"预期行为"中的步骤顺序实现方法体
- 异常处理按契约注释中的"异常"字段实现
- 确保返回值类型和结构与契约一致
- 若引用了依赖文档，按依赖文档的接口清单和认证方式实现调用

### TODO 标记解决
按变更类型分级处理：

| 变更类型 | 解决策略 |
|----------|----------|
| 新增方法 | 删除 TODO 标记，在 TODO 位置实现完整方法体 |
| 修改方法 | 删除 TODO 标记，按 TODO 中描述的变更点修改原实现 |
| 删除方法 | 删除 TODO 标记 + 删除原方法（仅当 TODO 注明可安全删除时），否则保留 TODO 并标注"待人工确认" |
| 重构/替换 | 删除 TODO 标记，按 TODO 中描述的新逻辑替换原实现，确保兼容性要求满足 |

### 契约注释处理
- 保留契约注释作为实施参考，不删除
- 若方法已实现且契约注释过长（> 15 行），可精简为 ≤ 8 行（保留：参数、返回值、异常、预期行为概括、依赖文档、设计文档锚点）

### 依赖文档使用
- 契约注释中标注了"依赖文档：dependencies/{名称}.md"的方法，编码时必须读取对应依赖文档
- 调用外部 API 时按依赖文档的接口清单、认证方式、限流策略实现
- 不猜测外部 API 的参数和返回值格式，严格按依赖文档实现

## 批内自检
编码后自查：
☐ 所有占位符已替换为实现代码
☐ 所有 TODO 标记已解决或标注"待人工确认"
☐ 方法签名与契约注释一致（未擅自修改）
☐ 异常处理覆盖契约注释中的所有异常场景
☐ 返回值类型和结构与契约一致
☐ 实现风格与 code-survey 调研结果一致
☐ 涉及第三方依赖的方法按依赖文档实现

完成后写 report.md，列出产出文件和自检结果。
```

### 合并

主 agent 收集各子 agent 产出，按项目相对路径合并已实现文件到项目源码目录。注意：
- 同批顺序无关的产出无文件交集，直接合并
- 跨批次时，后批需读取前批已实现的最新文件再编码

### 批次完成确认

```text
✅ 第 {N} 批编码完成

并行子任务：M 个（全部完成）
已实现方法：X 个
已解决 TODO：Y 个（待人工确认：Z 个）

进入下一批 / 进入阶段 4 契约验证
```

---

## 阶段 4：实现契约验证

全部批次编码完成后，将实现代码与骨架契约逐项比对。

### 验证维度

| 维度 | 验证内容 | 通过标准 |
|------|----------|----------|
| 方法覆盖 | 骨架中所有占位符方法都已实现 | 100% 覆盖 |
| 签名一致 | 实现后的方法签名与骨架契约注释一致 | 零偏差 |
| 异常覆盖 | 实现中处理了契约注释中的所有异常场景 | 100% 覆盖 |
| 行为完整 | 实现逻辑覆盖契约注释中的"预期行为"步骤 | ≥ 95% 覆盖 |
| TODO 解决 | 所有 TODO 标记已解决或标注"待人工确认" | 100% 处理 |
| 依赖正确 | 调用外部 API/SDK 的实现与依赖文档一致 | 零偏差 |
| 风格一致 | 命名规范、注释风格、异常模式、import 组织方式与 code-survey 调研结果一致 | 无明显偏差 |

### 输出格式

```text
📐 实现契约验证

验证范围：全部 N 批

逐项核对结果：
  ✅ 方法覆盖：{X}/{X}，100%
  ✅ 签名一致：零偏差
  ⚠️ TODO 解决：{Y-1}/{Y}，1 个标注"待人工确认" → {TODO 内容}
  ✅ 依赖正确：零偏差

一致性结果：✅ 一致 / ⚠️ 存在偏差（列出偏差项）

### 冲突处理规则

编码过程中若发现骨架契约注释与设计文档不一致：
- **以骨架契约注释为准**——骨架是 design-to-code 对设计文档的精确转译，转译中的调整（如签名微调、异常补充）反映了更准确的实施契约
- 不回退设计文档去"纠正"骨架注释
- 若偏差显著且怀疑骨架有误，向用户确认后再调整

偏差处理：遗漏方法补充实现；签名偏差以骨架契约为准修正；TODO 争议提交用户确认
```

验证通过后进入阶段 5 落盘。

---

## 阶段 5：落盘与状态更新

### 更新 skeleton-status.md

在原 `skeleton-status.md` 中追加编码实施状态：

```markdown
## 编码实施状态

编码时间：{YYYY-MM-DD HH:MM}
编码批数：共 N 批（其中 M 批使用 task-dispatch 并行）

### 实施进度

| 子需求 | 待实现方法 | 已实现方法 | 待解决 TODO | 已解决 TODO | 状态 |
|--------|-----------|-----------|-------------|-------------|------|
| S-01   | 5         | 5         | 1           | 1           | ✅ 已完成 |
| S-02   | 4         | 4         | 0           | 0           | ✅ 已完成 |

### 待人工确认项
{列出标注"待人工确认"的 TODO 或契约偏差项，无则写"无"}

### 契约验证
- 验证结果：✅ 一致 / ⚠️ 存在偏差
- 偏差记录：无 / {偏差列表}
```

### 输出格式

```text
✅ 代码实施已落盘

已实现文件：已写入项目源码目录
状态更新：{路径}/skeleton-status.md（追加编码实施状态）

统计：
  - 已实现方法：X 个
  - 已解决 TODO：Y 个（待人工确认：Z 个）
  - 契约验证：✅ 一致 / ⚠️ 存在偏差

🚀 后续行动选择
1. 📋 归档实现结果（implementation-report）
2. 🧪 编写测试（test-planner）
3. ⏭️ 暂不后续
```

---

## 反模式（不要做）

### 上下文准备层面
- ❌ 不读骨架契约注释直接凭记忆写代码——契约注释就是编码依据
- ❌ 不读 code-survey 调研结果直接按自己习惯写——应与项目风格一致
- ❌ 不读 dependency-docs 依赖文档凭猜测调用外部 API——应按文档精确实现
- ❌ 跳过阶段 0 直接编码——参考文档可能包含关键风格/依赖信息
- ❌ 骨架注释与设计文档不一致时回退设计文档"纠正"骨架——骨架注释为准，是编码应遵循的最终契约

### 编码执行层面
- ❌ 擅自修改方法签名——发现契约问题应回到 design-craft 修订设计
- ❌ 删除契约注释——保留作为实施参考，可精简但不能删除
- ❌ 忽略 TODO 标记中的影响范围和兼容性要求——编码前必须理解这些信息
- ❌ 把多个 TODO 标记合并处理——应就地逐一解决
- ❌ 实现方法时遗漏契约注释中的异常场景

### 验证层面
- ❌ 跳过契约验证直接交付——偏差会累积到后续阶段
- ❌ 契约偏差时自行判断以实现为准——应以骨架契约为准修正实现
- ❌ "待人工确认"项自行决定——必须提交用户确认

---

## 附加资源

- 骨架生成：`design-to-code` skill（生成骨架+契约注释）
- 代码调研：`code-survey` skill（编码前了解项目风格和模式）
- 依赖文档：`dependency-docs` skill（整理第三方依赖文档）
- 并行任务调度：`task-dispatch` skill（顺序无关批次并行编码）
- 实现结果归档：`implementation-report` skill