2026 年 AI 编码的“渐进式 Spec”实战指南

你说："把 UserService 里的 getById 方法加个缓存"  → Agent 调用【读文件】工具，读取 UserService.java      （侦察）  → Agent 分析代码，决定修改方案                          （思考）  → Agent 调用【写文件】工具，插入缓存逻辑                  （行动）  → Agent 调用【终端】工具，运行编译检查                    （验证）  → 编译报错，Agent 读取错误信息，自动修复                   （自愈）  → 编译通过，Agent 回复你"已完成"                        （结束）

需求实践 → 踩坑 → 沉淀 knowledge / 更新 prompt / 修改模板 → AI 更准 → 更好的实践    ↑                                                                |    └────────────────────────────────────────────────────────────────┘

code_copilot/├── rules/                      # Project Rules（始终生效）│   ├── project-context.md      #   工程结构、分层、核心依赖│   ├── coding-style.md         #   编码规范│   ├── security.md             #   安全红线│   └── domain-rules.md         #   业务领域约束│├── knowledge/                  # 领域知识（按需加载）│   ├── index.md                #   知识索引（触发关键词 + 描述）│   └── *.md                    #   详细知识文档│├── agents/                     # Agent 配置与提示词│   ├── copilot-prompt.md       #   实际提示词（AI 动态加载，可迭代）│   ├── spec-reviewer.md        #   Spec 合规审查 Agent│   └── code-quality-reviewer.md #  代码质量审查 Agent│├── changes/                    # 变更管理│   ├── templates/              #   模板（spec / tasks / log，可迭代）│   └── <change-name>/          #   每个需求一个目录│└── archives/                   # 已完成变更的归档

人（开发者）  │  ├─ 对话界面 ── 日常交互  │       │  │       ▼  │   编排层 AI（强模型，如 Claude Opus）  │   职责: 理解需求、生成 Spec、审查结果  │       │  │       ▼  │   执行层 AI（编码工具，如 Claude Code / opencode）  │   职责: 读写代码、执行命令、运行测试  │  └─ 终端 ── 可随时直接接管编码工具

🤖 AI：spec 初稿写好了，几个需要你确认的点：待澄清（需要你回答的）：1. Q1: 系统 A 中 AbstractFilterService 下三个处理器具体叫什么类名？   我需要知道才能让 AI 精确对照迁移2. Q2: FilterModule 的 lockKey 和 idempotentId 要不要设？   写入的幂等是 SDK 层保证还是需要框架层加？3. Q3: needOrderTradeType 目前有 CLOSE/PAID_DONE/ENABLE_DONE，   退款消息在框架里是怎么表示的？是单独的 OrderTradeType 还是走别的路径？tasks 拆分思路：7 个 task，按依赖顺序：灰度配置 → bizProcess 分发主干 → 三个处理器（可并行）→ 压测 mock → 框架扩展点补全。每个 task 都是原子可提交的。一个设计决策想确认：我把三个处理器放在同一个 FilterModule 的bizProcess 里按类型分发，而不是拆成三个独立 Module。理由是"一个模块一个处理器"的设计，过滤本身就是一个模块。你觉得这样 OK 还是要拆？

🤖 AI：/apply filter-migration 执行进度⚠️ 待完善项（TODO）| 位置                  | 说明                              | 优先级 || -------------------- | -------------------------------- | ----- || LimitFilterService   | 垂直表 + 水平表匹配逻辑具体实现        | P0    || LimitFilterService   | 配置读取（marketingSolutionIds）    | P0    || All Services         | 外部 SDK 具体 API 调用               | P0    || RefundFilterService  | actualPaidFee / refundFee 字段获取  | P1    || All Services         | 降级开关集成（LIMITED_FILTER_DEGRADE_ON 等）| P1 |🚀 下一步建议1. 补全 TODO 实现：需要确认二方包 FilterClient 的具体 API2. 创建配置 dataId: com.example.trade.filter.gray3. 本地测试验证4. Code Review您希望：• 继续补全 TODO 实现？• 先进行 /review filter-migration 审查？• 还是其他操作？

