Ai Dev Workflow

---
name: ai-dev-workflow
description: "Use when developing a Java backend feature — 覆盖三类场景：① 完整 spec 驱动流程（按流程开发/按规格开发/生成功能清单/写技术方案/拆任务/AI 编码收敛/需求覆盖报告）；② 轻量模式（写个接口/写 Controller/Service/ServiceImpl/实现功能/新增接口/改功能），直接\"加载规范 → 写码(全注释+全日志) → check-standards 兜底\"；③ 同模块已有历史产物时的迭代/改逻辑（把 XX 逻辑改一下/调整 XX 功能/在 XX 模块上新增个 XX）→ 必须先 0.8 /change-impact 定位旧产物、变更映射、产物同步计划（人确认）→ 从源头 1.1 同步产物 → 再写码，禁止直接改码/禁止用轻量模式绕过产物同步。Triggers on: \"按流程开发 XX 模块\"、\"按 jee-forge 流程开发 XX 模块\"、\"用 jee-forge 开发 XX 模块\"、\"按 ai-dev-workflow 流程开发 XX 模块\"、\"用 ai-dev-workflow 开发 XX 模块\"（即用户说 XX 模块 + 提到 按流程/jee-forge/ai-dev-workflow 任一 → 均触发本 skill，任意支持 Agent Skills 的工具通用）；轻量触发：写个 XX 接口/实现 XX 功能/写 Controller/Service/新增 XX 接口/把 XX 逻辑改一下/调整 XX 功能/在 XX 模块上改。无需求文档直接要求写码 → 自动轻量模式（加载规范 skill → 全量注释+全量日志写码 → check-standards 兜底，不因没走流程而跳过注释/日志/核对；改逻辑前先 ls docs/ 查历史产物，有 → 先 0.8）。Applies to Java service projects (Controller/Listener/Job) and similar layered backends. 续跑触发：继续 XX 模块/继续 XX 模块的需求/继续上次中断的任务/接着上次 → 按 /progress 逻辑从断点续跑（禁止从 1.1 重跑）。"
---

# AI 开发完整流程（需求 → 上线）

## 核心原则

**不跑偏**：让 AI 生成规范、可验证、可维护的代码。五道防线：

1. **类型化模板** — 每种产物格式固定（Controller/Listener/Job），AI 没有发挥空间
2. **验收场景前置** — 方案阶段写死"怎么算对"，作为 5.3 需求覆盖核对基准（不再翻译成测试）
3. **约束硬规则** — 项目约束是"能检查对错"的规则，AI 逐条对照
4. **角色分离** — 需求覆盖报告由独立步骤生成，不由实现代码的 AI 自评（防假成功）
5. **收敛兜底** — 实现后按类型逐条核对，防规格漂移

## 0.0 项目/工程初始化（脚手架，从零生成项目必做）

**适用范围**：从零生成/初始化 Spring Boot 工程（含 AI 一次生成整个项目）。**在既有项目里迭代新需求则跳过本节**：老代码基础上迭代 → 先走 0.5 存量代码扫描与约束适配；**已接入规范体系的项目**（项目级约束文件已按本流程 2.1 生成并固化，如 AGENTS.md 含本流程约束）里开发新模块 → 直接走 1.1。**判定不了项目是否已接入规范 → 一律按老项目走 0.5，不自行猜测**（宁可多扫一次，不可漏掉优化决策）。

**为什么必须有这一步**：流程 1.1~5.3 假设"项目已存在"，但一次生成整个项目时，工程骨架缺基础设施会导致**启动即炸**。历史踩坑（真实事故）：

| 缺失/错误 | 启动/运行现象 |
|---|---|
| 只有单个 application.yml，无环境拆分 | dev 配置带到生产，连错库 |
| datasource 只配 url/username/password，无 HikariCP 池参数 | 高并发连接打满，难排查 |
| JDBC URL 写 `characterEncoding=utf8mb4` | `Unsupported character encoding 'utf8mb4'` 启动失败 |
| JDBC URL 端口默认 3306，实际环境非 3306（NAT/容器映射） | `Access denied for user 'xxx'@'localhost'` 连接被拒 |
| 实体 `@TableField(fill=...)` 但项目无 MetaObjectHandler | 一插即炸：`Column 'create_time' cannot be null` |
| 库/表沿用旧 schema，与代码 Entity 不匹配 | `Unknown column 'real_name' in 'field list'` |
| MySQL 8 配了 5.1 旧驱动 | 字符集/时区/加密协议一串兼容问题 |

**脚手架硬性检查清单（生成项目后逐项核对，缺一项即不合格；命令 `/0.0-项目初始化`）**：

- [ ] 配置文件四件套：`application.yml` + `-dev` + `-qa` + `-online`（公共/开发/测试/生产），profile 激活 `${SPRING_PROFILES_ACTIVE:dev}` 不写死
- [ ] HikariCP 显式池参数（maximum-pool-size / minimum-idle / pool-name 等），禁止 datasource 三件套裸奔
- [ ] JDBC URL 字符集：**不写 `characterEncoding=utf8mb4`**（8.x 报 Unsupported character encoding），推荐不写或 `characterEncoding=UTF-8`；`serverTimezone=Asia/Shanghai` 必带
- [ ] JDBC URL 端口与目标环境实际一致（禁止默认 3306 想当然）
- [ ] MyBatis-Plus 插件配置（分页 + 乐观锁，参考 java-code-standards `04-templates/ConfigTemplate.java`）
- [ ] MetaObjectHandler 实现（createTime/updateTime 自动填充，参考 java-code-standards `04-templates/MyMetaObjectHandler.java`）
- [ ] 建库/建表显式 utf8mb4；**库初始化按当前 schema.sql 全量重建，禁止沿用旧库旧表**
- [ ] MySQL 驱动 Connector/J 8.x（Spring Boot BOM 管理，无 5.1 旧驱动）
- [ ] 日志配置：`resources/logback-spring.xml` 已提供（控制台 + 滚动文件 + 环境级 level，参考 java-code-standards `04-templates/logback-spring.xml`）；application.yml 有 logging.level 覆盖
- [ ] 接口文档依赖：接口模块已引 springdoc-openapi（/knife4j）且版本由 BOM 管理；`springdoc.api-docs.enabled` 按环境配置（online 关闭）

> 规范出处：配置文件/连接池/字符集 → java-code-standards `01-java/application-config-standards.md`；表/schema → database-standards `standards/table-design-standards.md`；依赖 → build-standards `standards/dependency-standards.md`。模板见 `templates/0.0-项目初始化.md`。

> [!NOTE] 0.0 与 2.1 选型衔接
> 脚手架默认选型（Logback + springdoc-openapi）仅作**工程基线**；第 ② 步 2.1 会**人确认工具选型**（日志框架 Logback/Log4j2、接口文档工具 springdoc/knife4j/Apifox）。2.1 确认的选型与脚手架默认不一致时 → **按 2.1 调整**（如确认 Log4j2 则排除 logback 并配 log4j2.xml；确认 Apifox 纯在线文档则按老约定），0.0 默认值不约束 2.1 决策。

## 0.5 存量代码扫描与约束适配（老代码基础上迭代新需求必做）

**适用范围**：在已有代码库（老项目/历史项目/他人维护项目）上迭代新需求，或在不了解现状的既有工程里开发。**从零新项目跳过本节**。核心思想：**先摸清老项目约定，再决定新代码怎么对齐**——新需求代码风格与老项目一致，不被规范 skill 的标准答案带偏。

**为什么必须有这一步**：老项目 ≠ 新项目。老项目有自己的包结构、返回体（如 `R`/`Response`）、命名风格、中间件版本与账号。若新代码直接按规范 skill 的"标准答案"写，会与老项目风格冲突、无法融入。先扫描把"老项目约定"固化成约束文件，AI 编码时才有据可依。

**执行流程（命令 `/legacy-scan`，扫描只读不改代码）**：

