Design To Code

---
name: design-to-code
description: 从设计文档生成代码骨架（文件 + 类 + 方法），把接口契约、数据模型、异常处理写进契约级注释，让后续编码不必反复翻文档；生成前先与用户确认架构风格与设计模式。触发："生成代码骨架"、"搭骨架"、"按设计生成代码结构"，或设计完成后准备编码。
---

# Design-to-Code（设计到代码骨架）

## 概述

**目的**：将设计文档中的结构设计转化为代码骨架，并将契约信息以注释形式就地嵌入，消除 AI 编码时的文档-代码上下文切换。

**核心问题**：AI 拿到设计文档后编码，需要反复查阅文档，导致 token 消耗大、信息稀释、偏离设计意图。

**解决方案**：设计完成后直接生成代码骨架（文件、类、方法），并就地嵌入契约级注释。AI 编码时打开代码文件即可看到完整实施契约，无需切换到外部文档——代码注释即文档。同批顺序无关时自动调用 `task-dispatch` 并行生成以加速。

## 定位

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

- **输入**：design-craft 产出的设计文档目录（`design/DESIGN.md` + 子文档，也兼容单文档快速通道）；走并行路线时另加 **design-craft 阶段 5.5.1 的模块划分**（决定桩与挂载点的落点）与 **5.5.2 的骨架交付清单**（11 项，含数据走向预演链路场景 / 横切约定 + 非功能预算 / 权限模型）
- **输出**：项目源码目录中的代码骨架文件（文件已创建、类已定义、方法已声明、契约已注释，方法体用语言原生占位符）

### 并行路线的骨架差异（design-craft 阶段 5.5 判定为"走并行链"时）

默认骨架是"给单个窗口顺序填充用"；走多窗口并行时，骨架还要承担**清空共享面**的职责，需额外满足：

| 差异项 | 顺序路线 | 并行路线 |
|--------|---------|---------|
| 方法体占位 | 语言原生占位符 | **抛 `NotImplemented`**（保证主干编译通过且调用即失败，不静默返回假值） |
| **桩标记（★ 供桩残留扫描）** | 不需要 | 桩体必须注入**自定义统一标记**（形如 `STUB:{SR-XX}:{方法名}`），并把**扫描模式写入单一来源 `.delivery/stub-pattern`**（一行正则，如 `STUB:`）——`verify/run.sh` 与 `premerge-check.sh` 都从它读，**避免三处各写一份而漂移**。**不要用 `NotImplemented` 当扫描模式**：抽象基类 / 协议声明等语言惯用法也用它 → 大面积误报 → 狼来了导致真残留被忽略 |
| 契约注释 | 参数 / 返回值 / 异常 / 预期行为 | **追加语义契约 10 项**（前置 / 后置 / 空值 / 错误 / 单位精度 / 时间 / 幂等 / 并发 / 事务 / 副作用） |
| 挂载点 | 按需 | **在现有大文件预留挂载位**（含挂载顺序） |
| 全局清单 / 数据模型 / 公共代码 / **横切约定 + 非功能预算** / **权限模型** | 设计文档说明即可 | **落成代码或配置并声明只读**（之后只增不改）；后两类见 5.5.2 第 10 / 11 项，**最易漏且不冲突不报错**。横切约定的典型落点：统一 logger formatter / trace 中间件 / 精度与时区常量 / ID 生成器 / 分页封装 / **错误码号段常量表**（按砖头分段）——落在公共代码区，即第 6 项冻结范围 |
| mock | 无 | **两类一并生成**：① 跨砖头依赖 mock（给调用方用）② **桩的 mock 版**（给数据走向预演填满全链路用）。含失败 / 超时 / 空 / 脏数据异常路径 |
| **数据走向预演测试** | 无 | **一并生成**（按 `design-craft` 阶段 5.5.2 第 8 项给的链路场景，逐跳断言；**必须用 mock 填满全链路**）；落 `tests/data-flow/`，**不按砖头分组**（它天然跨砖头，测的是链路不是单个砖头） |
| **片级验收测试骨架** | 无 | 按 `design-craft` 阶段 5.5.2 第 9 项的验收清单生成；落 `tests/{SR-XX}/`，**断言由验收项派生（不是照着实现写）**，骨架期应为红 |
| **测试与脚手架的落点（★ 分开）** | 按需 | **产品资产**（四类测试）→ `tests/` 下；**脚手架**（mock）→ `.delivery/mocks/`。判据：交付上线后还会因产品行为变化而失败 → 提交；否则 → 忽略（完整约定见 `delivery-slicing`「测试与脚手架的归属」） |
| 验收 | 骨架可编译 | 骨架可编译 **+ 分层测试达其骨架期期望**（见下）+ **桩标记全量注入（供 ⑥ 号拒收门扫描）** |

