# Pdd Generate Spec

> PDD-Generate Spec - 开发规格生成技能

- Skill: `wonderslife/pdd-generate-spec` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add wonderslife/pdd-generate-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wonderslife/pdd-generate-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wonderslife (https://skillmd.com/u/wonderslife)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wonderslife/pdd-generate-spec

---


# PDD-Generate Spec - 开发规格生成技能

## 核心概念

根据功能点矩阵和业务分析报告，为每个功能点生成详细的开发规格文档(spec.md)和验收标准(checklist.md)。

**输入**: feature-matrix.md(功能点矩阵) | 业务分析报告 | **输出**: spec.md(开发规格) | checklist.md(验收标准) | **不负责**: 代码实现/测试执行

## 规格文档模板

- **spec.md 模板**: 见 `references/spec-template.md`（接口定义/数据模型/业务逻辑/前端页面/权限安全/Options/路由/依赖，共9章）
- **checklist.md 模板**: 见 `references/checklist-template.md`（业务/技术/集成验收三部分）

## 生成流程

1. **读取功能点矩阵**: 从 `dev-specs/feature-matrix.md` 读取功能点定义
2. **分析功能点详情**: 提取功能描述|输入字段|输出信息|业务规则|状态转换|测试策略
3. **设计接口定义**: RESTful规范|HTTP方法语义|URL命名|请求/响应格式|错误码体系
4. **设计数据模型**: 实体识别|属性定义|关系映射|索引设计|审计字段(create_time/update_time/create_by/update_by/del_flag/status)
5. **定义业务逻辑**: 核心流程|边界条件|异常处理|状态机转换
6. **设计前端页面**: 页面结构|表单布局|列表展示|交互流程
7. **定义权限与安全**: 接口权限|数据权限|输入校验|SQL注入防护
8. **编写验收标准**: 业务场景覆盖|技术指标达标|集成测试通过
9. **输出规格文档**: 保存到 `dev-specs/FP-{序号}/spec.md` 和 `checklist.md`

## Guardrails / 质量护栏

**必须遵守**: 接口定义符合RESTful规范 | 数据模型包含审计字段 | 业务规则标注优先级 | 验收标准可测试可验证 | 外键字段定义前端组件类型(禁止UUID手动输入) | Options接口在Spec中声明 | 路由注册顺序遵守约定 | 枚举值用snake_case小写英文

**避免事项**: ❌ 接口路径不符RESTful | ❌ 数据模型缺审计字段 | ❌ 业务规则模糊 | ❌ 验收标准不可测试 | ❌ 外键字段用Input而非Select | ❌ Options路由在/{id}之后 | ❌ 枚举用大写/中文 | ❌ datetime声明为str

## 与其他技能协作

| 协作技能 | 协作方式 | 传入数据 | 期望输出 |
|---------|---------|---------|---------|
| **pdd-extract-features** | Sequential | 功能点矩阵 | 功能点详情 |
| **pdd-ba** | Sequential | 业务分析报告 | 用例/流程/状态 |
| **system-architect** | Consultation | 架构需求 | 架构建议 |
| **software-architect** | Consultation | 模块需求 | 模块设计 |
| **pdd-implement-feature** | Sequential | spec.md + checklist.md | 代码实现 |

## 人工审核规范

**审核节点**: 开发规格生成完成后需人工审核
**审核内容**: 接口设计合理性 | 数据模型完整性 | 业务逻辑正确性 | 验收标准完备性
**审核粒度**: 批量审核（快速浏览标志需详审项）| 关键功能点详细审核（P0优先级|复杂状态转换|外部系统集成|敏感数据）
**输出文件**: `review-spec.md` | **结果类型**: passed / rejected / conditional

## Iron Law / 铁律

1. **规格驱动实现**: 生成的spec.md必须是后续代码实现的唯一依据，所有接口定义、数据模型、业务规则都必须在规格中明确声明，不得让实现者自行推断。
2. **验收标准可测试性**: checklist.md中的每条验收标准都必须是客观的、可验证的，不得出现"界面美观""响应迅速"等主观描述。
3. **前后端一致性**: 规格中的接口定义必须同时适用于后端实现和前端调用，前端API层应能直接基于规格生成。
4. **完整性与简洁性平衡**: 规格必须足够详细以指导实现(不遗漏关键细节)，但也要避免过度详细导致维护成本过高。
5. **变更追溯性**: 规格中每个决策(如选择某种数据结构、设计某个接口)都应有简要的理由说明或引用来源，便于后续审查和理解。

**违规示例**: ❌ 接口只写路径而未定义请求参数和响应结构 | ❌ 验收标准写"用户体验良好"而非具体指标 | ❌ 后端规格与前端实际调用字段名不一致 | ❌ 规格过于简略致实现者频繁询问 | ❌ 联合索引未说明查询场景
**合规示例**: ✅ 每个接口含完整请求/响应定义和错误码列表 | ✅ 验收标准明确"列表接口响应时间<500ms(1000条数据)" | ✅ 前后端使用同一份接口规格作为开发依据 | ✅ 关键决策有注释、常规内容用表格 | ✅ 索引设计附说明"支持按status+create_time的组合查询"

## Rationalization / 理性化对照

完整对照表见 `references/rationalization.md`。核心要点：接口再简单也要定义完整请求/响应结构；每条验收标准必须量化或明确判定方法；规格生成时同步考虑前后端双向适用性；将"显而易见"的细节（尤其边界条件）显式写入规格；采用"概览+详细表格"分层策略。

## Red Flags / 红旗警告

### Layer 1: 输入检查
- **INPUT-GS-001**: 功能点矩阵为空或缺少功能点详情 → 🔴 终止并提示先完成功能点提取
- **INPUT-GS-002**: 业务分析报告缺少用例或状态定义 → 🔴 提示补充完整业务分析后再生成规格
- **INPUT-GS-003**: 功能点复杂度标记(P0/P1/P2)与实际描述不符 → 🟡 记录并标注偏差

### Layer 2: 执行检查
- **EXEC-GS-001**: 接口定义缺少请求参数或响应结构 → 🔴 补充完整接口定义
- **EXEC-GS-002**: 数据模型缺少审计字段(create_time等)或主键 → 🔴 补充标准审计字段和主键
- **EXEC-GS-003**: 验收标准存在无法客观验证的条目 → 🟡 重写为可量化/可判定标准
- **EXEC-GS-004**: 规格业务规则与业务分析报告矛盾 → 🔴 以业务分析为准修正或记录冲突请用户确认
- **EXEC-GS-005**: 外键字段未定义前端组件类型(如department_id用Input) → 🔴 改为Select并声明Options API数据源
- **EXEC-GS-006**: 枚举值使用大写或中文编码 → 🟡 改为snake_case小写英文
- **EXEC-GS-007**: datetime字段在Pydantic Schema中声明为str → 🟡 改为datetime类型并添加序列化配置

### Layer 3: 输出检查
- **OUTPUT-GS-001**: spec.md缺少必要章节(接口定义/数据模型/业务逻辑) → 🔴 补充缺失章节
- **OUTPUT-GS-002**: checklist.md验收标准少于5条或不足以覆盖主要功能 → 🔴 补充更完善的验收标准
- **OUTPUT-GS-003**: 规格保存路径不符合规范(不在dev-specs/FP-{序号}/下) → 🟡 移到正确目录
- **OUTPUT-GS-004**: spec.md缺少前端实现约定章节(第6章) → 🔴 补充前端组件映射和操作按钮矩阵
- **OUTPUT-GS-005**: spec.md缺少关联数据源章节(第7章) → 🔴 补充Options接口定义
- **OUTPUT-GS-006**: spec.md缺少依赖检查清单(第9章) → 🟡 补充前置依赖和后续依赖

**处理流程**: 🔴 CRITICAL → 立即停止，报告问题详情，等待指示 | 🟡 WARN → 记录警告到规格日志，尝试自动修复，在最终报告中标注 | 🔵 INFO → 记录信息，正常继续