1. **先扫描老代码**（提醒并执行，按以下维度逐项记录证据——文件路径/配置项）：
   - **包结构与分层**：业务代码放哪个包、controller/service/mapper 归属、BaseEntity/公共类位置
   - **返回体与公共组件**：统一返回类（类名/包位置/字段结构）、分页类、异常处理类、可复用工具类/基类清单
   - **命名风格**：Java 类/变量/方法命名、数据库表/字段命名（驼峰 ↔ 下划线映射）
   - **数据访问层约定**：ORM（MyBatis-Plus/MyBatis/JPA）、Mapper XML 使用习惯、逻辑删除/乐观锁/字段自动填充（MetaObjectHandler）、BaseEntity 公共字段（createTime/updateTime/createBy…）
   - **接口与错误码**：接口文档工具（Apifox/Swagger）、错误码体系与定义位置、权限注解（@RequiresPermissions）、参数校验方式
   - **认证鉴权**：登录方案（JWT/Shiro/OAuth2）、token 生成与命名、会话管理
   - **中间件与基础设施**（版本、账号配置、接入方式、使用规范——**老代码怎么用，新代码就怎么用**）：数据库（MySQL/PG/Oracle、连接池 HikariCP/Druid）、消息队列（RabbitMQ/Kafka/RocketMQ、交换机/队列/路由键命名、ACK 方式、消费组）、缓存（Redis key 前缀/序列化方式、本地缓存 Caffeine/Guava）、定时任务（Quartz/XXL-Job/@Scheduled、调度方式、防重入）、文件存储（本地磁盘/MinIO/OSS）、搜索引擎（Elasticsearch）、接口文档、日志（格式/链路追踪）、配置/注册中心（Nacos/Consul，Spring Cloud 场景）
   - **工程与环境**：构建工具、Java/Spring Boot 版本、profile 环境拆分（dev/qa/online）、端口约定
   - **验收能力**：可运行入口情况（HTTP/MQ/调度）与可验收条件，为 5.3 需求覆盖核对提供依据
   - **项目级约束文件**：老项目是否已有项目级约束文件（AGENTS.md / CLAUDE.md / GEMINI.md / README 规范章节 / 项目规范文档等，**以实际存在为准，不限于某一文件名**）——有则记录其覆盖的约束范围；2.1 存量模式生成时，**已有约束直接引用、只补充缺失项**（见 2.1 节）
   - 深度说明：小项目全量看；大项目抽样 2-3 个核心模块 + grep 兜底（返回体/命名/中间件配置必须全局确认）；完整 8 维度体检可另用 legacy-onboarding skill（`7-AI 开发存量项目接入`）

2. **优化决策闸门（强制，用户未明确选择前禁止进入 1.1）**——向用户明确展示"是否按规范优化一版存量代码？"，选项可多选，也可跳过：

| 选项 | 含义 | 后续路径 |
|---|---|---|
| `java-code-standards` | 按 AI 开发代码规范优化存量代码 | 生成存量优化任务 → 按规范执行（改到哪规范到哪，不追求一步全量）→ 更新扫描结论 → 进入 1.1 |
| `comment-standards` | 按 AI 开发注释规范优化存量注释 | 走存量补注释工作流 → 完成后进入 1.1 |
| `database-standards` | 按 AI 开发 SQL 规范优化存量表/SQL | 生成存量表结构/SQL 优化任务 → 执行 → 进入 1.1 |
| `跳过` | 不优化存量代码，只保证新需求代码与老项目一致 | 2.1 走**存量适配模式**（对齐老项目约定） |

**这是 0.5 的强制闸门**（同下方"中间产物确认闸门"）：向人展示选项并等待明确选择，**未选择前不得进入 1.1**；选择结果记入扫描结论（0.5-存量代码扫描.md"优化决策"章节）。

3. **产出扫描结论落盘**：`docs/0.5-存量代码扫描.md`（老项目约定基线 + 优化决策），2.1 生成约束时引用

> [!IMPORTANT] 存量约束口径
> **跳过优化 ≠ 新代码放飞**。用户选择跳过优化后，2.1 必须走**存量适配模式**：新需求代码按老项目约定生成约束（包结构/返回体/命名/中间件对齐老代码），该约束是硬规则，AI 编码时逐条对照。规范 skill 仅在老项目无对应约定时才作为兜底。
> **注释与日志不豁免**：老项目存量代码注释稀疏、日志不完善**不是新代码豁免的理由**——本次新增/修改的代码**必须全量注释**（comment-standards：所有类/方法含 private/抽取方法）**且方法级日志完善**（java-code-standards 日志规范 §1.6：每个业务方法方法体 ≥1 条 INFO/WARN/ERROR 日志（debug 不算）+ 入口入参耗时/关键节点 INFO/异常 ERROR 带堆栈），见 2.1 存量适配模板"注释规范/日志规范"章节。

## 开发场景判定（流程入口，先判定再走流程）

开始任何开发前，**先确认项目现状（由人确认，AI 不得自行跳过判定）**：

| 场景 | 判定依据 | 走哪条路 |
|---|---|---|
| 从零新项目 | 项目尚不存在，从零生成工程 | **0.0 项目初始化** → 1.1 |
| 老代码/既有项目迭代 | 项目已存在，且**未接入本流程规范**（无项目级约束文件，或约束文件非本流程 2.1 产物） | **0.5 存量代码扫描与约束适配**——**进入即弹"是否按规范优化存量代码"决策闸门** → 1.1 |
| 已接入规范项目新模块 | 项目级约束文件已按本流程 2.1 生成并固化（AGENTS.md 等含本流程约束） | 1.1 直接起 |
| **同模块已有产物迭代（改逻辑 / 新版本）** | 项目已接入规范，且 **`docs/` 下已存在该模块历史产物目录**（`<模块名>V<版本>-<时间戳>/`，含 1.1 功能清单/3.x 方案） | **0.8 迭代变更影响分析（/change-impact）**——**先定位旧产物、变更映射、产物同步计划，人确认后才从源头 1.1 同步** → 1.1 |

> [!WARNING] 判定兜底
> **判定不了项目是否已接入规范 → 一律按老项目走 0.5**，不自行猜测（宁可多扫一次，不可漏掉优化决策）。"是否按规范优化存量代码"的提醒是流程的强制环节，任何情况下不得被静默跳过。

## Git 基线纪律（可选，推荐；老项目无 git / 项目无构建可跳过并注明）

git 是流程的"干净起点 + 可追溯收尾"的底座。使用 git 的项目建议遵守：

1. **动工前（首个 1.1 拆解前或首次写码前）**：`git status` 确认工作区干净；从主分支新建独立分支（`git switch -c feature/<模块>`，或用 worktree），**不在 main/主分支上直接开发**；
2. **基线先绿**：动工前先跑一次现有构建（`mvn package` 或项目既有命令；项目无测试则只跑构建），确认"起点能构建通过"并把结论记入 `通用-模块进度与断点.md` 或 1.1 备注（无构建 → 注明"无基线"）；
3. **开发中**：每个任务（4.1 任务项）完成后独立提交，commit message = 任务 ID + 描述（联动硬性约束第 5 条）；不混提交、不提交半成品；
4. **收尾（5.3 后）**：向用户展示工作区状态与改动摘要，由用户决定 **merge 到主分支 / 开 PR / 保留 / 丢弃**；清理多余 worktree；**不自动 merge、不代用户 push**；
5. **不适用时**：老项目无 git / 无法建分支 → 跳过本纪律并在 `通用-模块进度与断点.md` 或需求覆盖报告注明"未采用 git 纪律（原因）"。

## 两种使用方式

### 配套规范 skill 触发矩阵（各步骤必须加载对应规范）