> ### ★ 桩残留扫描的三个易错点（都属「会静默出错」）
>
> | # | 易错 | 后果 |
> |---|------|------|
> | 1 | **扫描对象用 `git grep`** | 它只扫**已跟踪**文件，而实现期的桩正是**新建未提交**的 → 扫描**恒为空** → **假绿**（**比不扫更危险**：它给出"已检查且通过"的错误结论）→ 必须扫**工作区文件系统**（`grep -rn`） |
> | 2 | **用语言原生占位符当模式**（如 `NotImplemented`） | 抽象方法 / 协议声明等**语言惯用法**也用它 → 大面积误报 → 狼来了 → **真残留被忽略** |
> | 3 | **契约 / 文档文件里写了完整标记字面量** | 它会**命中自己**（实测：契约注释里写 `STUB:SR-01:*` → 必然误报）→ 契约里只写"标记模式见 `.delivery/stub-pattern`" |
>
> **扫不到的代价**：漏实现的接口调用即抛异常，而**契约测试只覆盖有测例的接口** ——
> 漏实现的恰是**没被覆盖**的那些。所以它是**独立机械扫描**，不读测试结论。

**分层测试期望值**（全流程判别标准，各相关文档必须一致）：

| 测试组 | 落盘位置 | 骨架期 | 窗口期（本砖头） | 拼接期 | 验什么 |
|--------|---------|-------|----------------|--------|--------|
| 契约测试 · **本砖头组** | `tests/contract/{SR-XX}/` | 红 | **绿** | 绿 | 本砖头是否兑现契约（形状） |
| 契约测试 · 其他组 | `tests/contract/{其他}/` | 红 | **不跑**（非本窗口职责） | 绿 | — |
| **片级验收测试** | `tests/{SR-XX}/` | 红 | **绿** | 绿 | **本砖头是否达成需求验收项**（功能） |
| 数据走向预演（**全 mock**） | `tests/data-flow/` | **绿** | 绿 | 绿（换真实实现） | 断言链是否完整可执行 |
| 挂载点测试 | `tests/mount/` | 红 | 红（**预期**，别的挂载位还没实现） | 绿 | 装配是否接通 |

> **契约测试与片级验收测试的区别**：前者验"接口是否兑现契约"（形状，由 `sub-requirements/{SR-XX}/contract/` 的契约快照派生）；后者验"**需求意图是否达成**"（功能，由 `5.5.1 承接的验收项` 派生）。**两者都必须由骨架阶段生成（红），窗口只负责让它们变绿**——窗口自己写验收断言 = 自己出题自己答。

**契约测试必须按砖头分组**：

- 分组口径 = **被测接口的实现方**——`tests/contract/SR-01/` 放"SR-01 所提供接口"的契约测试
- **为什么必须分组**：不分组的全局契约测试，在窗口分支上永远无法变绿（别人的桩还没实现）→ 窗口的完成定义不可达 → 窗口最可能的动作是**改测试来凑绿**，反而制造契约漂移
- 分组后每个窗口只对本组负责，完成定义可达

> **「红是健康，绿是警报」**：骨架期契约测试若出现 `passed`，说明桩返回了看似合法的默认值（`None` / `[]`）——那是**假绿**，拼接期也不会暴露，必须归零。
> **数据走向预演必须用 mock 填满全链路**：用 `NotImplemented` 桩会跑到第二跳就抛异常，后面的贯通断言根本执行不到。
> 数据走向预演红了 = **契约链有缺口**（缺字段 / 单位不一致 / 时区不一致）——此时改零成本，**不要带缺进并行**。

> 骨架核验与预演的 SSOT 在 `delivery-slicing`；生成完成后即交由它做 **阶段 0 骨架完备性核验**（存在性）与 **阶段 0.5 骨架预演**（可执行验证：零上下文预演 / 分层测试期望值 / 数据走向预演 / 覆盖反向 / 独立核验方）。
- **边界**：只管"从设计文档生成骨架结构 + 嵌入契约注释"，不管"怎么填充实现"（由 `code-implement` skill 负责）

## 核心原则

1. **骨架即实施指南**：代码文件本身就是实施指南，注释即文档，AI 编码时无需再读外部设计文档
2. **契约级注释**：类级概述类的作用与关键约束；方法级写明参数、返回值、异常、预期行为。不抄全文，只写契约
3. **签名即契约**：接口签名（方法名、路径、参数类型、返回值、异常）必须原样从设计文档抄入骨架
4. **依赖拓扑序**：骨架生成按子需求依赖 DAG 的拓扑序分批进行
5. **分批生成 + 并行加速**：子需求 ≥ 3 时强制分批，同批顺序无关时自动调用 task-dispatch 并行生成
6. **占位符合语言习惯**：方法体用语言原生占位符（Python `...`、Java `throw new UnsupportedOperationException()`、Go `panic("not implemented")`、TS `throw new Error("not implemented")`），确保骨架可被 IDE 解析无语法错误
7. **变更可更新**：设计变更后询问用户是否更新骨架，确认后仅重新生成受影响批次，不覆盖已完成批次的已填实现
8. **架构与模式前置评估**：生成骨架前先评估是否适用某种架构风格或设计模式（可读性、扩展性、可维护性、可测试性、复用性等），**与用户确认方案后才开始编写骨架**；无可适用信号时明确告知"无需引入额外模式"

