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	跳过，仅依赖骨架契约注释

输出格式

📂 骨架与参考文档定位

骨架状态：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：只读取骨架注释中明确引用的依赖文档（按需读取，不全读）
• 设计文档：仅当骨架契约注释中的信息不足以完成编码时，按锚点定位回查

输出格式

🔍 编码上下文提取

风格参考（来自 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 的快照

输出格式

🔗 编码批次规划

复用骨架批次结构：
  第 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）

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

| 编号 | 子任务 | 子需求 | 涉及文件 | 待实现方法 | 待解决 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 产出，按项目相对路径合并已实现文件到项目源码目录。注意：

• 同批顺序无关的产出无文件交集，直接合并
• 跨批次时，后批需读取前批已实现的最新文件再编码

批次完成确认

✅ 第 {N} 批编码完成

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

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

---

阶段 4：实现契约验证

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

验证维度

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

输出格式

📐 实现契约验证

验证范围：全部 N 批

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

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

### 冲突处理规则

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

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

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

---

阶段 5：落盘与状态更新

更新 skeleton-status.md

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

## 编码实施状态

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

### 实施进度

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

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

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

输出格式

✅ 代码实施已落盘

已实现文件：已写入项目源码目录
状态更新：{路径}/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