agentleFS
wonderslifewonderslife/pdd-skills-v3/skills/core/pdd-generate-spec/SKILL.md

pdd-generate-spec

Skill15 starsChanged 28 days agoMITView on GitHub

根据功能点矩阵生成开发规格与验收标准。当用户需要生成功能点技术规格、编写spec.md或checklist.md时调用。支持中文触发:生成规格、开发规格、技术规格、PDD规格、验收标准。

1 other project uses a version of this.

Adopted by

Most recently taken up by

The file

Files
SKILL.md

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-featuresSequential功能点矩阵功能点详情
pdd-baSequential业务分析报告用例/流程/状态
system-architectConsultation架构需求架构建议
software-architectConsultation模块需求模块设计
pdd-implement-featureSequentialspec.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 → 记录信息,正常继续

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.