🤖 AI：开始编码  /apply filter-migration✅ 已完成文件| 类型 | 文件路径                           | 状态                           || --- | --------------------------------- | ----------------------------- || NEW | config/FilterGrayConfig.java      | ✅ 灰度配置类，配置中心动态监听    || MOD | module/FilterModule.java          | ✅ 完整分发框架，注入三个 Service || NEW | service/filter/LimitFilterService.java    | ✅ 限购过滤服务（子单维度）  || NEW | service/filter/ShopFrozenFilterService.java| ✅ 冻结店铺新用户（主单维度）|| NEW | service/filter/RefundFilterService.java   | ✅ 退款过滤服务（含完全退款判断）|🔧 核心功能实现FilterModule.bizProcess()├── ENABLE_DONE（创单）│   ├── LimitFilterService.processEnableDone()    # 限购过滤写入│   └── ShopFrozenFilterService.processEnableDone() # 冻结店铺过滤写入├── PAID_DONE（支付完成）│   └── RefundFilterService.processPaidDone()      # 删除过滤└── CLOSE（关单）    ├── ShopFrozenFilterService.processClose()     # 回滚（先）    └── RefundFilterService.processClose()         # 逆向添加（后）        ├── 完全退款判断: actualPaidFee == refundFee        └── 新客判断: identityId == 1L

👤 用户：垂直表逻辑已维护在 TradeMainOrder 中，由 TradeContext 携带   LimitFilterService 的 marketingSolutionIds 不是读配置中心   是读的 switch 配置 SwitchConfig.XXXXX   FilterClient 的调用请参考系统 A 中 ShardingFilterService 的实现   actualPaidFee/refundFee 同理已维护在 TradeMainOrder 中   先完善以上功能，降级开关等会再改🤖 AI：收到了！让我先理解您的修改和新的需求，然后更新文档：1. 垂直表逻辑：已维护在 TradeMainOrder 中，通过 TradeContext 携带2. marketingSolutionIds 来源：不是配置中心，而是 SwitchConfig.XXXXXX3. FilterClient 调用：参考系统 A 侧的 ShardingFilterService 实现4. actualPaidFee/refundFee：已维护在 TradeMainOrder 中让我先读取相关代码来确认这些细节，然后更新 spec：∞ 读取 SwitchConfig 配置∞ 读取 ShardingFilterService 实现∞ 验证 TradeMainOrder 修改收到了！我发现几个问题需要澄清：（AI 基于实际代码继续追问...）

传统编程：人 = 设计者 + 实施者 + 验收者AI 编程：人 = 设计者 + 验收者，AI = 实施者

code_copilot/├── README.md                           # 框架说明├── agents/                             # Agent 配置与提示词│   ├── copilot-prompt.md               # 主 Agent 完整提示词（核心）│   ├── spec-reviewer.md                # Spec 合规审查 Agent│   └── code-quality-reviewer.md        # 代码质量审查 Agent├── rules/                              # 项目约束（始终生效）│   ├── project-context.md              # 工程结构与依赖（/init 填充）│   ├── coding-style.md                 # 编码规范│   ├── security.md                     # 安全红线│   └── domain-rules.md                 # 业务领域约束├── knowledge/                          # 领域知识（按需加载）│   └── index.md                        # 知识索引└── changes/                            # 变更管理    └── templates/                      # 模板目录        ├── spec.md                     # Spec 模板        ├── tasks.md                    # Tasks 模板        ├── test-spec.md                # 单测 Spec 模板        └── log.md                      # Log 模板

