wonderslife 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（业务/技术/集成验收三部分）
生成流程
- 读取功能点矩阵: 从
dev-specs/feature-matrix.md读取功能点定义 - 分析功能点详情: 提取功能描述|输入字段|输出信息|业务规则|状态转换|测试策略
- 设计接口定义: RESTful规范|HTTP方法语义|URL命名|请求/响应格式|错误码体系
- 设计数据模型: 实体识别|属性定义|关系映射|索引设计|审计字段(create_time/update_time/create_by/update_by/del_flag/status)
- 定义业务逻辑: 核心流程|边界条件|异常处理|状态机转换
- 设计前端页面: 页面结构|表单布局|列表展示|交互流程
- 定义权限与安全: 接口权限|数据权限|输入校验|SQL注入防护
- 编写验收标准: 业务场景覆盖|技术指标达标|集成测试通过
- 输出规格文档: 保存到
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 / 铁律
- 规格驱动实现: 生成的spec.md必须是后续代码实现的唯一依据，所有接口定义、数据模型、业务规则都必须在规格中明确声明，不得让实现者自行推断。
- 验收标准可测试性: checklist.md中的每条验收标准都必须是客观的、可验证的，不得出现"界面美观""响应迅速"等主观描述。
- 前后端一致性: 规格中的接口定义必须同时适用于后端实现和前端调用，前端API层应能直接基于规格生成。
- 完整性与简洁性平衡: 规格必须足够详细以指导实现(不遗漏关键细节)，但也要避免过度详细导致维护成本过高。
- 变更追溯性: 规格中每个决策(如选择某种数据结构、设计某个接口)都应有简要的理由说明或引用来源，便于后续审查和理解。
违规示例: ❌ 接口只写路径而未定义请求参数和响应结构 | ❌ 验收标准写"用户体验良好"而非具体指标 | ❌ 后端规格与前端实际调用字段名不一致 | ❌ 规格过于简略致实现者频繁询问 | ❌ 联合索引未说明查询场景 合规示例: ✅ 每个接口含完整请求/响应定义和错误码列表 | ✅ 验收标准明确"列表接口响应时间<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 → 记录信息，正常继续