ai-dev-workflow

让 AI 生成规范、不跑偏代码的完整开发流程 —— 规格驱动（SDD）+ 分层测试先行（TDD）+ 收敛验证

一套从需求文档到上线的 AI 辅助开发流程规范，配套可复制的中间产物模板和可安装的 Agent Skill。适用于 Java 服务端项目（Controller → Service → DAO/Mapper → 数据库；Quartz 定时任务；RabbitMQ 消息），方法论可推广到其他语言。

为什么需要这套流程

直接丢给 AI 一句提示词让它写代码，结果往往是：代码能跑但没人敢维护、接口悄悄偏离设计、测试从零开始、评审面对千行代码无从下手。

这套流程把 AI 编码约束进一条 5 步流水线，核心是四个字：不跑偏。

防跑偏手段	作用
类型化模板	Controller/Listener/Job 各自方案格式固定，AI 没有"发挥空间"
验收场景前置	方案阶段就写死"怎么算对"，直接翻译成测试
约束硬规则	项目约束写成"能检查对错"的规则，AI 逐条对照
角色分离	写测试的人/标准 ≠ 实现代码的 AI，防止"骗绿"
收敛兜底	实现完按类型逐条核对，防规格漂移

流程一览

产品需求
  │
  ▼
【入口确认】和用户确认：当前老项目上迭代需求，还是新项目？
  │
  ├─ 新项目 ──────────────────────┬─ 老项目上迭代 ──────────────────────┬─ 已接入规范项目
  │                               │                                     │
  ▼                               ▼                                     ▼
0.0 项目初始化                    【优化决策】是否按规范                  1.1 需求分析
（脚手架检查清单：多环境          优化存量代码？                          （直接起）
 配置/HikariCP/JDBC 字符集/       ⚠ 未明确选择 → 不得进入 1.1
 端口/MetaObjectHandler/         ├─ 是（选规范，可多选）──► 先做存量优化 ──► 1.1 需求分析
 schema 一致性/驱动版本；         └─ 否（跳过）──────────► 1.1 需求分析（2.1 走存量适配模式）
 防"启动即炸"）                    同模块已有历史产物？
  │                               ├─ 是 ──► 0.8 迭代变更影响分析 ──► 1.1（继承旧产物同步）
  │                               └─ 否 ──►（如上走 0.5 或 1.1）
  ▼
1.1 需求分析 ──→ 功能清单总览（需求准入：分档 A/B/C + 验收基线；先过滤非 Java 服务端需求；表格：功能项/类型/优先级/依赖/验收标准）
  │
  ▼
1.2 需求质量核对 ──→ 需求质量核对报告（/req-gate：原文回读逐节核对 + 跨节矛盾扫描 + 术语↔码值对齐；强制闸门，未过不得进入 1.3）
  │
  ▼
1.3 澄清 ────→ 澄清问题清单（歧义/入口复杂度/边界/依赖 + 裁决 1.2 交来的矛盾/术语项，人确认）+ 更新后功能清单
  │
  ▼
2.1 技术架构 ──→ 技术架构 + 项目约束（标准模式 / 存量适配模式：对齐老项目约定）
  │
  ▼
3.x 技术方案 ──→ 每功能项一份技术方案 md（3.0 通用骨架 + 类型模板：Controller/Listener/Job）
  │              含验收场景（测试用例蓝本）
  ▼
4.1/4.2 任务拆解 + 契约测试（人主导）──→ 任务拆解.md + 红色测试 + DDL
  │
  ▼
5.1/5.2/5.3 AI 编码 + 规范核对 + 收敛验收（AI 主导）──→ 绿色代码 + 验收报告
  │
  ▼
人工验收 ──→ 上线

编号与模板一一对应：0.8 迭代变更影响分析（同模块改逻辑/迭代必做）/ 1.1 功能清单 / 1.2 需求质量核对（/req-gate） / 1.3 澄清 / 2.1 项目约束 / 3.x 技术方案 / 4.1 任务拆解、4.2 契约测试 / 5.1 编码、5.2 规范核对（强制独立节点，产物 5.2 规范核对报告）、5.3 验收。产物落盘见下方「落盘规则」。