| 流程步骤 | 必须加载的规范 skill | 覆盖内容 |
|---|---|---|
| 0.0 项目/工程初始化 | **build-standards** + **java-code-standards**（application-config + 04-templates）+ **database-standards**（table-design） | 脚手架基础设施：多环境配置/HikariCP/JDBC 字符集/端口/MyBatis-Plus 插件/MetaObjectHandler/schema 一致性/驱动版本 |
| 0.5 存量代码扫描与约束适配 | **`templates/0.5-存量代码扫描.md`**（老项目约定基线模板）+ **`templates/2.1-项目约束-存量适配.md`**（存量模式约束模板）；**选择优化 → 加载对应规范 skill**（java-code-standards / comment-standards / database-standards，按所选） | 扫描只读不改码；约束来源 = 老项目事实（包/返回体/命名/中间件），非规范 skill |
| 0.8 `/change-impact`（迭代变更影响分析） | **`templates/0.8-迭代变更影响分析.md`**（历史版本定位 + 变更映射 + 产物同步计划模板） | 同模块已有产物时改逻辑必做：定位旧产物 → 变更点映射旧功能项（新增/修改/删除）→ 产物同步计划（1.1→3.x→4.x→5.x）→ 人确认后才从源头同步，禁止直接改码 |
| 1.1~5.3 所有 md 产物（含 0.6/0.8/0.9 产物） | **`templates/通用-中间产物-MD样式规范.md`** | 速览框 / 对齐表格 / mermaid 配色 / callout / 自检（生成任何中间产物 md 前必读） |
| 1.2 `/req-gate`（需求质量核对） | **`templates/1.2-需求质量核对.md`**（需求基线 + 回读核对表 + 矛盾清单 + 术语对齐表模板） | 三道核对：① 回读原文逐节防遗漏/误读；② 跨节矛盾扫描防静默选边；③ 术语↔码值对齐（老项目对照 `docs/0.5-存量代码扫描.md`，缺失先 `/legacy-scan`） |
| 2.1 `/constraints` | **build-standards**（标准模式，含走 0.5 选优化）；存量适配模式 → **`templates/2.1-项目约束-存量适配.md`**（约束来源 = 0.5 扫描结论，非规范 skill） | 技术架构选型、依赖/版本管理、多模块结构；存量模式 = 老项目约定（包/返回体/命名/中间件） |
| 3.x `/design` | **database-standards** + **java-code-standards** | DDL/表设计/索引（db）；Controller/Service 分层接口规范（java） |
| 4.1 `/task-breakdown` | **database-standards** | Mapper XML 触发条件（简单查询禁 XML） |
| 5.1 `/implement` | **java-code-standards**（必读）+ **database-standards** + **build-standards** + **comment-standards** | 写代码前先加载：Java → java-code-standards（命名/分层/注释引用）+ comment-standards（注释）；SQL/MyBatis-Plus → database-standards；pom/依赖 → build-standards。编码按方案实现，完成即停，不自行执行全量核对 |
| 5.2 `/check-standards` | **check-standards** skill | 关键规范自动核对（**5.1 后 / 5.3 前的强制独立节点**：**先矫正产物命名与路径**（技术方案 3.x.1 / 接口清单 3.x.2 / 核对报告 5.2.x / 需求覆盖报告 5.3.x，去任务 ID 前缀，移入模块版本目录），再加载 check-standards skill **优先跑 `scripts/check_standards.py` 机械扫描（无 Python 回退 grep/ast-grep）**逐项核对**全部核对项（无级别之分：方法级注释/日志全覆盖含 private 抽取方法 + 框架/SQL/代码质量/场景化）**；未到位先确认再补齐/升级人工；产物 5.2 报告 + 用户确认闸门，5.3 前置硬依赖） |
| 5.3 `/accept` | **—**（引用 5.2 规范核对报告结论，不重复自动核对） | **需求覆盖报告（独立生成，不由编码 Agent 自评）**：逐需求点核对代码（附 file:line 证据或"未找到"）+ 反向核对 + 两类结论分列（语义项标未验证）；Listener/Job 默认标"未验收"不阻塞 |

> 规范 skill 与流程 skill 的关系：**流程管「怎么走」，规范管「生成物长什么样」**。编码 Agent 写代码前必须先加载对应规范 skill，保证**生成物符合规范**（兜底在流程 skill，不靠项目 AGENTS.md）。

### 方式一：分步执行（推荐，可随时介入）

用斜杠命令按步骤执行，每步可独立触发、独立检查：

| 编号 | 命令 | 用途 |
|---|---|---|
| 总入口 | `/jee-forge` | **一键总入口**：开发场景判定 →（需求跨多模块/超大/混栈先 `/req-intake`）→ 完整流程或轻量模式，每步产物人确认；编码收尾统一 `/check-standards` 兜底 |
| 进度 | `/progress` | 读取/更新模块 `通用-模块进度与断点.md`，报告每步状态与当前断点并从断点续跑（跨会话/换人接手先 `/progress`，**禁止从 1.1 重跑**） |
| 0.0 | `/0.0-项目初始化` | 脚手架检查清单（从零生成工程必做；10 项硬检查，防"启动即炸"） |
| 0.5 | `/legacy-scan` | 存量代码扫描与约束适配（老代码迭代新需求必做；扫描老项目约定 + 优化决策） |
| 0.6 | `/feasibility` | 需求可行性评估（**可选前置**：仅当需求命中风险信号——未用过的外部系统/中间件/SDK、选型争议、成本不清新方向——经人确认是否执行；一页速评出 🟢 go / 🟡 需澄清 / 🔴 kill，人拍板；普通需求直接跳过进 1.1） |
| 0.8 | `/change-impact` | 迭代变更影响分析（**同模块已有产物时改逻辑/迭代必做**：定位旧产物 → 变更映射 → 产物同步计划 → 人确认后才从源头 1.1 同步，禁止直接改码） |
| 0.9 | `/req-intake` | 需求入口整形（**可选前置**：需求跨多模块/超大/混杂非 Java 内容时，忽略非 Java 部分 → 按 Java 模块生成模块级需求 md → 人确认后才进 1.1；单模块纯 Java 直接跳过） |
| 1.1 | `/feature-list` | 功能清单（需求准入分档/基线 + 过滤非 Java 服务端需求；迭代场景以 0.8 分析为输入从源头同步） |
| 1.2 | `/req-gate` | 需求质量核对（**1.1 后必做强制闸门**：原文回读逐节核对防遗漏/误读 + 跨节矛盾扫描防静默选边 + 术语↔码值对齐；🔲 项交 1.3 澄清；**未过闸不得进入 1.3**） |
| 1.3 | `/clarify` | 盘问歧义/入口复杂度/边界/依赖（含 req-gate 交来的矛盾/术语🔲项；方案前必做） |
| 2.1 | `/constraints` | 项目约束（含公共组件规范） |
| 3.x | `/design` | 技术方案（3.0 通用骨架 + 类型模板组合；含公共组件识别） |
| 4.1 | `/task-breakdown` | 任务拆解（公共组件入 Phase 0.5） |
| 5.1 | `/implement` | AI 编码（**目标 = 按 3.x 方案 + 4.1 任务实现**；编码完成即停，不自行执行全量核对） |
| 5.2 | `/check-standards` | 关键规范自动核对（**5.1 后的强制独立节点**：**先矫正产物命名/路径**（3.x.1/3.x.2/5.2.x/5.3.x，去 T0xx 前缀，移入模块版本目录），再加载 check-standards skill **优先跑 `scripts/check_standards.py` 机械扫描（无 Python 回退 grep/ast-grep）**核对**全部核对项（无级别之分，含方法级注释/日志全覆盖）**；未到位先确认再补齐/升级人工；产物 `5.2.<功能项序号>-<功能名>-规范核对报告.md` + 用户确认闸门，**5.3 前置硬依赖**） |
| 5.3 | `/accept` | 需求覆盖报告（**独立生成、不由实现代码 AI 自评**：逐需求点核对代码，附 `file:line` 证据或标"未找到"；双向核对 + 两类结论分列；**前置检查 5.2 报告存在性**，无则拒绝；Listener/Job 默认标"未验收"、不阻塞；缺口闭环由人确认） |
| 附加 | `/gen-comments` | 存量代码补注释（有 spec 派生 / 无 spec 事实注释，不猜意图） |
| 附加 | `/gen-logs` | 存量代码补全/完善日志（全类 @Slf4j / 删 System.out / 入口入参+耗时 / 关键节点 INFO / 异常 ERROR 带堆栈，只加日志不改业务） |

命令文件在 `commands/` 目录，每个命令自带输入/执行/完成标准。`/gen-comments` 与 `/gen-logs` 为独立命令，不属于五步流程，按需用于历史代码注释/日志补全；存量代码注释与日志都缺时，先 `/gen-comments` 后 `/gen-logs` 依序执行。

### 落盘规则（所有命令统一遵守）