## 工作流总览

```
阶段 0：定位设计文档      → 识别设计文档目录，读取父文档 + 子文档
阶段 1：提取骨架信息      → 提取文件路径、类结构、方法签名、数据模型字段、异常定义
阶段 2：依赖排序与批次划分 → 复用设计文档 DAG，划分生成批次，识别顺序无关批次
阶段 3：架构与设计模式评估 → 分析设计特征，推荐架构风格/设计模式以提升可读性、扩展性等，与用户确认
阶段 4：分批生成代码骨架  → 顺序无关批次调用 task-dispatch 并行；依赖批次串行
阶段 5：骨架一致性验证    → 比对骨架注释与设计文档，检查遗漏或偏差
阶段 6：落盘与集成        → 写入项目源码目录
阶段 7（可选）：设计变更更新 → 检测变更后询问是否更新骨架
```

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

---

## 阶段 0：定位设计文档

### 输入来源

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

### 读取内容

| 文件 | 内容 | 作用 |
|------|------|------|
| `DESIGN.md` | 父文档：需求背景、一览图、总体方案、全局风险 | 提取全局约束和跨子需求依赖 |
| `*_S{NN}_*_DESIGN.md` | 子文档：术语、现状、方案、数据模型、接口设计等 | 提取每个子需求的骨架信息 |

### 依赖文档检测

在设计文档目录下检测 `dependencies/` 目录（`dependency-docs` skill 的产出）：

- **存在**：读取 `dependencies/README.md` 索引，获取每个依赖的名称和文档路径。在阶段 1 提取骨架信息时，将方法/类涉及的第三方依赖关联到对应依赖文档路径
- **不存在**：跳过依赖文档引用，在注释中不标注"依赖文档"字段

### 单文档检测

若 `*_S{NN}_*_DESIGN.md` 匹配为空，判定为**单文档场景**：将 `DESIGN.md` 按章节拆分为虚拟子需求，阶段 2 排序简化为"按章节出现顺序"。

### 非 design-craft 来源检测

读取 `DESIGN.md` 后检查是否包含 design-craft 特征标记：
- **匹配**：按设计文档章节名进行提取
- **不匹配**：输出警告，询问用户是否继续。确认后按章节名模糊匹配提取规则

### 输出格式

```text
📂 设计文档定位

来源：{路径}
父文档：DESIGN.md（N 个全局章）
子文档：
  - S-01：{名称}（M 章）
  - S-02：{名称}（K 章）

校验结果：✅ 完整 / ⚠️ 存在以下问题：<...>

确认后进入阶段 1 提取骨架信息。
```

---

## 阶段 1：提取骨架信息

从设计文档中提取生成代码骨架所需的全部信息。**只提取结构信息和契约信息，不提取决策理由、AS-IS、备选方案。**

### 提取规则

| 章节类型 | 提取内容 | 用于骨架的什么 |
|----------|----------|---------------|
| 方案(TO-BE) - 新增文件 | 每个新增文件的完整路径 | 创建文件 |
| 方案(TO-BE) - 修改文件 | 每个修改文件的完整路径 + 变更类型（新增/修改/删除）+ 变更定位（哪个类/方法/字段）+ 变更描述 + 影响范围 | 在现有文件上标记 TODO 并插入/修改代码 |
| 接口设计 | 每个接口的完整签名（方法、路径、参数、返回值、异常）+ 行为描述 | 方法声明 + 方法级契约注释 |
| 数据模型 | 每个新增/修改字段（名、类型、默认值、含义）+ 模型间关系 | 类定义 + 字段声明 + 字段注释 |
| 异常处理 | 每个异常场景 → 触发条件 → 行为 → 是否对外暴露 | 方法级注释中的异常说明 |
| 时序图 - 关键步骤 | 时序图中的关键消息传递步骤 | 方法级注释中的"实现步骤"提示 |
| 性能安全 | 每个性能/安全约束 | 类级或方法级注释中的约束说明 |
| 第三方依赖 | 每个方法/类使用的第三方依赖名称 + 依赖文档路径（若 dependency-docs 已产出） | 方法级或类级注释中的"依赖文档"字段 |
| 影响范围 | 每个受影响的外部模块/系统 | 类级注释中的"影响范围"说明 |
| 全局风险 | 每个跨子需求风险 + 缓解措施 | 全局约束文件注释 |

### 不提取的内容

- 现状章(AS-IS)、术语章、决策理由、被否决方案、时序图的图元

