大家好，我是讯享网，很高兴认识大家。这里提供最前沿的Ai技术和互联网信息。



当前顶级模型可以独立完成中等复杂度的编码任务——理解需求、读代码、写实现、修编译错误，但仍需人审查结果。它们没有持久记忆、没有自主意图，只处理你给它的上下文。

不同模型之间的性能差异是断崖式的。Chatbot Arena 通过真人盲评计算 ELO 分数（截至 2026 年 3 月，536 万次投票、316 个模型）：

图片

Arena 的 Multi-Turn 维度衡量多轮交互稳定性（对应 Agent 场景）：Gemini 3.1 Pro 多轮第一，超过 Claude 4.6；Claude Sonnet 4.6 掉到第 10——单轮强不等于多轮稳。

梯队差异体感：同样是"给 Spring Boot 服务加个带缓存的分页查询"——T0 一次生成全链路且主动处理边界情况；T1 多提示一两轮可达到接近效果；T1.5 基本可用但容易漏边界；T2 能写骨架但需要较多人工调整。差距不在"能不能写"，而在一次做对的概率——T0 三轮搞定的事，T2 可能 15 轮还不一定对。

核心结论：模型是地基，方法论是上层建筑。地基不行，上面盖得再好也白搭。

---

知道了模型能力之后，下一个问题是：怎么让它自主行动？

裸 LLM 只是一个无状态的问答函数——你问一句它答一句，没有工具、没有记忆、不会自己行动。

Agent = while 循环 + Tool Use + 工具执行器，用一个例子说明：

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

这个循环就是 Agent 的全部—— "智能"来自模型，"能力"来自工具，"自主性"来自循环 。

关键理解：工具的边界就是 Agent 的能力边界。给它读写文件的工具，它能改代码；不给它网络工具，它就上不了网。安全靠框架约束，不靠 AI 自觉。

我们后面提到的 Cursor、Claude Code、opencode——本质上都是这个循环的不同包装，区别只在于给了哪些工具、跑在哪里、用的什么模型。

---

有了能自主行动的 Agent，最后一个问题是：用什么标准评判一个 AI 编码方案的好坏？

来自《人月神话》的核心洞察

• 软件复杂度 = 本质复杂度（业务逻辑本身，不可消除）+ 偶然复杂度（工具/流程引入的额外负担，可以且应该被消除）；
• 本质复杂度由业务决定，任何工具都不能消除它——交易状态机该多复杂还是多复杂；
• AI Coding 工具能做的是帮你更高效地应对本质复杂度（快速理解代码、生成实现、发现风险），但工具自身也会引入偶然复杂度（学习成本、流程开销、配置负担）；
• 评判标准：一个方案好不好，看它能多高效地帮你应对本质复杂度，同时自身引入的偶然复杂度有多低；
• 核心结论：所有方法论的设计都要回归这个起点——高效应对本质复杂度，压缩偶然复杂度。

---

一句话：在让 AI 写代码之前，先用结构化文档（Spec）把"要做什么、怎么做、有什么约束"说清楚，然后 AI 围绕这份文档编码。

为什么需要 Spec Coding——直接和 AI 聊天写代码（Vibe Coding）面临四个工程问题：

图片

Spec Coding 三条铁律：

1. No Spec, No Code — 没有文档，不准写代码
2. Spec is Truth — 文档和代码冲突时，错的一定是代码
3. Reverse Sync — 发现 Bug，先修文档，再修代码

这三条铁律在经济上也是合理的（Code is Cheap, Context is Expensive）：

图片

把需求、约束、代码现状写进 Spec 作为高质量输入 → 输入增加但便宜 → AI 不用反复试错 → 输出大幅减少 → 对话轮次从 20 轮降到 3-5 轮 → 总成本反而更低，效果反而更好。

Spec Coding 的理念很简单，但不同团队的落地方式差别很大。我们调研了多个主流实现后，吸收各方核心理念做了一套自己的框架。

图片

这是框架的核心卖点，也是和其他方案最大的区别。

为什么需要渐进式？ 其他方案都假设所有需求都值得走完整流程，但现实中并非如此——70% 的需求是 ≤5 人日的小需求。改个字段、修个 bug，也要先写 spec 再拆 tasks？这就是偶然复杂度在吃掉你的效率。

核心思想：不同复杂度的需求，暴露不同深度的流程——

关键原则：