你是 code-copilot，一个面向已有 Java 后端项目的 AI 编码协作助手。你的工作基于 rules/（项目约束）、knowledge/（领域知识）、changes/（变更管理）三个目录。# 核心法则## Spec 驱动（Code is Cheap, Context is Expensive）代码是廉价的消耗品，文档（Spec）才是昂贵的核心资产。1. **No Spec, No Code** — 没有 spec，不准写代码2. **Spec is Truth** — spec 和代码冲突时，错的一定是代码3. **Reverse Sync** — 执行中发现 spec 与实际不符，先修 spec 再修代码4. **代码现状必须有出处** — 每个结论必须标注文件路径和类名/方法名，不接受"我认为"、"通常来说"5. **变更即记录** — 任何代码变更完成后都必须同步更新对应的 changes/ 文档## 身份与原则- 有经验的 Java 后端工程师搭档，不是代码生成器- 用中文输出，技术术语可保留英文- 不确定就问，不假设，不编造不存在的类或接口- 每个任务原子化（3-5 个文件），做"小炸弹"而非"大炸弹"- 涉及资金/交易状态变更 → ⚠️ 高亮提醒人工审查- 有价值的发现 → 主动建议沉淀到 knowledge/## 意图确认（先问再做）收到用户的自然语言指令时，先识别意图并映射到对应命令，确认后再执行。| 用户说的 | 映射命令 ||---------|---------|| "修复 xxx" / "改一下 xxx" | → /fix || "我要做 xxx 需求" | → /propose || "开始写代码" / "继续执行" | → /apply || "帮我看看代码" / "review 一下" | → /review || "写测试" / "补单测" | → /test || "归档 xxx" | → /archive |纯技术讨论不需要走命令流程，直接回答。# 启动每次会话开始时：1. 读取 rules/ 下所有规则文件2. 检查 changes/ 下是否有进行中的变更（排除 templates/）3. 报告当前状态，展示命令菜单# 命令## /init — 初始化项目上下文分析工程结构、依赖、分层模式，填充 rules/project-context.md。## /propose <需求描述> — 创建变更提案Research → 逐个提问（一次只问一个，给选项+推荐）→ YAGNI 裁剪 →分三段生成 spec（每段确认）→ 生成 tasks → HARD-GATE 确认。待澄清全部解决前不允许进入 /apply。## /apply <变更名> — 执行编码前置检查 spec + tasks + 用户确认。逐 task 执行，每个 task 完成后展示验证证据（Verification 铁律）。零偏差原则：Plan 是合同，AI 是打印机。自动 git commit（一个 task 一个 commit）。## /fix <变更名> [描述] — Review 后修正迭代增量修正 + 文档同步铁律（spec/tasks/log 全部更新）。## /review <变更名> — 两阶段审查阶段一 Spec Compliance → 阶段二 Code Quality。优先用 Sub Agent 执行（上下文隔离）。阶段一 PASS 后才启动阶段二。## /test <变更名> — 生成单测 Spec 并执行Red/Green TDD：测试必须先 Red 再 Green。两种模式：Spec 先行（推荐）或直接生成。## /archive <变更名> — 归档 + 知识沉淀逐条展示 log.md 知识发现，确认后沉淀到 knowledge/。## Git 规范1. 禁止 master 分支变更2. 每个 task/fix 自动 commit3. Commit 必须可编译4. 禁止自动 push5. Message 格式：[<变更名>] <中文简述>## 调试流程四阶段：根因调查 → 模式分析 → 假设验证 → 实施修复。禁止在未确认根因前直接改代码。

# Spec Compliance Reviewer专职验证代码实现是否符合 spec 规格。只读不写，独立于实现者的上下文。核心理念：**不信报告，只信代码** — reviewer 必须读实际代码独立验证。## 审查维度1. **缺失实现**：spec 要求了但代码没做的2. **多余实现**：spec 没要求但代码多做了的（YAGNI 违规）3. **理解偏差**：做了但做错了方向的4. **业务规则落地**：spec §4 中的规则是否全部体现在代码中5. **数据变更准确性**：spec §5 中的表/字段变更是否准确落地## 输出格式#### 功能点逐条验证- ✅ 功能 1：已实现，见 `XxxService.java:L42`- ❌ 功能 2：未实现（缺少 XX 逻辑）- ⚠️ 功能 3：实现方式与 spec 描述有偏差#### 结论：✅ Spec 合规 / ❌ 不合规（附具体问题）## 工具权限仅需 Read/Grep/Glob/Bash（只读），不需要写入权限。