### 修改文件提取细则

修改文件与新建文件的提取策略不同——修改文件需要**精确定位变更点**，而非生成完整骨架。

**变更类型分级**：

| 变更类型 | 风险等级 | 提取要求 | 骨架中的处理方式 |
|----------|---------|----------|-----------------|
| 新增（新增方法/字段/类） | 低 | 提取新增要素的完整签名 + 契约信息 | TODO 标记 + 占位方法体 |
| 修改（修改已有方法签名或行为） | 中 | 提取原签名 → 新签名 → 变更点 | TODO 标记 + 保留原实现 + 注明变更 |
| 删除（删除已有方法/字段） | 中 | 提取被删除要素 + 影响范围 | TODO 标记 + 注明删除原因和影响 |
| 重构/替换（替换整个逻辑流程） | 高 | 提取原逻辑 → 新逻辑 + 兼容性要求 | TODO 标记 + 影响范围 + 兼容性说明 |

**定位信息**：每个修改点必须提取：
- 目标文件路径
- 目标类名
- 目标方法名或字段名（类级 + 方法名定位；行号定位为可选辅助信息）
- 变更类型（新增/修改/删除/重构）
- 变更描述（一句话说明改什么、为什么改）
- 影响范围（哪些调用方/依赖方会受影响）

### 提取粒度约束

文件级 → 类级 → 方法级 → 字段级，每级独立提取不合并。未匹配提取规则的章节按段落逐条提取，标注 `§ 章节名 [未识别类型]`。

### 输出格式

```text
🔍 骨架信息提取

S-01：{子需求名称}
  文件：X 个（新增 Y / 修改 Z）｜ 类：A 个 ｜ 方法：B 个 ｜ 字段：C 个 ｜ 异常场景：D 个

S-02：{子需求名称}
  ...

全局约束：K 条

依赖文档关联：{N 个依赖已关联文档路径 / 未检测到 dependencies/ 目录，跳过依赖引用}
  - OpenAI API → dependencies/openai-api.md
  - Stripe → dependencies/stripe.md

确认提取全面性，有无遗漏或多余。
```

---

## 阶段 2：依赖排序与批次划分

### 排序规则

复用设计文档的依赖 DAG：
1. **父文档全局约束**排最前
2. **无依赖的子需求**最先生成
3. **被依赖的子需求**排在依赖它的子需求之前
4. **同一子需求内**按：文件创建 → 数据模型（类+字段）→ 接口实现（方法声明）→ 异常处理

### 批次划分规则

| 子需求数量 | 划分策略 |
|-----------|----------|
| 1-2 个 | 单批次一次性生成 |
| ≥ 3 个 | **强制分批**，按依赖层级划分 |

### 顺序无关批次识别

同一依赖层级中**无交叉依赖**的批次标记为顺序无关：

**判定规则**：两个批次 A、B 在同一依赖层级，且 A 不依赖 B、B 不依赖 A → **顺序无关，可并行**。

**示例**：
```
S-01（无依赖）  ─┬─→ S-03（依赖 S-01）
                 │
S-02（无依赖）  ─┼─→ S-04（依赖 S-02）
                 │
                 └─→ S-05（依赖 S-01, S-02）

批次划分：
  第 1 批 [顺序无关]：S-01, S-02 — 可并行
  第 2 批 [顺序无关]：S-03, S-04 — 可并行
  第 3 批 [依赖前批]：S-05 — 需等前两批
```

### 排序校验

- 每个子需求的前提条件是否已在之前批次完成
- 是否有循环依赖（如有，标记并提示用户）
- 顺序无关批次之间是否存在隐式共享资源（如修改同一文件），若有则标注警告

### 输出格式

```text
🔗 排序与批次划分

生成顺序：
  第 1 批 [顺序无关]（无依赖）：S-01（X 文件 / Y 类 / Z 方法）、S-02（...）
  第 2 批 [依赖前批]（依赖 S-01, S-02）：S-03（K 文件 / ...）

批次说明：共 N 批，M 个顺序无关组
[若存在顺序无关批次]
  → 第 1 批 S-01/S-02 可并行生成，将使用 task-dispatch 加速
  → 第 2 批需等第 1 批完成后启动

确认排序合理性与批次划分。
```

---

## 阶段 3：架构与设计模式评估（确认后生成）

在正式生成骨架之前，先评估是否适合引入某种架构风格或设计模式，以提升代码的可读性、扩展性、可维护性、可测试性或复用性等质量属性。**本阶段必须产出建议方案并与用户确认，未获确认前不得进入阶段 4 生成骨架。**

### 为什么需要这一步

骨架一旦生成，文件/类/方法的组织方式就基本固化，后续拆改成本高。如果在生成前识别出"这里用策略模式更利于扩展""这个模块适合分层架构"等信号，骨架结构就能天然承载这些意图，后续 `code-implement` 编写实现也会顺畅得多。