目录结构

ai-dev-workflow/
├── README.md                  # 本文件
├── LICENSE
├── docs/                      # 方法论文档
│   ├── 流程总览.md            # 5 步完整流程（权威定义）
│   ├── Vibe-Coding-与-Spec-Coding-对比.md
│   └── Spec-Coding-详解.md    # SDD 六步 + 中间产物
└── skill/                     # 可安装的 Agent Skill（自包含：SKILL.md + commands + templates）
    └── ai-dev-workflow/
        ├── SKILL.md           # 主入口（模型自动触发）
        ├── commands/          # 15 个步骤命令（/命令 分步执行）
        │   ├── 0.0-项目初始化.md     # 0.0 脚手架检查清单（从零生成工程必做）
        │   ├── legacy-scan.md       # 0.5 存量代码扫描与约束适配
        │   ├── change-impact.md     # 0.8 迭代变更影响分析（同模块改逻辑/迭代必做：定位旧产物→变更映射→产物同步计划）
        │   ├── feature-list.md      # 1.1 功能清单（需求准入：分档 + 基线）
        │   ├── req-gate.md          # 1.2 需求质量核对（强制闸门：回读/矛盾/术语）
        │   ├── clarify.md           # 1.3 澄清歧义/入口复杂度/边界/依赖 + 裁决 1.2 🔲 项
        │   ├── constraints.md       # 2.1 项目约束（标准/存量适配双模式）
        │   ├── design.md            # 3.x 技术方案（3.0 通用骨架 + 类型模板组合）
        │   ├── task-breakdown.md    # 4.1 任务拆解
        │   ├── contract-tests.md    # 4.2 接口契约测试
        │   ├── implement.md         # 5.1 AI 编码
        │   ├── check-standards.md   # 5.2 规范核对强制节点（产物 5.2 规范核对报告，5.3 前置硬依赖）
        │   ├── accept.md            # 5.3 验收报告
        │   ├── gen-comments.md      # 附加：存量代码补注释
        │   └── gen-logs.md          # 附加：存量代码补全/完善日志
        └── templates/         # 18 份中间产物空白模板（含完整示例）
            ├── 0.0-项目初始化.md
            ├── 0.5-存量代码扫描.md
            ├── 00-中间产物-MD样式规范.md
            ├── 0.8-迭代变更影响分析.md
            ├── 1.1-功能清单.md
            ├── 1.2-需求质量核对.md
            ├── 1.3-澄清问题清单.md
            ├── 2.1-项目约束.md
            ├── 2.1-项目约束-存量适配.md
            ├── 3.0-技术方案-通用骨架.md
            ├── 3.1-技术方案-Controller.md
            ├── 3.2-技术方案-Listener.md
            ├── 3.3-技术方案-Job.md
            ├── 3.4-接口清单-前后端通用.md
            ├── 4.1-任务拆解.md
            ├── 4.2-接口契约测试.md
            ├── 5.1-编码指令.md
            └── 5.3-验收报告.md

快速开始

方式一：纯手工使用模板（无需任何工具）

1. 从 skill/ai-dev-workflow/templates/ 复制需要的模板到你的项目 docs/ 目录（技术方案需配套复制：3.0-技术方案-通用骨架.md + 对应类型模板，如 3.1-技术方案-Controller.md）
2. 按 1.1→5.3 顺序填写（每份模板开头有填写说明）
3. 第 5.1 步把 5.1-编码指令.md 的内容连同 4.1-任务拆解.md 一起发给 AI

方式二：安装 Skill（Claude Code / Codex / OpenCode 等支持 skill 的 Agent）

1. 安装

将 skill/ai-dev-workflow/ 复制到你的 skills 目录：