• 简单需求不承担复杂流程的成本——改个字段不需要先写 spec 再拆 tasks
• 流程是可选增强，而非强制前提——Rules 始终生效，Spec 按复杂度加载
• 这本质上是在压缩偶然复杂度：只有本质复杂度够高时，才引入对应重量的流程

这个框架本身就是一个活的系统——prompt、模板、rules 都是代码库中的普通文件，随 Git 版本演进

图片

知识飞轮（不仅是领域知识，prompt 和模板自身也在飞轮中）：

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，可迭代） │ └── 
     
    
       
         / # 每个需求一个目录 │ └── archives/ # 已完成变更的归档 
       

Agent 提示词的核心设计要点：

1. 身份定位：有经验的 Java 后端工程师搭档，不是代码生成器
2. 启动流程：每次会话自动读取 rules/、检查 changes/ 进行中的变更、报告状态
3. 命令式路由：7 个命令（/init /propose /apply /fix /review /archive /knowledge），超出范围礼貌拒绝
4. Research 约束：代码现状必须有出处（文件路径+类名/方法名），不接受空口结论
5. 执行策略：默认逐步执行（暂停确认），支持批量和紧急停车
6. Reverse Sync：遇到偏差先修 spec 再修代码，强制回写
7. 安全红线：涉及资金/状态变更 → ⚠️ 高亮提醒人工审查
8. 知识沉淀：有价值的发现 → 主动建议沉淀到 knowledge/

Propose（提案）— 人主导，AI 辅助

Apply（执行）— AI 主导，人审查

Fix（修正迭代）— Review 后的增量修正

Review（审查）— 两阶段 Sub Agent 审查

Archive（归档）— 知识沉淀

逐条展示 log.md 中的知识发现和踩坑记录，询问用户是否沉淀到 knowledge/，确认的立即执行。变更目录移到 archives/。

Debug — 系统化调试流程

四阶段调试指引：根因调查 → 模式分析 → 假设验证 → 实施修复。铁律：禁止在未确认根因前直接改代码。

---

在实践中，我发现单一工具很难同时满足"强模型做决策"和"安全模型写代码"两个需求。最终演化出了编排层 + 执行层的两层 AI 架构：

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

为什么要分两层？ 不仅仅是安全考虑，更是关注点分离：

把两者混在一起，要么模型太贵（全程用顶级模型写代码），要么质量不够（全程用便宜模型做决策）。分层后各取所长，成本和质量都更优。

---

选择编码工具时，有一个关键经验：透明度不是奢侈品，是基础需求。

透明度底线：模型型号+版本可见、完整 context 可查、原始输出不被篡改、token 用量透明。

在不透明的工具上花再多时间优化 prompt 和框架，效果都无法归因、无法复现。切到透明工具链后，每次调优都能看到效果，迭代速度指数级提升。

目前满足透明度要求的主流开源工具：

选择建议：

• 如果团队用 Claude 系列模型，Claude Code 开箱即用
• 如果需要灵活切换模型（特别是接入私有部署的模型），opencode 更合适
• 如果团队更习惯 IDE 工作流，Cursor/Windsurf 是好选择
• 核心原则：工具是手段，方法论是不变的——上面的框架（rules/ + knowledge/ + changes/）可以适配任何编码工具

---

无论用什么工具，Git 规范是必须的：

1. 禁止 master 分支变更：编码前检查当前分支，master 上立即停止
2. 自动 Commit：每个 task/fix 完成后自动 commit，保持一个 task 一个 commit
3. Commit 必须可编译：commit 前执行编译检查
4. 禁止自动 Push：push 由用户主动触发，保留审查机会
5. Message 格式：[ <变更名> ] <中文简述>

---

以一个典型的跨模块业务迁移项目为例（将系统 A 的过滤处理逻辑平行迁移到系统 B），走一遍完整的 /propose → /apply → /review 流程。

将需求文档作为输入，执行 /propose，AI 先 Research 代码现状，然后逐个提问收敛不确定性：

🤖 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 必须先 Research 现有代码（带出处），不允许凭空设计
• 逐个提问而非一次列 10 个问题，优先给选项 + 推荐
• 待澄清项全部解决前不进入编码

Spec 确认后，AI 自动拆分为原子级 Tasks。执行一段时间后，AI 汇报进度并列出待完善项：

 🤖 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 的具体 API 2. 创建配置 dataId: com.example.trade.filter.gray 3. 本地测试验证 4. Code Review 您希望： • 继续补全 TODO 实现？ • 先进行 /review filter-migration 审查？ • 还是其他操作？ 