| 产物类型 | 落盘位置 |
|---|---|
| 文档（md） | `docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/` 目录下（每模块每版本一个目录） |
| 业务代码 | `src/main/java/<对应包>/` |
| 项目约束 | `docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/2.1-项目约束.md`（每模块每版本一份，与 1.1/1.2/3.x 等产物同目录） |
| 需求质量核对（1.2 节点） | `docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/1.2-需求质量核对.md`（/req-gate 输出 + 用户确认，**1.3 澄清前置**） |
| 任务拆解（4.1 节点） | `docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/4.1.<功能项序号>-<功能名>-任务拆解.md`（每功能项一份；功能项序号与 3.x 一致） |
| 存量扫描结论（项目级） | `docs/0.5-存量代码扫描.md`（老代码迭代新需求时生成，跨模块共享一份） |
| 需求可行性评估（0.6 节点，可选） | `docs/0.6-需求可行性评估.md`（/feasibility 输出 + 用户拍板 🟢/🟡/🔴；同一批再次评估 → `docs/0.6-需求可行性评估-<YYYYMMDDHHMMSS>.md`；模块版本目录已建则放入其内，未建放 docs/ 根） |
| 迭代变更影响分析（0.8 节点） | `docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/0.8-迭代变更影响分析.md`（/change-impact 输出 + 用户确认，**1.1 迭代模式前置输入**；新版本目录已建则放入其内，未建先放 docs/ 根，1.1 建目录时移入） |
| 需求入口整形（0.9 节点，可选） | `docs/req-intake-<YYYYMMDDHHMMSS>/`（批次级，先于各模块 1.1；含《需求构成清单与确认.md》+ 每 Java 模块一份《<模块名>-模块需求.md》，人确认后各模块才进入 1.1） |
| 模块进度（全流程） | `docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/通用-模块进度与断点.md`（1.1 建目录时创建，每步产物确认后更新；跨会话/换人接手先 `/progress`，禁止从 1.1 重跑） |
| 项目初始化核对（项目级） | `docs/0.0-项目初始化.md`（从零生成工程时） |
| 规范核对报告（5.2 节点） | `docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/5.2.<功能项序号>-<功能名>-规范核对报告.md`（/check-standards 输出 + 用户确认，**5.3 需求覆盖前置硬依赖**；功能项序号与 3.x 技术方案一致） |
| 需求覆盖报告（5.3 节点） | `docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/5.3.<功能项序号>-<功能名>-需求覆盖报告.md`（/accept 输出；功能项序号与 3.x 技术方案一致） |

> [!IMPORTANT] 产物命名统一规则
> 技术方案 = `3.<功能项序号>.1-<功能名>-技术方案.md`；接口清单 = `3.<功能项序号>.2-<功能名>-接口清单（前后端通用）.md`；任务拆解 = `4.1.<功能项序号>-<功能名>-任务拆解.md`；需求质量核对 = `1.2-需求质量核对.md`；规范核对报告 = `5.2.<功能项序号>-<功能名>-规范核对报告.md`；需求覆盖报告 = `5.3.<功能项序号>-<功能名>-需求覆盖报告.md`。**功能项序号 = 功能清单功能项表格的 # 列**（3.x / 4.1.x / 5.2.x / 5.3.x 同一功能用同一序号）；**文件名禁止拼接任务 ID（T0xx）、需求点编号或任何额外前缀**——任务 ID 只用于 commit message，不进入产物文件名。
> **模板编号 ≠ 产物编号**：`templates/` 下模板的 `3.0/3.1/3.2/3.3/3.4` 等是**模板库索引号**（每类模板一份）；产物文件名里的 `3.<功能项序号>.1/.2` 等是**产物编号**（功能项 × 子产物序号）。两者体系不同、不要求对等（如接口清单模板是 `3.4-…`，产物是 `3.<功能项序号>.2-…`）——产物的规范文件名以上面规则为准。

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

示例（订单模块 V1.2.0）：

```
docs/
├── 0.5-存量代码扫描.md            # 存量扫描结论（老代码迭代时生成，项目级）
└── 订单模块V1.2.0-20260824103000/
    ├── 1.1-功能清单.md
    ├── 1.2-需求质量核对.md         # 原文回读 + 矛盾扫描 + 术语对齐（1.3 澄清前置）
    ├── 1.3-澄清问题清单.md
    ├── 2.1-项目约束.md
    ├── 3.1.1-订单创建-技术方案.md
    ├── 3.1.2-订单创建-接口清单（前后端通用）.md  # 功能项接口契约（URL/JSON 入参/JSON 出参），后端完成后直接给前端
    ├── 3.2.1-用户管理-技术方案.md
    ├── 3.2.2-用户管理-接口清单（前后端通用）.md
    ├── 4.1.1-订单创建-任务拆解.md
    ├── 5.2.1-订单创建-规范核对报告.md
    ├── 5.2.2-用户管理-规范核对报告.md
    ├── 5.3.1-订单创建-需求覆盖报告.md
    └── 5.3.2-用户管理-需求覆盖报告.md
src/
└── main/java/com/example/order/    # 业务代码
```

### 方式二：一句话全流程

用户说"按流程开发 XX 模块"时，**先执行上方"开发场景判定"**（新项目→0.0；老代码迭代→0.5 含优化决策闸门；已接入规范新模块→1.1；**同模块已有产物迭代→0.8 变更影响分析**），再按流程顺序执行。**命中可行性风险信号（未用过外部系统/选型争议/成本不清新方向）→ 人确认是否先 0.6 `/feasibility`**（一页速评 go/需澄清/kill，人拍板）。**需求跨多 Java 模块 / 超大 / 混杂非 Java 服务端内容（任一）→ 先执行 0.9 `/req-intake`**（非 Java 部分直接忽略，人确认后各模块才进入 1.1）；单模块纯 Java → 直接 1.1。**每步产物必须给人确认后才能进入下一步**（见下方"中间产物确认闸门"；1.1 后必须过 1.2 `/req-gate` 需求质量核对闸门才可进 1.3）。中途用户可要求跳到任一 `/命令`。

### 方式三：轻量模式（写个接口 / 改个功能，非完整模块开发）

当用户只是"写个 XX 接口 / 实现 XX 功能 / 改段代码"，而非完整模块开发时，**不强制走 1.1~4.1 重步骤**，直接：

1. **加载规范**（写码前必做）：Java → java-code-standards + comment-standards；SQL → database-standards；pom → build-standards
2. **写码**：全量注释 + 全量日志
3. **收尾兜底**（硬性）：加载 **check-standards** skill 逐项核对，未执行到位项提示用户确认是否补齐

> 轻量模式只是跳过"功能清单/技术方案/拆任务"这些中间产物，**代码质量三条硬要求（全量注释、全量日志、check-standards 兜底）不打折**。老项目迭代同样先按上方"开发场景判定"走 0.5 存量扫描（至少对齐老项目包结构/返回体/命名/中间件），再走轻量模式。
>
> [!CAUTION] 轻量模式不豁免变更溯源
> **同模块已有历史产物时，改逻辑/迭代一律先走 0.8 `/change-impact` 定位旧产物、出产物同步计划（人确认）**——产物同步到位后才允许写码。轻量模式仅适用于**真·新增的零散接口/工具**（无既有产物需同步）；拿不准是否影响既有功能 → 先 0.8，**禁止拿"轻量模式"当绕过产物同步的借口**。

## 产物进度与接续断点（/progress）

每个模块版本目录维护一份 `通用-模块进度与断点.md`（`docs/<模块名>V<版本号>-<时间戳>/通用-模块进度与断点.md`），作为该模块的**唯一进度事实**：

- 在 1.1 `/feature-list` 创建模块版本目录时**同步创建**（模板 `templates/通用-模块进度与断点.md`）；
- 每个中间产物**经人确认后同步更新**对应步骤行状态（只允许 `✅ 已确认` / `🔲 待办` / `⏸ 当前断点`，禁止另造状态值）；
- **跨会话 / 换人接手必须先 `/progress`**：读 通用-模块进度与断点.md → 报告断点 → 从断点续跑，**禁止从 1.1 重跑**（流程产物 + 人工闸门可被机器化接续，但每次续跑仍遵守对应步骤的确认闸门）。
- **自然语言续跑入口**：用户说「继续订单模块」「继续订单模块的需求」「继续上次中断的任务」「接着上次」等 → 一律按本机制处理：AI 收到此类意图即执行 /progress 逻辑（定位模块 → 读 通用-模块进度与断点.md → 报告断点 → 从断点续跑）。

## 经验记录与回流（docs/experience.md，可选）

使用者的项目级经验/使用总结统一记录在项目 `docs/experience.md`（与 `0.5-存量代码扫描.md` 同级，跨模块共享一份；**不进技能安装目录、不进模块版本目录**）：

- **何时写**：5.3 需求覆盖收尾、bugfix 完成后，把本次踩坑追加一条（模板 `templates/通用-经验记录.md`）
- **何时读**：1.1 拆需求前、0.8 / bugfix 动手前，检索主文件相关条目并遵循（按模块/关键词匹配，不整文件灌入）
- **条目状态与生命周期**：`本地` / `待上缴 [HARD]` / `✅ 已固化 → <出处>`；已固化条目**移入归档**（规则已接管，主文件不再重复驱动）
- **控制体积**：主文件只保留存活条目（建议 ≤40 条），归档到 `docs/experience-archive/YYYY-经验归档.md`
- **回流给维护者（可选）**：跨项目通用经验（标 [HARD]）按 `docs/experience-contributing.md` 交回；维护者评审后按"建议固化目标"翻译成**对应 skill 的规则/核对项**（不限 check-standards），随版本发布

