从设计文档生成代码骨架（文件+类+方法结构），将接口契约、数据模型、异常处理等以契约级注释嵌入代码中，使 AI 编码时无需反复查阅外部文档。大型项目按依赖批次分批生成，同批并行加速。生成前先评估架构风格与设计模式并与用户确认。适用场景：(1) 设计文档完成后准备编码，(2) "生成代码骨架"、"搭骨架"、"按设计生成代码结构"，(3) 设计变更后更新骨架，(4) AI 编码阶段需降低 token 消耗，(5) 修改现有代码时标注 TODO + 契约注释。
Scanned 9/20/2026
Install to Claude Code
Skills Directorynpx -y skills add HACK-WU/skills --skill design-to-code --agent claude-codeInstalls into .claude/skills of the current project.
Are you the author of Design To Code?
Add the live security badge to your README — it updates automatically with every re-scan.
[](https://www.skillsdirectory.com/skills/hack-wu-design-to-code)More formats (shields.io, HTML) on the badges page.
---
name: design-to-code
description: 从设计文档生成代码骨架（文件+类+方法结构），将接口契约、数据模型、异常处理等以契约级注释嵌入代码中，使 AI 编码时无需反复查阅外部文档。大型项目按依赖批次分批生成，同批并行加速。生成前先评估架构风格与设计模式并与用户确认。适用场景：(1) 设计文档完成后准备编码，(2) "生成代码骨架"、"搭骨架"、"按设计生成代码结构"，(3) 设计变更后更新骨架，(4) AI 编码阶段需降低 token 消耗，(5) 修改现有代码时标注 TODO + 契约注释。
---
# 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 特征标记：
- **匹配**：按设计文档章节名进行提取
- **不匹配**：输出警告，询问用户是否继续。确认后按章节名模糊匹配提取规则
### 输出格式
```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（同批顺序无关时自动调用）
- 实施计划生成：design-craft 阶段 6
- 实现结果归档：`implementation-report` skill
Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.
No comments yet. Be the first to comment!