# Claude Code
cp -r skill/ai-dev-workflow ~/.claude/skills/

# Codex / OpenCode
cp -r skill/ai-dev-workflow ~/.agents/skills/

注意：本项目自带 .gitignore 的 ! 规则保证 SKILL.md 会被克隆下来；若你从别处拷贝，确保 SKILL.md 文件存在。

2. 触发方式

方式 A：斜杠命令分步执行（推荐，可随时介入检查）

安装后，skill 的 commands/ 目录注册为 /命令，输入 /命令 + 内容 即可执行对应步骤：

编号	命令	用途	示例用法
0.0	/0.0-项目初始化	脚手架检查清单（从零生成工程必做，10 项硬检查）	/0.0-项目初始化 新工程路径
0.5	/legacy-scan	存量代码扫描与约束适配（老代码迭代新需求必做；含"是否按规范优化存量代码"强制决策闸门）	/legacy-scan 老代码项目路径
0.8	/change-impact	迭代变更影响分析（同模块已有产物时改逻辑/迭代必做：定位旧产物 → 变更映射 → 产物同步计划）	/change-impact 商品模块：列表加商品类型筛选
1.1	/feature-list	生成功能清单（需求准入：分档 A/B/C + 验收基线；先过滤非 Java 服务端需求）	/feature-list 订单模块：创建/查询/取消订单
1.2	/req-gate	需求质量核对（强制闸门：原文回读逐节核对 + 跨节矛盾扫描 + 术语↔码值对齐）	/req-gate 订单模块
1.3	/clarify	澄清歧义/入口复杂度/边界/依赖（含裁决 req-gate 交来的矛盾/术语项）	/clarify 订单模块
2.1	/constraints	生成项目约束	/constraints Spring Boot 3.2 + MyBatis-Plus
3.x	/design	技术方案（自动路由类型）	/design 订单创建
4.1	/task-breakdown	任务拆解	/task-breakdown 技术方案/订单创建.md
4.2	/contract-tests	写契约测试（先红）	/contract-tests 技术方案/订单创建.md
5.1	/implement	AI 编码（让测试变绿；编码完成即停，不自评规范核对）	/implement 任务拆解/订单创建.md
5.2	/check-standards	关键规范自动核对（5.1 后 / 5.3 前强制独立节点：全部核对项（无级别之分，含方法级注释/日志全覆盖） + 证据，产物 5.2 规范核对报告 + 用户确认闸门，5.3 前置硬依赖）	/check-standards 项目路径
5.3	/accept	验收报告（前置检查 5.2 报告存在性，无则拒绝验收回 /check-standards；含 quickstart 调通证据）	/accept 订单创建
附加	/gen-comments	存量代码补注释（有 spec 派生 / 无 spec 事实注释，不猜意图）	/gen-comments src/main/java/com/xxx/order
附加	/gen-logs	存量代码补全/完善日志（全类 @Slf4j / 删 System.out / 入口入参+耗时 / 关键节点 INFO / 异常 ERROR 带堆栈）	/gen-logs src/main/java/com/xxx/order

方式 B：自然语言触发

你想做什么	对 Agent 说
完整走一遍 5 步流程	"按流程开发 XX 模块" / "从需求到代码，按流程来"
老代码上迭代新需求	"在老项目上新增 XX 功能" / "按老项目的风格开发 XX"
只要第 1 步	"先生成 XX 模块的功能清单"
只要技术方案	"给 XX 功能写技术方案"
拆任务	"按技术方案拆任务" / "生成任务拆解"
写测试	"按技术方案写契约测试"
AI 编码	"按任务拆解实现，让测试变绿"
存量补注释	"给 XX 模块补注释" / "存量代码注释补全"
存量补日志	"给 XX 模块补日志" / "日志不完善，完善一下"

3. Skill 会做什么

安装后，Agent 按 SKILL.md 中的 5 步流程执行，每一步使用 templates/ 中对应模板：