## 中间产物确认闸门（强制，所有步骤适用）

**每一步产出中间产物后，AI 必须停下来，等人在场确认，禁止连续执行到下一步。**

确认流程（每步通用）：

```
1. 该步产物落盘（md/代码）
2. AI 对照该步"完成标准"逐项自检，向人展示：
   - 产物位置（文件路径）
   - 完成标准核对结果（每项 ✅/❌）
   - 关键内容摘要（如功能清单表格、约束条目、方案要点、需求覆盖结论）
3. 人检查产物 → 确认通过 / 提出修改意见
4. 人确认后 → 才进入下一步；有修改意见 → AI 修改后重新展示确认
```

- **每步一个闸门，禁止跨步**：0.5 确认后才能 1.1；0.8 确认后才能 1.1（迭代场景）；1.1 确认后才能 1.2；1.2 确认后才能 1.3；1.3 确认后才能 2.1……依次类推
- 关键闸门（必须人明确确认，不能默认通过）：
  - **0.5 优化决策**：是否按规范优化存量代码——人明确选择（优化哪几项 / 跳过）后才可进入 1.1
  - **0.6 可行性评估结论（可选前置）**：命中风险信号时一页速评结论 🟢 go / 🟡 需澄清 / 🔴 kill——**人拍板后才可进入 1.1**；🟡 待澄清项逐项裁决后才放行；人选择跳过评估则无本闸门
  - **0.8 变更影响分析（迭代场景强制）**：历史产物定位 + 变更映射 + 产物同步计划——**人确认后才进入 1.1，未确认不动任何代码**
  - **0.9 需求构成清单（可选前置）**：模块边界 + 各模块需求 md（含来源段落追踪）——**人确认后才进入 1.1**
  - **1.1 功能清单**：类型/验收标准/依赖是否齐全；**需求分档（A/B/C）+ 验收基线已确认**；迭代场景 0.8 变更映射已全部落实
  - **1.2 需求质量核对（强制独立节点）**：原文回读核对无遗漏/误读残留 + 矛盾项无静默选边 + 术语↔码值对齐（对不上已标 🔲）——**本闸门通过（用户确认）是进入 1.3 的前提，1.2 报告未确认不得进入 1.3**
  - **1.3 澄清问题清单**：所有"待确认"项必须人逐项确认（含 req-gate 交来的矛盾/术语 🔲 项；已有问题清单模板）
  - **2.1 项目约束**：技术选型与硬规则是否符合预期
  - **3.x 技术方案**：接口/DDL/验收场景无"待定"
  - **4.1 任务拆解**：任务粒度 + 每任务完成标志可独立判定
  - **5.1 编码结果**：按方案实现完成 + 代码抽查
  - **5.2 规范核对报告（强制独立节点）**：全部核对项（无级别之分，含方法级注释/日志全覆盖）全 ✅ 或 ❌ 已补齐（报告落盘 `5.2.<功能项序号>-<功能名>-规范核对报告.md`）——**本闸门通过（用户确认）是进入 5.3 的前提，5.3 `/accept` 前置检查报告存在性，无报告拒绝验收**
  - **5.3 需求覆盖报告**：逐需求点均落到 `file:line` 证据或明确"未找到（缺口）"；双向核对完成；语义/行为类结论已标注"静态未验证，需按需行为验证"（**语义项禁止打 ✅**）；缺口经人确认处理；Listener/Job 默认标"未验收"、不阻塞收尾
- 人未确认前，AI 不得继续下一步（这是"防跑偏"的第零道闸门：人有权在任意一步叫停修正）

## 五步流程

每步的详细指令见对应 `commands/` 命令文件，模板见 `templates/`。

### 0.6 需求可行性评估（可选前置）→ `/feasibility`

**适用范围**：需求命中**风险信号**（未用过的外部系统/中间件/第三方 SDK、技术选型有争议、成本不清的新方向/新领域）时，先回答"**值不值得做、做不做得动**"。**普通需求直接跳过本步进 1.1**。与 1.1 需求分档（A/B/C 管"描述质量"）、1.3 澄清（管"细节歧义"）分工不同——本步管"可行性/方向"。**人确认是否执行；命中信号但人选择跳过 → 直接进 1.1**。

- **输入**：原始需求文档 + 开发场景判定结论
- **动作**（详见 `/feasibility` 命令）：风险信号判定（命中任一 → 展示并请人确认执行）→ 读事实（需求文档/相关产物/0.5 存量扫描结论等，**实查不凭空**）→ 自查关键未知（读码/查文档查得清的当场查清）→ 按模板一页速评（风险扫描表 + 关键未知结论 + 体量粗估 + 备选路线 ≥2）→ 结论 🟢 go / 🟡 需澄清 / 🔴 kill → **人拍板**
- **输出**：`0.6-需求可行性评估.md`（模块版本目录已建则放入其内，未建放 docs/ 根）
- **完成标准**：风险信号判定明确（未命中则直接进 1.1）；已有事实实查非凭空；风险扫描无空行 + 备选路线 ≥2 + 有推荐；结论经人拍板；🟡 待澄清项逐项裁决后才可 go；go 后按正常入口进 1.1（超大/跨模块按需先 0.9 `/req-intake`）；🔴 kill 理由与重启条件存档

### 0.8 迭代变更影响分析（人 + AI）→ `/change-impact` ★ 同模块迭代必做

**适用范围**：**同模块已有历史产物目录**（`docs/<模块名>V<版本>-<时间戳>/`）时，改逻辑 / 迭代新需求。这是解决"改逻辑没比对旧需求、没同步产物，越改越乱"的**入口闸门**。

**为什么必须有这一步**：老需求开发的产物（1.1 功能清单 / 3.x 技术方案 / 接口清单）是后续迭代的**比对基准**。若改逻辑时直接从代码入手、不回源更新产物，产物与需求/代码失同步——下次迭代失去参照，规格漂移悄悄发生。本步强制**先找到旧产物 → 变更映射 → 从源头（1.1）同步更新 → 最后才动代码**。

- **输入**：本次变更描述 + 该模块历史产物目录（`ls docs/` 实查，取最新版为基准，旧目录只读不改）
- **动作**（详见 `/change-impact` 命令）：
  1. **定位历史产物**：列出模块所有版本目录，读取最新版 1.1 功能清单 / 3.x 技术方案 / 接口清单
  2. **变更点映射**：把本次变更拆成变更点，逐点映射到旧产物与旧功能项（**新增** / **修改** / **删除**）；落不到旧产物的"新增"也明确记录
  3. **产物同步计划**：按 1.1 → 3.x.1 技术方案 → 3.x.2 接口清单 → 4.x → 5.x 顺序列出受影响产物及动作；注明不受影响（继承）项，避免无谓重写
  4. **变更影响确认闸门**：向人展示定位 + 映射 + 计划，**确认后才进入 1.1**（以本分析为输入）
- **输出**：`0.8-迭代变更影响分析.md`（新版本目录已建则放入其内，未建先放 docs/ 根，1.1 建目录时移入）
- **完成标准**：历史产物已定位（实查目录）；变更映射完整（每变更点落到旧产物或明确新增）；产物同步计划按流程顺序列出；新版本号已确认、旧目录不动；**人确认后才进入 1.1，未确认不动任何代码**

### 0.9 需求入口整形（可选前置）→ `/req-intake`

**适用范围**：需求文档**跨多个 Java 模块 / 体量超大 / 混杂非 Java 服务端内容**（三者任一命中）。单模块纯 Java 小需求直接跳过本步进 1.1。本步解决"超大跨栈需求硬塞给 1.1 → 拆漏 + 无人能一次确认"。

- **非 Java 服务端需求（硬规则）**：前端/App/小程序/其他语言服务端等**一律直接忽略**——不拆、不列入清单、不产文件；仅清单末句注明"已忽略非 Java 服务端部分"
- **输入**：原始需求文档 + 开发场景判定结论
- **动作**（详见 `/req-intake` 命令）：触发判定 → 忽略非 Java 部分 → 识别 Java 模块边界（AI 提议、人拍板）→ 模块清单确认 → 逐模块生成「模块需求 md」（含**来源段落追踪**/验收基线/跨模块依赖）→ 推荐开发顺序 → 人确认一轮
- **输出**：`docs/req-intake-<YYYYMMDDHHMMSS>/` 下《需求构成清单与确认.md》+ 每 Java 模块一份《<模块名>-模块需求.md》（后者为该模块 1.1 的输入）
- **完成标准**：触发判定明确；非 Java 部分已忽略；模块边界与各模块需求 md **经人确认**；确认后各模块才可进入 1.1 `/feature-list`（模块已有历史产物 → 1.1 前先 0.8）