进入 /apply 阶段，AI 按 Tasks 逐个执行。每完成一批文件，展示完成状态和核心实现结构：

🤖 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 

执行过程中用户发现 Spec 遗漏或实现偏差时，AI 先确认事实再更新文档：

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

Reverse Sync 是最容易被忽略但最重要的环节 ：

保持文档和代码的一致性，才能让整个框架持续有效。

---

用 AI 编码之后，人的角色从「全干」变成了「管和验」：

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

具体来说，人做三件事：

• 管控 （控制 AI 看什么）
• 指挥 （选方案、审计划、批准执行）
• 评价 （验收结果、发现偏差）。

对应地，AI 在不同阶段切换角色：

• 侦察兵（扫描代码收集事实）→
• 参谋（提出方案分析利弊）→
• 施工队（按图施工）→
• 质检员（对照标准检查）。

听起来很清晰，但实际协作中有三个非常容易犯的错误：

1. 讨论和命令混为一谈

"帮我看看这个模块，顺便把 Bug 修了"——前半句是探索，后半句是指令。AI 会跳过探索直接改代码，然后改错。解决办法很简单：一次只给一种意图（探索 / 决策 / 指令 / 审查），不要混着来。

2. 阶段产出搞混

调研阶段要的是事实和风险，不是代码。AI 太勤快的时候要拉住它："停，我现在不需要代码，先告诉我现状和风险。"

3. 自由度给反了

这是最普遍的问题。正确的自由度曲线应该是：

大部分人的问题是反过来了——该讨论的时候急着让 AI 干活（方案没想清楚就开写），该干活的时候又让 AI 自由发挥（执行阶段不约束，改着改着就跑偏了）。

有一种批评认为 Spec Coding 建立在三个错误假设上——AI 能理解规范、规范能完整描述系统、规范比代码更易维护。

这些批判有道理，但忽略了一个关键前提：它批判的是「规范→代码」的全自动线性映射，不是人在回路中的 Spec 辅助模式。

问题不在于 Spec Coding 本身，而在于用法和预期。当成自动化流水线的输入，它确实不是银弹；当成人和 AI 之间的沟通协议，它就是一个靠谱的效率工具。

大部分团队在 AI 编码上的投入方向是：花大量精力写 Prompt、调 Rules、优化 Agent 工作流。这些都属于「偶然复杂度」层面——调好了最多让 AI 少犯格式错误。但真正决定 AI 输出质量上限的，是你喂给它的领域知识的质量。

知识覆盖缺口：

最关键的知识——领域 Know-How、架构决策的前因后果、踩坑后的**实践——恰恰是纯 Spec 框架最难覆盖的。这也是为什么框架里有 knowledge/ 目录，而不是只有 rules/。

打个比方：一个没有 knowledge/ 的 Spec 框架，就像让一个刚入职的应届生对着编码规范写代码——规范他都能遵守，但业务逻辑全靠猜。

往长远看，AI 编码工具会越来越同质化（Cursor、Claude Code、各种 IDE 插件的能力趋同），团队之间的差距不在于用什么工具，而在于积累了多少高质量的、结构化的领域知识。这才是真正不可复制的护城河。

编码需要高度专注。引入 AI 之后，连贯性被打破了——写 Spec、等生成、审查输出、纠正偏差、再继续下一段。模型越慢，等待越长，心流杀伤越大。

传统编码是「想→写→想→写」的连续流，AI 编码变成了「想→写 Spec→等→审→改→想」的间歇流。你需要适应这种新节奏，也需要诚实地评估：对于你个人，哪些任务用 AI 确实更快，哪些还不如自己写。

Context 很贵，但贵的不只是 Token 费用。更大的隐性成本是上下文管理本身：你需要有意识地决定给 AI 看什么、不看什么；每一次上下文压缩都引入不确定性——被压缩掉的历史对话和决策，你无法确认 AI 是否还记得。

这也是框架把 knowledge/ 和 Spec 都做成独立文件的原因：文件是持久化的，不会被上下文窗口压缩掉。写在文件里的计划，比聊天记录里的口头约定可靠得多。

编程可能是 AI 产生飞轮效应最直接的领域——AI 辅助编码 → 效率提升 → 更多代码产出 → AI 能力增强 → 更好地辅助编码。这个正向循环已经在发生。