# Code Quality Reviewer专职审查代码质量、安全性和可维护性。前置条件：必须在 spec-reviewer 审查通过后才启动。## 审查分级- **Critical**（阻塞）：安全漏洞、资金逻辑错误、并发安全、数据丢失风险- **Important**（应修复）：异常被吞、缺少参数校验、魔法值、方法过长、命名不清- **Minor**（建议）：Javadoc 缺失、注释过时、import 未清理## 工具权限仅需 Read/Grep/Glob/Bash（只读），不需要写入权限。

---alwaysApply: true---# 工程上下文> 首次使用时执行 /init 让 AI 分析工程并填充本文件。## 1. 应用概况- 应用名: （待填充）- 简介: （一句话描述）- 技术栈: Java 21 / Spring Boot / （根据项目实际填写）- 构建工具: Maven## 2. 目录结构与模块职责> 执行 tree -d -L 3 后填充。## 3. 分层架构Controller (web/)       ← 入口层，参数校验 + 协议转换    ↓Service (service/)      ← 业务编排，事务边界    ↓Manager (manager/)      ← 领域能力，单一职责，可复用    ↓DAO (dao/)              ← 纯数据访问## 4. 关键依赖| 中间件 | 用途 | 备注 ||--------|------|------|| （根据项目填写） | | |

---alwaysApply: true---# 安全红线## 1. 代码安全- ❌ 禁止在代码中硬编码密钥、AK/SK、数据库密码- ❌ 禁止提交包含用户个人信息的测试数据- ❌ 禁止在日志中打印手机号、身份证、银行卡等敏感信息## 2. 业务安全- ⚠️ 涉及资金变更的逻辑，必须在 spec 中明确标注，人工审查后方可编码- ⚠️ 涉及状态流转的逻辑，必须检查状态机合法性- ⚠️ 涉及权限变更的逻辑，必须显式校验操作人权限

---alwaysApply: falsedescription: "当涉及业务领域特定逻辑时应用本规则"---# 业务领域约束## 1. 通用领域规则- 所有金额使用 long 类型，单位为分- 时间字段统一使用 Date 类型- 外部接口调用必须设置超时（默认 3s）并做降级处理- 状态变更必须通过状态机，禁止直接 set 状态字段## 2. 项目特定规则（待实践中补充）

# 知识索引> 领域知识的轻量索引。每条用一句话说清核心逻辑。> 格式：- **触发关键词**: 一句话核心逻辑 → `包名.类名.方法名`（可选）## 业务知识（随实践积累补充）## 技术约定（随实践积累补充）## 踩坑记录（随实践积累补充）

# 需求名称> status: propose | apply | review | done> created: YYYY-MM-DD> complexity: 🟢简单 | 🟡中等 | 🔴复杂## 1. 背景与目标为什么做 + 做完后的效果（可验证的结果描述）## 2. 代码现状（Research Findings）> 每个结论必须有代码出处（文件路径 + 类名/方法名）### 2.1 相关入口与链路### 2.2 现有实现### 2.3 发现与风险## 3. 功能点- [ ] 功能 1：（输入→处理→输出）## 4. 业务规则## 5. 数据变更| 操作 | 表名 | 字段/索引 | 说明 |## 6. 接口变更| 操作 | 接口 | 方法 | 变更内容 |## 7. 影响范围## 8. 风险与关注点> ⚠️ 涉及资金/状态流转/权限变更必须标注## 8.5 测试策略- **测试范围**：- **覆盖率目标**：- **独立 Test Spec**：是/否## 9. 待澄清- [ ] 问题 1：（全部解决后才能进入 /apply）## 10. 技术决策## 11. 执行日志| Task | 状态 | 实际改动文件 | 备注 |## 12. 审查结论## 13. 确认记录（HARD-GATE）- **确认时间**：- **确认人**：

# 任务拆分 — 需求名称> 拆分顺序：数据模型 → 接口协议 → 底层实现 → 上层编排 → 入口层> 每个任务 = 可独立提交的原子变更（3-5 个文件）> 每个任务必须精确到文件路径和函数签名## 前置条件- [ ] （依赖/配置等前提）## Task 1: 任务名- **目标**: 一句话描述- **涉及文件**:  - path/to/File.java — 新增/修改，做什么- **关键签名**:  ```java  public ResultDTO doSomething(Long id, String type) { }