### 评估输入

复用阶段 1 的骨架信息 + 阶段 2 的依赖 DAG：

- 子需求的职责分布（哪些子需求职责相近、哪些易变）
- 接口/方法的交互形态（是否存在多种算法/实现、是否需要统一抽象）
- 数据模型的耦合关系（模型间是否有稳定边界）
- 调用链与依赖方向（是否已呈现分层/管道特征）
- 设计文档是否已在方案中指定架构/模式（若 design-craft 已明确分层/模式，评估以"确认而非重复发明"为主，避免与设计意图冲突）
- 设计文档中标注的"可扩展点""易变部分""性能安全约束"

### 评估维度与建议策略

| 信号（设计特征） | 可能适用的模式/架构 | 带来的主要收益 |
|------------------|---------------------|----------------|
| 存在多种可互换算法/策略（如支付方式、渲染器、校验器） | 策略模式 / 工厂模式 / 依赖注入 | 扩展性：新增实现无需改调用方 |
| 对象创建逻辑复杂、需统一入口 | 工厂模式 / 建造者模式 | 可读性、可测试性 |
| 跨切面关注点（日志、鉴权、事务） | 装饰器 / 中间件 / AOP | 可维护性、复用性 |
| 模块间职责边界清晰、调用有方向 | 分层架构（controller/service/repo）/ 端口与适配器（六边形） | 可读性、可维护性 |
| 数据流呈多阶段转换 | 管道-过滤器 / 责任链 | 可读性、可扩展性 |
| 状态驱动的复杂行为 | 状态模式 | 可读性、可维护性 |
| 需要统一访问接口屏蔽底层差异 | 适配器模式 / 门面模式 | 复用性、可读性 |
| 一对多通知/事件驱动 | 观察者模式 / 发布订阅 | 扩展性、解耦 |
| 全局配置/资源需单点管理 | 单例（谨慎）/ 依赖注入容器 | 复用性 |
| 跨子需求共享的稳定抽象 | 抽象基类 / 接口隔离 | 可扩展性、复用性 |

> ⚠️ **不要为模式而模式**：仅当设计特征明确给出信号时才建议引入。简单直接的实现优于过度设计。若无可适用信号，明确告知用户"当前设计无需引入额外模式，按平铺结构生成骨架即可"。

### 评估输出格式

```text
🏗️ 架构与设计模式评估

设计特征信号：
  - S-01/S-02：存在 3 种可互换的校验策略（邮箱/手机/令牌）→ 策略模式信号
  - 全局：鉴权、日志为跨切面关注点 → 中间件/装饰器信号
  - 调用方向：controller → service → repository 清晰 → 分层架构信号

建议方案（按推荐度排序）：
  ① 分层架构 + 策略模式（推荐）
     收益：可读性↑、扩展性↑、可测试性↑
     代价：增加少量抽象类/接口文件
     对骨架的影响：新增 strategy/ 目录与 BaseValidator 抽象基类；service 层依赖接口而非具体实现
  ② 仅分层架构（保守）
     收益：可读性↑、可维护性↑
     代价：新增校验策略时需改调用方
     对骨架的影响：仅调整目录分层

请确认采用方案 [①/②/其他]，或说明你的偏好。确认后进入阶段 4 生成骨架。
```

### 确认门禁

- 用户明确选择方案（或提出调整）→ 进入阶段 4，生成时按确认方案组织目录/类/接口结构
- 用户对某模式存疑 → 补充说明该模式在此处的收益与代价，必要时给出"引入 vs 不引入"的对比，再二次确认
- 用户明确要求跳过评估 → 记录"用户跳过评估，按平铺结构生成"，直接进入阶段 4（适用于简单/单文档/小项目，且设计文档未给出模式信号时）
- 轻量通道：若子需求 ≤ 2 且设计文档无任何模式信号，可一句话给出"当前设计无需引入额外模式，按平铺结构生成"，确认后即进入阶段 4，不必展开完整方案对比，避免确认疲劳
- 未获任何确认（也未要求跳过）→ 停留在阶段 3，绝不进入生成阶段

### 评估结论落盘

确认后的方案记录到 `skeleton-status.md` 的"架构与设计模式"小节，供 `code-implement` 阶段参考。

---

## 阶段 4：分批生成代码骨架

核心阶段。**每批独立生成 + 独立验证**。

### 执行策略

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

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

### 并行判定

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

### task-dispatch 调度要点

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

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

```text
| 编号 | 子任务 | 子需求 | 涉及文件 | 类/方法/字段 |
|------|--------|--------|----------|-------------|
| K-01 | S-01 骨架 | 用户服务 | user_service.py | 1类 / 3方法 / 5字段 |
| K-02 | S-02 骨架 | 订单服务 | order_service.py | 1类 / 4方法 / 3字段 |
```

**子 agent prompt 要点**：

