Agentic-SDD：给 Claude Code Agent 一套真正的工程流程

让 AI 编码代理去「修个 bug」，它确实会修——但通常只修最表层、它最先打开的那个文件里的 bug。它很少停下来问：这个修改是否真的解决了需求？同一个调用方是否也有同样的问题？评审人会不会真的签字通过？

这与其说是模型能力问题，不如说是流程缺失：人类不会跳过设计和评审，不是因为我们在当下更聪明，而是因为没人把这种纪律固化进循环里。

Agentic-SDD 是一个 Claude Code 插件，试图把这种纪律固化进去——一条六阶段流水线（require → plan → analyze → implement → verify → fix），由磁盘上的持久化状态文件而非对话记忆来把关，背后是 18 个专业 Agent 组成的阵容，并自带知识检索引擎，不依赖任何其他插件就能把决策建立在你的真实代码库之上。

仓库地址：github.com/MallikarjunHt/agentic-sdd

核心思路：六个带门禁的阶段，而不是聊天循环

一次 /sdd.require <feature-id> 调用不只是写代码，它会让一个真实功能走完：

1. Require（需求）。业务分析师 Agent 把原始工单/请求转成 1-spec.md——问题、建议方案、明确的非目标、风险，以及 Given/When/Then 形式的验收标准。你必须先批准，后续才会发生。
2. Plan（计划）。架构师 Agent 把已批准的规格转成 2-plan.md 和 3-tasks.md——具体的完成定义（DoD）、文件映射，以及带编号的任务列表；每个任务都会从 12 个专业角色（Java、Angular、React、Python、UI、DevOps、QA、BA、DBA、Security、Architect、Senior Dev）中按触发关键词打分，推荐一个负责人。这一步同样需要你批准。
3. Analyze（分析）。专门的差距分析 Agent 会在写第一行代码之前，把计划对照规格的验收标准以及真实的当前代码库做检查。CRITICAL 级别的发现会阻塞进度，直到被解决或被显式移出范围。
4. Implement（实现）。每个任务由路由到的专家实现，并按该任务自身的复杂度打分选择模型档位（便宜/中等/昂贵）——一行配置改动不需要和跨切面重构用同一个模型。
5. Verify（验证）。三个独立 Agent 分别检查宪法一致性、质量/安全、测试充分性；再加第四个专职「魔鬼代言人」，它唯一的职责就是找出清单式评审在结构上抓不到的东西：并发、迁移/回滚风险、向后兼容性。PASS 会提出一份活文档 diff，走正常 PR 评审，绝不静默提交。
6. Fix（修复）。如果验证失败，修复 Agent 只有三次尝试机会，之后必须停下来建议修改计划，而不是无限循环——这是真正的熔断器，不是无限重试。

require 之后的每个阶段都会按功能读写 status.json，因此崩溃的会话可以恢复而不是重来，阶段也真正无法乱序执行。这一个设计选择——用文件作为门禁，而不是靠模型自己判断「我是不是已经做过了」——承担了这里大部分的可靠性。

Profile 系统：一个插件，适配任意仓库

/sdd.init 不会硬编码某一种技术栈的约定，而是基于那个具体目标仓库的真实约定写出 specs/constitution.md——构建工具、测试框架、lint 命令、禁止/必须的模式——而不是通用教科书标准。当仓库自身检测到的配置与宪法文件冲突时，仓库配置永远优先。一次安装，多个目标仓库，每个都被如实呈现。

我差点做错的部分：知识 grounding

最初的设计是让每个阶段的「收集上下文」步骤调用一个 MCP 工具契约——任何暴露 knowledge_search 形状工具名的服务器都可以接入。干净、解耦，但对真正的目标来说是错的：如果有人卸载了提供该工具的服务器，插件就失去了一个它本应始终具备的能力。

所以我把真正的搜索引擎 vendor 进了插件——一个基于 Lucene 的小型 Java CLI，BM25 全文检索，可选 ONNX 向量嵌入升级——放在自己重命名的包下，不留下任何来源痕迹。以下是真实操作（而非假设）中得到的几点教训：

• 我差点提交一个 150MB 的 jar。 GitHub 拒绝单文件超过 100MB 的推送。回头看修复方法很明显：vendor 源码（几百 KB），首次使用时用 Maven 在本地构建 jar，并把构建产物加入 gitignore。插件仓库保持小巧，二进制每台机器只构建一次。
• 嵌入模型是设计上可选，而不是偶然可选。 完整语义检索需要一个约 90MB 的 ONNX 模型，我也不想默认发布它。引擎本身已有干净的降级路径——不 vendor 模型就只用 BM25，并由它自己的 doctor 命令如实报告——所以默认安装就是……能用，仅词法检索，向量检索作为可选的后续升级。
• 相对默认路径是个陷阱。 CLI 的 --index-dir 和 --models-dir 默认是相对当前工作目录的路径。我之前已经见过这类 bug（工具静默报告「没有嵌入模型」，其实只是因为从错误的工作目录调用，而不是模型真的缺失）——所以插件内部每次调用都传绝对路径。很无聊，但这就是「在我机器上能跑」和「能跑」的区别。

用证据说话，而不是推销

我在一个生产级 Java/npm monorepo 中，针对一个真实的 Dependabot CVE 告警跑完了整条流水线——一个传递依赖 yaml 在深层嵌套输入下存在栈溢出漏洞。六个阶段全部真实执行：规格捕获了真实的 CVE 和受影响的 manifest；计划把它限定为一行 npm override（无功能变更，符合纯依赖修复所需的纪律）；分析确认 yaml 是传递依赖而非直接依赖（所以 override 才是正确机制，而不是直接升级）；实现正确地重新生成 lockfile，而不是手工编辑；验证确认解析出的版本确实脱离了受影响范围——直接来自重新生成的 lockfile，因为当天环境的漏洞源代理不可达。两次真实提交，没有编造，没有静默跳过。

已知的缺口

直说，因为一个隐藏自身局限的工具比一个坦承局限的工具更糟：

• 插件自身的提示词/模板没有自动化验证——markdown 指令文件没有编译器。一次改动只能靠对真实功能跑一遍来证明，而不是靠测试套件。
• 没有跨仓库协调——每次安装通过自己的配置针对一个仓库。跨两个仓库的功能需要两次独立、手动协调的运行。
• wiki 镜像功能（按阶段同步页面到 Confluence 或类似系统）是唯一仍依赖外部 MCP 服务器连接的能力，未连接时降级为「仅本地产物」——这是刻意的，因为 wiki 是真正的外部系统，不是插件应该 vendor 一份副本的东西。

如果你也在构建类似的东西——或者只是厌倦了看着 Agent 自信地修错东西——仓库已开源，MIT 许可，这条流水线的设计初衷就是让人阅读，而不只是运行：github.com/MallikarjunHt/agentic-sdd。