编号	动作	使用的模板
0.0	脚手架检查清单（从零生成工程必做，10 项硬检查）	templates/0.0-项目初始化.md
0.5	存量代码扫描与约束适配（老代码迭代新需求必做；优化决策闸门：是否按规范优化存量代码，未选不得进入 1.1）	templates/0.5-存量代码扫描.md
0.8	迭代变更影响分析（同模块已有产物改逻辑/迭代必做：定位旧产物 → 变更映射 → 产物同步计划，人确认后才从源头 1.1 同步）	templates/0.8-迭代变更影响分析.md
1.1	生成功能清单总览（需求准入：分档 A/B/C + 验收基线；表格；先过滤非 Java 服务端需求；迭代场景以 0.8 为输入）	templates/1.1-功能清单.md
1.2	需求质量核对（强制闸门：原文回读逐节核对 + 跨节矛盾扫描 + 术语↔码值对齐）	templates/1.2-需求质量核对.md
1.3	澄清歧义/入口复杂度/边界/依赖 + 裁决 1.2 交来的矛盾/术语项	templates/1.3-澄清问题清单.md
2.1	生成技术架构 + 项目约束（标准 / 存量适配双模式）	templates/2.1-项目约束.md / templates/2.1-项目约束-存量适配.md
3.x	生成技术方案	templates/3.0-技术方案-通用骨架.md + templates/3.1/3.2/3.3-技术方案-*.md
4.1/4.2	生成任务清单 + 红色测试	templates/4.1-任务拆解.md、4.2-接口契约测试.md
5.1/5.2/5.3	让测试变绿 + 规范核对（强制独立节点）+ 验收	templates/5.1-编码指令.md、5.3-验收报告.md（5.2 规范核对加载 check-standards skill，产物 5.2 报告为 5.3 前置硬依赖）

skill 是自包含的：SKILL.md、commands/、templates/ 在同一目录内，模板路径为相对引用，安装后无需任何额外配置。

4. 落盘规则（产物放哪里）

产物类型	落盘位置
文档（md）	docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/ 目录下（每模块每版本一个目录）
测试代码	src/test/java/<对应包>/
业务代码	src/main/java/<对应包>/
项目约束	docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/2.1-项目约束.md（每模块每版本一份，与 1.1/1.2/1.3/3.x 等产物同目录）
需求质量核对（1.2 节点）	docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/1.2-需求质量核对.md（/req-gate 输出 + 用户确认，1.3 澄清前置）
存量扫描结论（项目级）	docs/0.5-存量代码扫描.md（老代码迭代新需求时生成，跨模块共享一份）
迭代变更影响分析（0.8 节点）	docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/0.8-迭代变更影响分析.md（/change-impact 输出 + 用户确认，1.1 迭代模式前置输入）
脚手架核对（项目级）	docs/0.0-脚手架核对.md（从零生成工程时）
规范核对报告（5.2 节点）	docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/5.2.<功能项序号>-<功能名>-规范核对报告.md（/check-standards 输出 + 用户确认，5.3 验收的前置硬依赖）
验收报告（5.3 节点）	docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/5.3.<功能项序号>-<功能名>-验收报告.md（/accept 输出）

[!IMPORTANT] 产物命名统一规则 技术方案 = 3.<功能项序号>.1-<功能名>-技术方案.md；接口清单 = 3.<功能项序号>.2-<功能名>-接口清单（前后端通用）.md；规范核对报告 = 5.2.<功能项序号>-<功能名>-规范核对报告.md；验收报告 = 5.3.<功能项序号>-<功能名>-验收报告.md。功能项序号 = 功能清单 # 列（3.x / 5.2.x / 5.3.x 同一功能用同一序号）；文件名禁止拼接任务 ID（T0xx）——任务 ID 只用于 commit message。