```
你是子 agent，负责生成子需求 S-{NN}：{名称} 的代码骨架。

## 骨架信息
{从阶段 1 提取的该子需求完整骨架信息：文件、类、方法、字段、异常}

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

## 生成步骤
按顺序执行：
1. 创建/打开文件（create 新建；modify 先读取原文件再追加）
2. 写入文件头注释（文件用途、关联设计文档锚点、全局约束）
3. 导入语句（根据设计文档中的依赖关系添加 import）
4. 定义类/结构体（类声明 + 继承 + 实现）
5. 声明字段（字段名 + 类型 + 默认值 + 行内注释）
6. 声明方法（方法签名 + 契约级注释 + 占位方法体）

## 契约级注释格式

类级注释：
```python
class UserService:
    """用户服务。

    职责：管理用户注册、登录、信息查询。
    关键约束：密码必须加盐哈希存储；查询接口响应时间 < 200ms。
    影响范围：被 AuthController、ProfileController 依赖。
    依赖文档：dependencies/redis.md（缓存依赖）
    设计文档：§ S-01 方案
    """
```

方法级注释：
```python
def login(self, cred: LoginRequest) -> TokenPair:
    """用户登录，返回访问令牌和刷新令牌。

    参数：cred: LoginRequest — 登录凭证
    返回：TokenPair — {access_token, refresh_token, expires_in}
    异常：AuthError: 密码错误时抛出（对外暴露，返回 401）
    预期行为：
        1. 根据用户名查询用户记录
        2. 校验密码（加盐哈希比对）
        3. 生成 TokenPair 并返回
    HTTP：POST /api/auth/login
    依赖文档：dependencies/openai-api.md（GPT 调用）
    设计文档：§ S-01 接口设计
    """
    ...
```

## 注释约束
- 不抄全文：只写契约信息，不抄决策理由、AS-IS、备选方案
- 方法级注释 ≤ 15 行
- 必须包含锚点：设计文档：§ {子需求编号} {章节名}
- 签名原样：方法签名必须与设计文档完全一致
- 依赖标注：方法/类涉及第三方依赖时，标注"依赖文档：dependencies/{名称}.md"；无依赖时不标注此字段

## 修改文件策略

修改现有文件时，**不直接替换已有实现**，而是在修改点上方插入 TODO 标记 + 契约注释。

### TODO 标记格式

根据目标语言使用对应的行注释语法：

| 语言 | 行注释语法 | TODO 标记示例 |
|------|-----------|---------------|
| Python | `#` | `# TODO[S-01]: 新增 - 登录方法` |
| Java | `//` | `// TODO[S-01]: 新增 - 登录方法` |
| Go | `//` | `// TODO[S-01]: 新增 - 登录方法` |
| TypeScript | `//` | `// TODO[S-01]: 新增 - 登录方法` |
| Rust | `//` | `// TODO[S-01]: 新增 - 登录方法` |

TODO 标记完整格式（以 Python 为例，其他语言替换注释符号即可）：

```python
# TODO[S-01]: {变更类型} - {一句话变更描述}
#   参数/返回值/异常：{契约信息，仅修改时写出变更部分}
#   预期行为：{1.步骤 → 2.步骤 → 3.步骤}
#   影响范围：{哪些调用方/依赖方会受影响}
#   兼容性：{仅高风险修改需要，说明是否需要过渡方案}
#   依赖文档：dependencies/{依赖名称}.md（仅涉及第三方依赖时标注）
#   设计文档：§ {子需求编号} {章节名}
```

### 按变更类型的处理方式

| 变更类型 | TODO 标记 | 方法体 | 额外要求 |
|----------|-----------|--------|----------|
| 新增方法 | TODO[S-NN]: 新增 - ... | 原生占位符 | 注明在哪个类中新增 |
| 修改方法 | TODO[S-NN]: 修改 - ... | **保留原实现**，TODO 中说明变更点 | 注明原签名 → 新签名的变化 |
| 删除方法 | TODO[S-NN]: 删除 - ... | **保留原方法**，TODO 注明删除原因 | 注明影响范围（调用方列表） |
| 重构/替换 | TODO[S-NN]: 重构 - ... | **保留原实现**，TODO 说明替换逻辑 | 必须注明兼容性要求和过渡方案 |

### 修改文件注意事项
- 先读取原文件内容，理解现有结构后再定位修改点
- TODO 标记紧跟在修改点上方，不要放在文件头部集中标注
- 保留所有已有实现，不删除不替换——编码阶段由 AI 决定如何处理
- 同一文件有多个修改点时，按从上到下的顺序标注 TODO
- 同一文件既有新增又有修改时，先处理修改点（插入 TODO + 保留原实现），再处理新增点（追加占位方法体）

## 方法体占位
{根据目标语言使用原生占位符：Python `...`、Java `throw new UnsupportedOperationException()`、Go `panic("not implemented")`、TS `throw new Error("not implemented")`、Rust `todo!()`}

