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

概述

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

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

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

定位

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

• 输入：design-craft 产出的设计文档目录（design/DESIGN.md + 子文档，也兼容单文档快速通道）
• 输出：项目源码目录中的代码骨架文件（文件已创建、类已定义、方法已声明、契约已注释，方法体用语言原生占位符）
• 边界：只管"从设计文档生成骨架结构 + 嵌入契约注释"，不管"怎么填充实现"（由 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 特征标记：

• 匹配：按设计文档章节名进行提取
• 不匹配：输出警告，询问用户是否继续。确认后按章节名模糊匹配提取规则

输出格式

📂 设计文档定位

来源：{路径}
父文档：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 标记 + 影响范围 + 兼容性说明

定位信息：每个修改点必须提取：

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

提取粒度约束

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

输出格式

🔍 骨架信息提取

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 — 需等前两批

排序校验

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

输出格式

🔗 排序与批次划分

生成顺序：
  第 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）/ 端口与适配器（六边形）	可读性、可维护性
数据流呈多阶段转换	管道-过滤器 / 责任链	可读性、可扩展性
状态驱动的复杂行为	状态模式	可读性、可维护性
需要统一访问接口屏蔽底层差异	适配器模式 / 门面模式	复用性、可读性
一对多通知/事件驱动	观察者模式 / 发布订阅	扩展性、解耦
全局配置/资源需单点管理	单例（谨慎）/ 依赖注入容器	复用性
跨子需求共享的稳定抽象	抽象基类 / 接口隔离	可扩展性、复用性

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

评估输出格式

🏗️ 架构与设计模式评估

设计特征信号：
  - 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）

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

| 编号 | 子任务 | 子需求 | 涉及文件 | 类/方法/字段 |
|------|--------|--------|----------|-------------|
| 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 方案
    """

方法级注释：

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 为例，其他语言替换注释符号即可）：

# 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% 覆盖

输出格式

📐 骨架一致性验证

验证范围：全部 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（骨架状态记录）

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

# 代码骨架生成状态

关联设计文档：`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 |

## 一致性验证

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

输出格式

✅ 代码骨架已落盘

骨架文件：已写入项目源码目录
状态记录：{路径}/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（同批顺序无关时自动调用）
• 实施计划生成：design-craft 阶段 6
• 实现结果归档：implementation-report skill