docs 模块目录命名：<模块名>V<版本号>-<YYYYMMDDHHMMSS>——模块名 + V 开头版本号（从 PRD/需求文档获取，如 V1.2.0）+ 连字符 + 功能清单生成时间戳（YYYYMMDDHHMMSS）。例：docs/订单模块V1.2.0-20260824103000/。目录在 1.1 功能清单步骤创建（/feature-list 从需求文档读取版本号），后续步骤产物（含 2.1 项目约束）全部落入该目录，跨版本开发互不覆盖。

docs/
├── 0.5-存量代码扫描.md              # 存量扫描结论（老代码迭代时生成，项目级）
└── 订单模块V1.2.0-20260824103000/
    ├── 0.8-迭代变更影响分析.md      # 迭代场景：变更映射 + 产物同步计划（同模块改逻辑时生成）
    ├── 1.1-功能清单.md
    ├── 1.2-需求质量核对.md
    ├── 1.3-澄清问题清单.md
    ├── 2.1-项目约束.md
    ├── 3.1.1-订单创建-技术方案.md
    ├── 3.1.2-订单创建-接口清单（前后端通用）.md
    ├── 4.1.1-订单创建-任务拆解.md
    ├── 5.2.1-订单创建-规范核对报告.md
    └── 5.3.1-订单创建-验收报告.md
src/
├── main/java/com/example/order/    # 业务代码
└── test/java/com/example/order/    # 测试代码

5. 重要提示（防"骗绿"）

• 测试必须由你写（或审核），不要交给实现代码的同一个 Agent——否则它会改弱断言来"骗绿"
• 3.x 技术方案是质量闸门：技术方案里有"待定/视情况"就继续追问，不要带歧义进入编码
• 项目约束要能检查对错：写"统一用 MyBatis-Plus，禁止原生 JDBC"，不要写"尽量用规范的写法"
• 注释与日志不豁免（新老项目一视同仁）：老项目存量代码注释稀疏、日志不完善，不是新代码豁免的理由——本次新增/修改的代码必须全量注释（comment-standards）+ 日志完善（java-code-standards 日志规范：入口入参+耗时/关键节点 INFO/异常 ERROR 带堆栈），禁止大段代码无注释、该记日志的地方必须记

中间产物一览

编号	产物	谁主导
0.5	存量扫描结论（老项目约定基线 + 优化决策）	AI + 人验证
0.8	迭代变更影响分析（变更映射 + 产物同步计划；同模块改逻辑时）	AI + 人验证
1.1	功能清单总览（需求准入：分档 + 基线；表格）	人
1.2	需求质量核对报告（回读核对 + 矛盾清单 + 术语对齐；强制闸门）	AI + 人验证
1.3	澄清问题清单 + 更新后功能清单	人 + AI
2.1	技术架构 + 项目约束（标准 / 存量适配双模式）	人
3.x	每功能项一份方案 md（类型化 + 验收场景）	人 + AI 辅助
4.1/4.2	任务拆解.md + 红色测试 + DDL	人
5.1/5.2/5.3	绿色代码 + 规范核对报告（5.3 前置硬依赖）+ 验收报告	AI + 人验证
验收	可上线	人

适用场景

• ✅ 团队协作、生产上线、多 Controller 复杂模块
• ✅ 需要长期演进、多人维护的服务端项目
• ✅ 对代码规范、可测试性、可追溯性有要求的团队
• ⚠️ 原型验证、个人小工具、一次性脚本 → 这套流程偏重，直接用 Vibe Coding 即可

配套 skill 生态

本 skill 只管流程（怎么走：需求 → 方案 → 任务 → 验收）。编码时按环节配合以下规范 skill：

skill	GitHub	职责	何时加载
build-standards	构建/依赖/多模块	写 pom、加依赖、拆模块
java-code-standards	Java 代码规范（19 类 + 安全/分布式）	写任何 Java 代码
comment-standards	注释规范	写注释/补注释（流程约束模板引用）
database-standards	SQL/表设计/索引/分页	写 SQL、建表
test-standards	测试规范	写测试（4.2 契约测试引用）

License

MIT