## 批内自检
生成后自查：
☐ 所有文件已创建/修改  ☐ 所有类已定义  ☐ 所有方法已声明
☐ 所有字段已声明  ☐ 方法级注释含参数/返回值/异常/预期行为
☐ 方法体用语言原生占位符  ☐ 所有注释含设计文档锚点
☐ 修改文件的 TODO 标记含变更类型 + 影响范围  ☐ 修改文件的原实现已保留
☐ 涉及第三方依赖的方法/类标注了依赖文档路径

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

### 合并

主 agent 收集各子 agent 产出，按项目相对路径合并骨架文件到项目源码目录。同批顺序无关的产出无冲突（文件无交集），直接合并。

### 批次完成确认

```text
✅ 第 {N} 批骨架生成完成

并行子任务：M 个（全部完成）
产出文件：X 个（新增 Y / 修改 Z）

进入下一批 / 进入阶段 5 一致性验证
```

---

## 阶段 5：骨架一致性验证

全部批次生成完成后，将骨架中的注释与设计文档逐项比对。

### 验证维度

| 维度 | 验证内容 | 通过标准 |
|------|----------|----------|
| 文件覆盖 | 设计文档中所有新增/修改文件都已生成骨架 | 100% 覆盖 |
| 类覆盖 | 设计文档中所有类/模型都已定义 | 100% 覆盖 |
| 方法覆盖 | 设计文档中所有接口/方法都已声明 | 100% 覆盖 |
| 签名一致 | 方法签名与设计文档完全一致 | 零偏差 |
| 字段一致 | 字段名、类型、默认值与设计文档一致 | 零偏差 |
| 异常覆盖 | 所有异常场景都在方法注释中说明 | 100% 覆盖 |
| 行为描述 | 方法注释中的"预期行为"覆盖设计文档中的行为要求 | ≥ 95% 覆盖 |
| 锚点完整 | 每条注释都有设计文档锚点 | 100% 覆盖 |
| 修改点定位 | 修改文件中的 TODO 标记位置与设计文档变更描述一致 | 零遗漏 |
| 修改影响 | 高风险修改的 TODO 标记中标注了影响范围和兼容性说明 | 100% 覆盖 |

### 输出格式

```text
📐 骨架一致性验证

验证范围：全部 N 批

逐项核对结果：
  ✅ 文件覆盖：{X}/{X}，100%
  ✅ 类覆盖：{Y}/{Y}，100%
  ⚠️ 方法覆盖：{Z-1}/{Z}，遗漏 1 个 → {方法名} § {锚点}
  ✅ 签名一致：零偏差

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

偏差处理：遗漏项补充到对应骨架文件；不一致项以设计文档为准修正骨架
```

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

---

## 阶段 6：落盘与集成

### 存储位置

骨架文件直接写入项目源码目录（按设计文档中的文件路径）。骨架状态记录 `skeleton-status.md` 存放在设计文档目录旁：

```
项目根目录/
├── src/
│   ├── path/to/
│   │   ├── file.py          ← 骨架文件，含契约级注释
│   │   └── other.py
└── {设计文档目录}/
    ├── DESIGN.md
    └── skeleton-status.md  ← 骨架生成状态记录
```

### skeleton-status.md（骨架状态记录）

记录骨架生成状态，供中断恢复和变更检测使用：

```markdown
# 代码骨架生成状态

关联设计文档：`design/DESIGN.md`
生成时间：{YYYY-MM-DD HH:MM}
生成批数：共 N 批（其中 M 批使用 task-dispatch 并行）

## 架构与设计模式

确认方案：{分层架构 + 策略模式 / 仅分层架构 / 无需额外模式（平铺结构）}
评估依据：{命中的设计特征信号，如"3 种可互换校验策略 → 策略模式"}
对骨架的影响：{新增的抽象基类/接口/目录，及依赖方向变化}
确认时间：{YYYY-MM-DD HH:MM}

## 批次状态

| 批 | 子需求 | 文件数 | 生成方式 | 状态 | 生成时间 |
|----|--------|--------|----------|------|----------|
| 第 1 批 | S-01, S-02 | X | task-dispatch 并行 | ✅ 已完成 | {时间} |
| 第 2 批 | S-03 | Y | 主 agent 串行 | ✅ 已完成 | {时间} |

## 骨架文件清单

| 文件路径 | 类型 | 类数 | 方法数 | 字段数 | TODO数 | 变更类型分布 | 设计锚点 |
|----------|------|--------|--------|--------|--------|--------------|----------|
| src/path/to/file.py | 新增 | 2 | 5 | 8 | 0 | — | § S-01 |
| src/path/to/other.py | 修改 | 0 | 0 | 2 | 3 | 新增1/修改2 | § S-02 |

## 一致性验证

- 验证结果：✅ 一致
- 偏差记录：无 / {偏差列表}
```