### 1.1 功能清单（人主导）→ `/feature-list`

**这一步决定需求是否被完整实现**——拆漏一个需求点，后续方案/编码/验收全链缺失。

- **输入**：需求文档；**迭代场景（已走 0.8）→ `0.8-迭代变更影响分析.md` 为输入**（从源头继承旧 1.1 清单 + 按变更点同步，不是从零重拆）
- **动作**：
  1. **需求准入（先做，未确认不拆解）**：**需求分档**（A 结构化完整 / B 有模糊 / C 碎片化口头描述——C 档先补需求文档再走流程，不直接开工）+ **验收基线确认**（本次以哪份文档哪个版本为准、是否存在文档外的口头补充需求），结果写入功能清单速览框
  2. **先过滤非 Java 服务端需求**（前端页面/移动端/小程序/其他语言服务端等 → 不拆功能项，记入"已过滤"清单，不进入本流程开发范围；前端可走 vue-ai-dev）
  3. **列需求点清单**：需求文档逐条拆成需求点（编号+描述+来源），先穷尽需求再设计功能
  4. **拆功能项**：每项 = 可独立验收的用户可感知能力（一个端点/一个消费逻辑/一个 Job/一组内聚 CRUD），标注"承接需求点"；模糊需求标"待澄清"不强行拆解；走 0.5 时对照存量扫描结论避免重复建设；**迭代场景按 0.8 同步计划执行**——旧功能项继承（变更的改验收标准/新增项补行/删除项移除），需求覆盖核对同步
  5. **需求覆盖核对**：逐条对照需求点——每个需求点有承接（功能项 / 已过滤 / 延后），**不允许静默消失**
  6. **MVP 切分**：P1 集合 = 本期最小可交付；记录非功能需求（性能/安全/审计，标注落地位置）
- **输出**：功能清单总览文件（表格），每项含：承接需求点、类型（Controller/Listener/Job）、优先级、依赖、**验收标准**（每条 **GIVEN-WHEN-THEN 三段式**——GIVEN 前置状态/数据 → WHEN 操作/调用 → THEN 可观测结果，多态用多条并列，禁形容词/禁"实现 XX 功能"；写法见模板"验收标准写法"章节）
- **完成标准**：需求准入已确认（分档 + 基线）；需求覆盖核对通过（无静默消失的需求点）；每项有类型 + **GIVEN-WHEN-THEN 可验证验收标准** + 依赖标注；粒度符合标准；MVP 切分明；非 Java 服务端需求已过滤并记录；**迭代场景：0.8 变更映射项已全部在 1.1 落实（继承/修改/新增/删除）**；**产物经人确认后执行 `/req-gate`（1.2）过需求质量核对闸门，才可进入 1.3**

### 1.2 需求质量核对（人 + AI）→ `/req-gate` ★ 1.3 前的强制闸门

**为什么必须有这一步**：功能清单只证明"需求点被拆成了功能项"，不证明"需求点本身拆对了"——需求点由 AI 拆解，若拆解时误读/收窄范围、或在文档矛盾处静默选边，需求覆盖核对照样全绿。老项目还常有"需求术语与现有系统枚举/码值对不上"的问题（如"标准商品" vs `MallProductTypeEnum.PHYSICAL`），若不在方案前对齐，会一路拖到编码收尾才暴露。本闸门对需求文档原文做三道独立核对，把"拆错的需求"拦在方案与编码之前。

- **输入**：1.1 功能清单 + **需求文档原文** + 存量枚举/码值事实源（老项目 → `docs/0.5-存量代码扫描.md`，缺失先 `/legacy-scan`；新项目 → grep 现有枚举类/常量类）
- **动作**（详见 `/req-gate` 命令）：
  1. **原文回读核对**：回读需求文档**逐节**比对（非逐条）——每节原文有对应需求点/功能项承接；无承接 = 遗漏信号（补项或明确"过滤/延后"），功能项与原文口径不符 = 误读信号（回退修正）；**①·补 验收标准格式核对**：1.1 每条验收标准为 GIVEN-WHEN-THEN 三段式且 THEN 可观测，不合格 🔧 回写 1.1
  2. **跨节矛盾扫描**：把文档所有**规格性表述**（字段/规则/数值/枚举/状态机/口径）两两交叉核对冲突（如 7.3.1 vs 7.3.2 列不一致、跳转类型与跳转目标打架）——发现矛盾**禁止静默选边**，标 🔲 交 1.3 由人裁决；**②·补 枚举/状态机械对照矩阵**（需求含规格性表格时强制）：枚举一致性矩阵 + 状态×动作闭合矩阵，取值不齐/状态无迁移/引用枚举外状态 → 必出 🔲
  3. **术语↔码值对齐**：提取需求术语/枚举值对照存量事实源建映射表（需求用词 ↔ 现有枚举/码值）——对不上标 🔲（是否新增由人裁决，**禁止擅自造新枚举**）；老项目未跑 0.5 → 自动提示先 `/legacy-scan`
- **输出**：`docs/<模块名>V<版本号>-<YYYYMMDDHHMMSS>/1.2-需求质量核对.md`（需求基线 + 回读核对表 + 验收标准格式核对 + 矛盾清单 + 枚举/状态矩阵 + 术语对齐表 + 待确认汇总）；🔧 修正项当场回写 1.1
- **完成标准**：逐节回读无遗漏/误读残留；验收标准全部 GIVEN-WHEN-THEN（不合格已回写 1.1）；矛盾项全部标 🔲 无静默选边；枚举/状态矩阵已产出（无规格性描述注明跳过）；术语对齐 🔲 已汇总；**产物向人展示确认后才进入 1.3**（1.2 报告是 1.3 的前置输入）

### 1.3 澄清（人 + AI）→ `/clarify` ★ 方案前必做

- **输入**：功能清单 + **1.2 需求质量核对产物**（矛盾/术语 🔲 项在此澄清裁决）+ **追问模式库**（`docs/追问模式库-Java.md`）
- **输出**：澄清问题清单（人确认答案）+ 更新后的功能清单（补边界/风险列、依赖）
- **动作**：**① 先扫追问模式库**（`docs/追问模式库-Java.md`：字段/枚举/状态/权限机械信号命中必问，不许自己选答案；同一字段多条命中只出优先级最高一条；1.2 已裁决项不重复问）→ **② 逐项盘问四类问题**——**歧义**（模糊词/未定义字段/不可验证标准）、**入口形态与复杂度**（有/无入口、简单/复杂、跨功能项规则归属）、**边界用例**（重复/并发/空值/超长/状态流转）、**依赖**（功能间/外部系统/数据）；**并逐项裁决 1.2 交来的矛盾/术语 🔲 项**（每条给出 AI 建议默认值，人拍板）
- **完成标准**：模式库已扫描（命中已全部进清单，无命中注明）；无"待确认"残留（含 1.2 🔲 项已全部裁决）；每个功能项边界用例已列出；依赖完整

> 这是防跑偏的第一道闸门：歧义带进方案，后面全偏。宁可在这里多盘问，不要带歧义进入 `/design`。

### 2.1 项目约束（人主导）→ `/constraints`

- **输入**：功能清单
- **模式**：三种情况——
  - **标准模式**（新项目 / 未走 0.5 / **走 0.5 且选择按规范优化**）：按规范 skill 生成约束（见下"输出"）；走 0.5 选优化时，老代码已按所选规范优化过，新代码按规范——**中间件版本/账号等老项目事实仍对齐**（引用 `docs/0.5-存量代码扫描.md` 中间件清单，不在优化范围）
  - **存量适配模式**（已走 0.5 且用户选择跳过存量优化）：按 `docs/0.5-存量代码扫描.md` 生成约束，**约束来源 = 老项目实际约定**——新代码放入的包结构、返回体/公共组件（类名与位置对齐老代码，如 `R`/`Response`）、字段命名风格（Java 命名 + 数据库字段与老项目一致）、中间件（数据库/MQ/Redis/JOB 的版本、账号、接入规范与老代码一致）；规范 skill 仅在老项目无对应约定时兜底；**注释与日志不豁免**——新代码仍按 comment-standards 全量注释 + 日志完善（见下方"输出"注释/日志规范）
  - **存量模式与老项目约束文件的关系（去重引用，不复制）**：老项目**有**项目级约束文件（AGENTS.md / CLAUDE.md / GEMINI.md / README 规范章节等，**以实际存在为准**）→ 文件里**已有的约束在 2.1 中直接引用**（"按老项目约束文件《XX》执行"，不复制内容），**只把文件里没有的约定补充进 2.1**；老项目**无**此类文件 → 扫描到的约定**全部写入 2.1**（2.1 是本次开发的唯一约束来源）