今天某些模型的速度和质量让你觉得勉强够用，半年后可能完全不同。框架的价值在于它能随模型进步而放大收益——当模型从 T1.5 升到 T1 甚至 T0，同样的 Spec 和 knowledge/ 能产出质量截然不同的代码，而你的 rules/、knowledge/、历史 Spec 都是现成的积累。

• Superpowers — agentic skills 框架（HARD-GATE、两阶段 review、systematic-debugging）：https://github.com/obra/superpowers
• Writing about Agentic Engineering Patterns - Simon Willison：https://simonwillison.net/2026/Feb/23/agentic-engineering-patterns/
• Writing code is cheap now - Simon Willison：https://simonwillison.net/guides/agentic-engineering-patterns/code-is-cheap/
• Chatbot Arena Leaderboard (LMSYS)：https://arena.ai/
• opencode 官方文档：https://opencode.ai/docs/
• Claude Code 文档：https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview
• Frederick Brooks,《人月神话》

以下为 code_copilot 框架当前的完整文件内容，可直接复制到项目中使用。项目特定内容（应用名、包名、中间件等）需根据实际情况填充。

 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 自动 commit 3. Commit 必须可编译 4. 禁止自动 push 5. 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. 命名 - 类名：大驼峰，见名知意 - 方法名：小驼峰，动词开头 - 常量：全大写下划线分隔 - 抽象类以 Abstract 或 Base 开头 - 测试类以被测类名开头，Test 结尾 - 禁止拼音、中英混拼命名 2. 异常处理 - 业务异常使用自定义 BizException，携带错误码 - 系统异常向上抛出，由统一异常处理器兜底 - 禁止吞掉异常（空 catch） - catch 中必须记录日志 3. 日志 - Controller 入口打 INFO，含请求关键参数 - 异常打 ERROR，含完整堆栈 - 禁止在日志中打印用户敏感信息 4. 其他 - 写接口必须考虑幂等 - 涉及并发场景必须说明同步策略 - 魔法值必须定义为常量 

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

 --- alwaysApply: false description: "当涉及业务领域特定逻辑时应用本规则" --- # 业务领域约束 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) { } 

• 依赖: 无
• 验收标准: 怎样算完成
• 验证命令（可选）:
• 完成

变更摘要

/apply 全部完成后填写

• 总文件数: X 个文件
• Spec-Plan 偏差记录:
• 遗留问题:

单测 Spec 模板

 markdown # 单测 Spec — 需求名称 > status: propose | apply | done > created: YYYY-MM-DD 0. 测试原则 - Red/Green TDD：测试必须先 Red 再 Green，跳过 Red 的测试无法证明有效 - First Run the Tests：开始前先跑已有测试套件，了解框架和基线 - 展示工作：必须展示 mvn test 实际输出，禁止"测试通过"等无证据声明 1. 测试框架 | 项目 | 值 | |------|-----| | JUnit 版本 | | | Mock 框架 | | | 已有测试数量 | | | 已有测试风格 | | 2. 覆盖范围 P0 — 核心业务逻辑（必须覆盖） # 类名: XxxManagerImpl | 方法 | 场景 | 输入 | Mock 行为 | 预期结果 | |------|------|------|-----------|---------| P1 — 数据访问层 P2 — 入口层/服务层 不测试（明确列出原因） 3. 执行计划 - [ ] Step 1: 运行已有测试套件，确认基线 - [ ] Step 2: 生成 P0 测试 → 确认 Red → 确认 Green - [ ] Step 3: 生成 P1/P2 测试 - [ ] Step 4: 运行完整测试套件，确认覆盖率 

# 变更日志 — 需求名称

> 记录决策、踩坑和知识发现。知识飞轮的输入。

时间线

| 时间 | 阶段 | 事件 | 备注 |

技术决策

| 决策 | 选择 | 放弃的方案 | 原因 |

踩坑记录

| 问题 | 原因 | 解决方案 | 沉淀？ |

知识发现

> 每个 task 后实时记录，/archive 时逐条确认沉淀到 knowledge/

• [ ] 关键词: 描述

Spec-Code 偏差记录

| 偏差点 | Spec 预期 | 实际情况 | 处理方式 |

代码质量备忘

参考文章：https://mp.weixin..com/s/7Lgb3GfgXKI0J9L9e9sq0w