### 输出格式

```text
✅ 代码骨架已落盘

骨架文件：已写入项目源码目录
状态记录：{路径}/design/skeleton-status.md

统计：
  - 文件：X 个（新增 Y / 修改 Z）
  - 类：A 个 ｜ 方法：B 个 ｜ 字段：C 个 ｜ 契约注释：D 条

🚀 后续行动选择
1. 🔨 开始编码实施（调用 `code-implement` skill）
   骨架已就绪，code-implement 将系统化地读取骨架契约 + code-survey + dependency-docs，分批填充实现。
2. 📝 生成实施计划（design-craft 阶段 6）
3. ⏭️ 暂不实施

请选择 [1/2/3]：
```

---

## 阶段 7（可选）：设计变更更新

设计文档变更后，检测变更范围并询问用户是否更新骨架。

### 触发方式

1. **用户主动触发**："设计变了，更新骨架"、"重新生成骨架"
2. **skill 自动检测**：比对设计文档修改时间与 `skeleton-status.md` 生成时间，若设计文档更新则提示

### 更新策略

| 变更类型 | 更新策略 |
|----------|----------|
| 新增子需求 | 生成新批次骨架，追加到现有骨架中 |
| 修改接口签名 | 重新生成受影响的方法声明和契约注释 |
| 修改数据模型 | 重新生成受影响的类定义和字段声明 |
| 删除子需求 | 提示用户确认是否删除对应骨架文件（不自动删除） |
| 全局约束变更 | 更新文件头注释中的全局约束说明 |
| TODO 标记变更 | 更新/删除受影响的 TODO 标记：变更类型升级则重写 TODO；需求撤销则删除 TODO 并注释说明 |
| TODO 变更类型变化 | 原 TODO 标注"新增"→实际需"修改"时，更新 TODO 为新变更类型 + 补充影响范围 |

### 更新约束

- **仅更新受影响批次**：未变更的批次骨架保持不变
- **不覆盖已填实现**：若骨架文件中的方法已被 AI 填充实现，更新时仅修改契约注释和方法签名，保留实现逻辑
- **更新后重新验证**：受影响批次重新执行阶段 5 一致性验证

---

## 反模式（不要做）

### 提取层面
- ❌ 将"决策理由"、"备选方案"、"AS-IS 描述"当作骨架信息提取
- ❌ 笼统概括为"实现 xx 模块"而不拆解到文件/类/方法级
- ❌ 自行添加设计文档中未要求的"最佳实践"条目
- ❌ 修改设计文档中的接口签名或数据模型定义
- ❌ 对修改文件笼统标注"修改 xx 文件"而不拆解到具体变更类型和定位点
- ❌ 遗漏第三方依赖的文档引用——方法调用外部 API/SDK 时必须标注依赖文档路径

### 生成层面
- ❌ 方法体写入具体实现逻辑——骨架只放占位符
- ❌ 契约注释抄写设计文档全文——只写契约信息
- ❌ 遗漏方法级注释中的"预期行为"
- ❌ 使用非语言原生的占位符
- ❌ 修改现有文件时直接删除或替换已有实现——应用 TODO 标记并保留原实现
- ❌ 遗漏 TODO 标记中的变更类型或影响范围说明
- ❌ 高风险修改（重构/替换）不标注兼容性说明
- ❌ 把所有 TODO 标记集中在文件头部标注——应紧跟在修改点上方
- ❌ 跳过阶段 3 的架构/设计模式评估与用户确认，直接生成骨架——可能固化不良结构、丧失扩展性，且违背本 skill 的确认门禁

### 使用层面
- ❌ 编码时不看骨架注释直接凭记忆写代码
- ❌ 编码时擅自修改方法签名——发现设计问题应回到 design-craft 修订
- ❌ 子需求 ≥ 3 时一口气生成所有批次——上下文过长
- ❌ 跳过批内验证直接进入下一批次——偏差会逐批累积
- ❌ 设计变更后不更新骨架直接编码
- ❌ 编码时忽略 TODO 标记直接修改代码——应先理解标记中的契约信息再动手
- ❌ 修改现有方法时不检查 TODO 标注的影响范围和兼容性要求

---

## 附加资源

- 设计文档生成：`design-craft` skill
- 第三方依赖文档整理：`dependency-docs` skill（在设计前整理依赖文档，产出 `dependencies/` 目录供骨架注释引用）
- 骨架编码实施：`code-implement` skill（系统化地从骨架填充实现，参考 code-survey + dependency-docs）
- 并行任务调度：`task-dispatch` skill（**同会话内**同批顺序无关时自动调用）
- 跨会话并行交付（骨架核验 + 切片 + 批次）：`delivery-slicing` skill
- 实施计划生成：design-craft 阶段 6
- 实现结果归档：`implementation-report` skill