- **输出**：技术架构 + 项目约束（硬规则，能检查对错，禁止"尽量/建议"）+ **注释规范**（全量注释规则：所有类/变量/方法必须注释（含 private/抽取方法）+ 方法体步骤注释 + // WHY: 约定，含正反例；**存量适配模式同样全量，不豁免**）+ **日志规范**（全量日志规则：全类 @Slf4j + **每个业务方法方法体 ≥1 条 INFO/WARN/ERROR 日志（含 private 抽取方法，debug 不算）** + 入口入参耗时 + 关键节点 INFO + 异常 ERROR 带堆栈，见 java-code-standards `00-common/04-logging-standards.md` §1.6）+ **公共组件规范**（包结构约定 common/util|base、第 2 个使用点必须抽公共、禁止复制粘贴）
- **工具选型人确认（标准模式强制）**：生成约束前先向用户确认两项工具选型——**日志框架（Logback / Log4j2）**、**接口文档工具（springdoc-openapi / knife4j / Apifox）**，写入技术架构表与硬性约束，禁止默认替用户决定；**老项目（0.5 存量适配）**由 0.5 扫描确认老项目所用工具，新需求对齐（不重新选型）
- **完成标准**：每条约束可检查，版本号写死，AI 可直接读取；存量模式下每条约束有老代码出处（类/配置/目录）

> [!NOTE] 约束的生效范围
> - **标准模式（新项目）**：2.1 生成后**同步写入项目根规范文件**（`AGENTS.md`，或项目约定的规范文件——无则创建、有则追加到规范章节），成为整个项目的长期规范——后续所有模块开发都遵守，不限于本次。模块目录内的 `2.1-项目约束.md` 是本模块的产物副本（本次开发引用）。
> - **存量适配模式（老项目跳过优化）**：2.1 **仅本次开发流程内生效**（1.1~5.3 引用），**不写入项目 AGENTS.md**——老项目未接入规范体系，本次约束只约束本次新代码，不影响老项目其他部分。

### 3.x 技术方案（人 + AI 辅助）→ `/design`

- **输入**：功能清单
- **动作**：读功能项的类型列，选模板组合——**3.0 通用骨架必用**（基本信息/验收场景/公共组件识别/注释要求/自检），类型特有内容按四段式（入口定义/数据契约/核心逻辑/关注点）取自对应类型模板：Controller → `3.1`、Listener → `3.2`、Job → `3.3`；无入口形态（配置/工具/纯数据）→ 仅用 3.0，跳过类型段；每功能项做**架构自检**（识别重复逻辑，判定抽工具类 common/util 还是抽象基类 common/base，结果写入方案"公共组件识别"小节）
- **输出**：每功能项一份完整技术方案 md（`3.<功能项序号>.1-<功能名>-技术方案.md`，3.0 通用章节 + 类型四段内容合并）；**每个 Controller 类型功能项方案生成后同步产出 `3.<功能项序号>.2-<功能名>-接口清单（前后端通用）.md`**（按功能项聚合 URL/方法/JSON 入参/JSON 出参，后端完成后直接给前端，模板见 `templates/3.4-接口清单-前后端通用.md`；Listener/Job/无入口跳过）
- **盲答自核（方案输出后、交人确认前必做）**：AI **蒙住本方案**、只凭 1.1 功能清单 + 需求原文 + 2.1 约束，把方案里每个"需求没直说、AI 定了口径"的决策列成封闭题自答并**逐字摘抄依据**——摘不到原文 = 无依据设计，删除或转 1.3 澄清；自核记录写入方案"盲答自核记录"小节（全 ✅ 才交人确认）
- **完成标准（质量闸门）**：第零段定性正确；通用章节完整（验收场景三态/公共组件识别/注释要求）；类型四段齐全；接口明细逐 URL 且失败示例与错误码一一对应；核心逻辑含**调用骨架**（分层 + `→` 调用标注 + 中文步骤 + Mapper 内联 SQL，不写实现代码）；DDL 完整且业务 SQL 全量在方案内（无独立 sql 目录、无"DDL 外推 schema.sql"）；**所有 SQL 带注释（DDL 每列 COMMENT + DML/查询 SQL 每条 `--` 用途注释）**；类型特有横切关注点（权限事务/幂等死信/防重入批处理）已写明；**盲答自核已过（无"摘不到原文"的无依据设计残留）**

### 4.1 任务拆解（人主导，AI 辅助）→ `/task-breakdown`

- **输入**：技术方案 md + 项目约束
- **输出**：任务拆解.md（公共组件拆入 **Phase 0.5**——任务拆解内的公共组件阶段，与流程步骤 0.5 存量扫描无关；无重复则留空注明）+ DDL
- **完成标准**：每任务有文件路径 + **可独立判定的完成标志**（一行命令/curl/日志关键字即可判定，无需上下文）；公共组件复用点在功能任务中已写死（调用/继承，禁止复制）

### 5.1 AI 编码 + 5.2 规范核对 + 5.3 需求覆盖报告（AI 主导，人验证）→ `/implement` → `/check-standards` → `/accept`

**依赖链（防跳过，5.2 产物是 5.3 的前置硬依赖）**：`/implement`（按方案实现、完成即停）→ `/check-standards`（强制独立节点：**先矫正产物命名/路径**，再独立核对，产物 `5.2.<功能项序号>-<功能名>-规范核对报告.md` + 用户确认）→ `/accept`（**前置检查 5.2 报告存在性，无报告拒绝验收**；输出需求覆盖报告）。

- **5.1 `/implement` 输入**：任务拆解.md + 技术方案 + 项目约束；**输出**：按方案实现的代码（含按注释规范生成的注释）+ 编码完成报告（**编码完成即停，不自行执行全量规范核对**）
- **5.2 `/check-standards`（强制独立节点）**：**先矫正产物命名与路径**（docs/ 中间产物须符合技术方案 3.x.1 / 接口清单 3.x.2 / 核对报告 5.2.x / 需求覆盖报告 5.3.x 规范，去文件名任务 ID 前缀，移入模块版本目录，改动引用同步；矫正清单先向用户确认），再由本节点独立核对——**优先跑 check-standards skill 的 `scripts/check_standards.py` 机械扫描（无 Python 回退 grep/ast-grep）**核对**全部核对项（无级别之分，优先核对方法级注释/日志全覆盖：public + private/抽取方法逐个查 Javadoc 与方法内日志；其余含构造器注入/分层边界/Entity 不暴露/异常处理/命名/公共组件复用/SQL/框架等）**，每项附证据；**先判模式：选型敏感项（接口文档/日志框架/数据访问层/返回体）新项目按 2.1 人确认选型判定、老项目按 0.5 扫描约定判定**，其余按规范；**未执行到位项（含 INFO，不分重要与否）先向用户确认是否补齐（人确认后才动手），仍 ❌ 升级人工核对**；产物落盘 `5.2.<功能项序号>-<功能名>-规范核对报告.md` 并**向用户展示报告获确认**（判定标准见 check-standards skill + `templates/5.1-编码指令.md`"关于关键规范核对"）
- **5.3 `/accept` 输入**：1.1 功能清单 + 3.x.1 技术方案（验收场景）+ 3.x.2 接口清单 + 5.1 代码 + **`5.2.<功能项序号>-<功能名>-规范核对报告.md`（前置硬依赖：先 `ls` 检查存在性，不存在 → 拒绝验收，返回 /check-standards）**；**动作**：由独立步骤（非编码 Agent 自评）逐需求点回读核对代码，产出**需求覆盖报告**——每个需求点给 `file:line` 证据或标"未找到（缺口）"；**双向核对**（需求→代码 是否有遗漏 + 代码→需求 有无需求没要求的东西）；**两类结论分列**——「可机器验证」（端点/字段/校验/错误码/DDL 是否存在，附证据）与「语义/行为」（显式标注"静态未验证，需按需行为验证"，**语义项禁止打 ✅**）；Listener/Job 默认标"未验收"（不阻塞收尾）；**缺口闭环**：未找到项 → 产出缺口清单 → 用户确认后追加任务回 `/implement` 补齐或人工确认豁免
- **完成标准**：5.2 报告全部核对项全 ✅（无级别之分，含方法级注释/日志）且**用户已确认**；需求覆盖报告逐需求点有证据或明确缺口、双向核对完成、语义项未打 ✅；公共组件已实现且使用点复用、无 ≥2 处相同方法体；缺口全部经人确认处理
- **按需行为验证**：本流程默认不生成、不执行任何测试代码。需要行为验证（接口真的能调通/事务并发行为正确）时，**按需加载 `test-workflow` 技能（`/gen-test`）**生成验收测试工具与独立报告，不阻塞主流程；**5.3 需求覆盖报告是静态结构核对，不替代运行时行为验证**。存量适配场景复用的中间件账号见 `0.5-存量代码扫描.md`；**账号缺失 → 向开发人员索取，禁止编造/凭印象填写**

## 硬性约束（写入编码 Agent 提示词，不可协商）

```
1. 严格按 Phase 顺序：先数据层 → 再公共组件（Phase 0.5，**任务拆解内的公共组件阶段，与流程步骤 0.5 存量扫描无关**）→ 再业务 → 再接口/消费/调度
2. 必须遵守《项目约束》的全部规则（逐条对照，含"注释规范"与"公共组件规范"章节）
3. **生成的代码必须遵守约束文件约定**：写任何代码前先对照 `2.1-项目约束.md`。标准模式遵守规范 skill 约定（Java → java-code-standards + comment-standards；SQL/表/MyBatis-Plus → database-standards；pom/依赖 → build-standards）；**存量适配模式遵守老项目约定（包结构/返回体/命名/中间件对齐老代码），规范 skill 仅在老项目无对应约定时兜底**。生成物不符合约束即不合格、需返工
4. 每个任务完成后独立提交（commit message = 任务 ID + 描述）
5. 不实现任务拆解.md 之外的东西（不做"顺手优化"）；Phase 0.5 列出的公共组件必须实现并被复用点调用/继承。编码中发现设计外的重复逻辑：不擅自抽取，标注 `// TODO(收敛)` 由需求覆盖阶段统一处理
6. 写代码时同 pass 生成注释（内容从技术方案派生，禁止事后补/编造），遵守注释规范（见 comment-standards skill）——**全量注释，禁止大段代码无注释**（存量适配模式同样适用，不因老项目注释稀疏豁免）
7. 写代码时同步生成日志（遵守日志规范，见 java-code-standards `00-common/04-logging-standards.md` §1.6 方法级日志覆盖）——全类 @Slf4j、**每个业务方法（public + private 抽取方法）方法体内 ≥1 条 INFO/WARN/ERROR 日志（debug 不算）**（入口记入参摘要+耗时、关键节点 INFO、异常 ERROR 带堆栈；大段逻辑 ≥10 行无 INFO/WARN/ERROR = 不合格；存量适配模式同样适用，不因老项目日志稀疏豁免）；收尾阶段核对注释、日志、权限、事务、幂等、防重入
8. **与简洁类 skill（如 ponytail）共存：先满足本流程硬规则，再追求最简实现**——本流程的分层/注释/中间产物是用户明确要求的硬规则，简洁类 skill 不得砍减；其极简原则仅在规范未指定的地方生效（见下方「与简洁类 skill 共存规则」）
9. **5.2 规范核对是强制独立节点（编码 Agent 不自行执行全量核对）**：5.1 编码完成后停下，进入 `/check-standards`（加载 **check-standards** skill：**优先跑 `scripts/check_standards.py` 机械扫描，无 Python 回退标准 grep/ast-grep 指令**）独立核对**全部核对项（无级别之分，含方法级注释/日志全覆盖——private/抽取方法逐个查）**，每项**附实际执行证据（文件:行号）**；**所有未执行到位项（无级别之分）→ 一起向用户展示证据、确认"是否按规范补齐" → 用户确认后才执行补齐** → 重跑该项 + 新证据 → 仍 ❌ → 升级人工核对；产物 `5.2.<功能项序号>-<功能名>-规范核对报告.md` 落盘并获用户确认后，才可进入 5.3 `/accept`（其前置检查报告存在性，无报告拒绝验收）。禁止"没做就声称做了"、禁止编码 Agent 自评通过、禁止把任何 ❌ 当"不重要"跳过
```

## 与简洁类 skill 共存规则（如 ponytail）

同时加载本流程 skill 与简洁类 skill（ponytail：YAGNI / stdlib 优先 / 最少文件 / 最短 diff）时，按以下优先级协调，禁止互相覆盖：

1. **本流程产物是用户明确要求的硬规则**：分层（Controller/Service/Impl/Mapper/Entity/DTO/VO）、注释规范（comment-standards）、中间产物 md（功能清单/方案/需求覆盖报告）——简洁类 skill 的"最短 diff / 解释不超 3 行 / YAGNI applies to tests"**不适用于这些显式要求的产物**。ponytail 自身的"Never simplify away: anything explicitly requested"条款与之天然兼容
2. **优先级：规范硬规则 > 极简优先 > 默认行为**——先满足规范，再追求最小实现；规范未指定的地方（如公共组件识别、依赖选型、实现方式）才应用简洁类 skill 的极简原则
3. **简洁类 skill 的适用边界（在规范内生效）**：
   - 不重复造轮子：规范已约束的公共组件/工具类直接复用，不重写
   - 不引入多余依赖：已有依赖能解决的不新增（对齐 build-standards 依赖规范）
   - 不写规范未要求的抽象：无单一实现接口、无多余配置项
   - 公共组件识别更保守：第 2 个使用点才抽公共的规则不变，但候选更严格
4. **流程产物不受"解释超 3 行"限制**：功能清单/技术方案/需求覆盖报告是用户显式请求的文档，给出完整内容

> 注意：存量适配模式（老项目跳过优化）同样适用本规则——对齐老项目约定仍是硬约束，简洁类 skill 只在老项目无约定处生效。

## 常见错误

| 错误 | 修正 |
|---|---|
| 跳过 3.x 直接让 AI 写代码 | 方案有歧义，后面全跑偏。3.x 是质量闸门，宁可多花时间 |
| 约束写成"尽量/建议" | 无法检查 = 无效约束。必须是能判对错的规则 |
| 验收场景只写正常路径 | 非法/边界场景缺失 = 需求覆盖有洞。三态都要有 |
| 实现完不核对方案 | 规格漂移悄悄发生。验收核对应是最后一关 |
| 让 AI 编码时"顺手"抽公共类 | 会跑偏（改任务外代码）。公共组件必须方案期识别（3.x 架构自检）+ 拆入 Phase 0.5，编码只实现不复抽 |
| 委派断链后直接编码却不加载规范 skill | 生成物不符合规范、验收返工。规范 skill 加载是写码前第一步，见硬性约束第 4 条 |
| 澄清阶段没确认入口/复杂度 | 第零段判定靠 AI 猜，方案四段选错、全链跑偏。入口形态/业务复杂度/状态机归属必须在 1.3 澄清盘问并由人确认 |
| 需求文档有矛盾/术语不齐就直接拆功能项 | 需求点拆错（误读/收窄/静默选边）覆盖核对照样全绿。1.1 产物确认后必须过 1.2 `/req-gate`（原文回读 + 矛盾扫描 + 术语↔码值对齐），未过闸不得进入 1.3 |
| 同模块改逻辑/迭代不溯源旧产物直接改码 | 产物与需求/代码失同步，越改越乱。docs/ 已有该模块历史产物目录 → 必须先 0.8 `/change-impact`（定位旧产物 + 变更映射 + 产物同步计划，人确认）→ 从源头 1.1 同步 → 才允许写码；**禁止用轻量模式绕过** |
| 把 5.3 需求覆盖报告当"验证通过" | 5.3 是**静态结构核对**，证明需求没漏做，不证明可运行（配置错误/连接失败/旧 jar 过期/库表未初始化它都查不出）。行为验证**按需**用 `test-workflow` 技能（`/gen-test`）真实调用接口，不阻塞主流程 |
| 修 bug 直接盲试改码（猜着改/改跑偏） | 缺陷修复先复现 + assess 根因（证据）→ 最小修复。**Bugfix 场景加载 `bugfix-workflow` skill（`/bugfix`）**；修复涉及需求/范围变更或该模块 docs/ 已有产物 → 先 0.8（产物同步不豁免），完成统一 `/check-standards` 兜底 |