【第一篇】AI 编程助手做项目级对接方案Claude Code-设计篇

引入 AI 编码助手之后，团队会立刻撞上三件事。不是"可能会"，是"一定会"。

对接方案要做的，就是把这三类问题变成可配置、可执行、可验证的工程设施。

每一层解决上一层解决不了的问题：

第一层是文档规则——遵守率取决于 AI 有没有读到那一段。

第二层把规则编排成流程——但流程仍可被跳过。

第三层用 hook 强制——跳不过去。

第四层证明前三层确实装上了且没坏。

五个阶段，四道人工确认门，三处机器拦截。

为什么拆解和设计必须分开？

我们最初合成一步，结果产出大量重复内容。因为这是两种思维：

混在一起，AI 会一边列功能点一边设计接口，两边都不完整。

阶段 1.5 是后加的

它解决一个具体问题：如果测试用例在编码之后才设计，测试人员会照着已写好的代码去设计用例——

把用例骨架提到编码之前，用例编号先于代码存在，后面的对账才有基准。

我们最初只有一套完整流程。跑了两周，团队反馈："改个文案也要走六步。"

然后发生的事情完全可以预料——他们开始绕过流程。有人直接改代码不建单，有人建了单但所有确认门一次性全填 yes。

解法是三档分流。判档表自上而下、命中即定档：

第一行是硬闸，不可降档

哪怕是单行改动，碰了认证、权限、数据库结构、对外协议、加密——无条件 A 档。

没这条会出现什么？我们见过这句话：

过滤链是鉴权核心。改错了，整个系统的权限模型就漏了。

B 档的价值不在轻量，在保留接口对齐

B 档砍掉长篇风险分析没问题，但这四项必须保留：接口签名、数据结构、鉴权级别、数据源归属。

原因很实际：四端之间有两条 HTTP 契约和一条加密签名链。任何一端擅自改了字段名或加密方式，联调时才发现，返工成本远超写文档的成本。如果连这四项都砍了，B 档和 C 档没有区别。

流程不能只写在文档里。它需要一个机器能读、人工能签的东西。

每个需求有一个审批状态文件：

三个设计要点：

AI 被禁止写入此文件。它能创建模板，不能改状态——能开单，不能盖章。

两个字段挂着机器闸。「方案确认」不是 yes，调编码 agent 直接被拒；「评审放行」不是 yes，发布说明写不出来。

C 档豁免机器闸，但仍需人工建单——留痕不能省。

三道闸：从"约定"变成"约束"

照抄结构容易，照抄思想难。只抄结构的方案，会在半年内失效。

AI 每次会话能装进上下文的内容有限，且越靠后的内容越容易被忽略。

我们实测反复出现的现象：全局规则文件超过 200 行后，AI 开始漏读后半部分。表现是——你在第 180 行写了一条规则，它照做；挪到第 250 行，它就当没看见。

这不是模型缺陷，是注意力分配的必然结果。方案设计必须承认这个约束，而不是假装它不存在。

做法是按"是否每次都需要"切分：全局池子只留跨模块的硬约束、命令速查、测试纪律；各端细则改成路径触发——编辑 Java 工程时 Java 规则才进上下文，编辑前端时它不占位置。

已在第 04 节展开。这里只留一条判断标准——

文档规则的实际遵守率 ＝ AI 读到那段的概率 × 它当时的判断质量。

两个乘数都不是 100%，乘起来更低。而且这个概率不可观测——你不知道这次它有没有读到，只能从结果反推。

一个必须知道的默认行为

钩子的默认语义是放行：脚本正常退出且没有明确说"拒绝"，流程继续。

所以所有阻断型守卫必须显式拒绝异常输入：输入为空、解析失败、参数非法，一律拒绝。

我们的写入守卫最早在空输入时放行，后来改成拒绝。原因是——

同一个事实散落多处，改一处漏七处。

这是我们花时间最多的问题类型，超过写方案本身。

它为什么特别难防

因为每一处单独看都是对的。

真实案例：一条关于"测试文档目录形态"的规定，散落在 8 个文件里——流程手册、测试 agent 定义、模板注释、新手指南、自检脚本的断言……

第一轮改了 2 处，以为清了。第二轮又发现 3 处。第三轮才清完。

做法：每个事实挑一个权威文件；其余位置只写指针，不复述内容——复制的那一刻，你就创造了第二个真相源；修正错误后，全库反查所有出现点。

AI 会把"看起来对"写得非常像"确实对"，包括它对自己工作的验证报告。

更隐蔽的一种：用例设计了 80 条，跑了 20 条纯逻辑的，剩下 60 条需要环境的归到"人工补验"。然后在总结里写"测试已完成"。没跑的那 60 条，在心理上被当作通过了。

解法是一条纪律 + 两张表。纪律很简单：

关键词是"当前回复内"和"新鲜"——防的是引用几轮之前的旧输出。

为什么两张都要

这是本条最重要的一点。对账表只能保证"文档里的用例都跑了"，防不了"测试设计本身漏了改动点"。

我们有五六个改动点，测试文档从来没有对应用例——对账表永远发现不了，因为它只对账文档里有的东西。这些缺口全靠人偶然实测撞见。

我们有一套自检脚本 + 单元测试，长期"全绿"。

第八轮评审时，有人问了一个问题：

答案是：大部分不会。

测试在跑，测试全绿，但它们没有断言真正关键的行为。绿色只证明测试跑完了，不证明被测对象是对的。

一个具体的假绿

自检脚本里有一条：检查权限配置的"默认模式"字段存在。

问题是——存在不等于正确。有人把这个字段改成"绕过所有权限"，自检照样全绿，而十几条禁止规则全部失效。

修正后的写法是断言"值等于预期值"，不是断言"字段存在"。这类假绿在自检脚本里成片出现过，后来专门做了一轮反向扫描才清完。

四条判据

这条规则成本很高——每条测试要多做一次"改坏再改回"。但它是唯一能证明测试有鉴别力的方法。而且它不只适用于本方案：任何"我们有测试所以有保障"的论断，都该被这个问题检验一遍。

① 什么时候算"可以推广给团队"？

判据是干净检出可复现：从版本库全新检出一份，不带任何本地状态，跑通全套验证。

这条判据挡住过一次真实事故：工作区里方案跑得好好的，但有 3 个文件从未提交。干净检出后——接线在、闸不在，所有审批调用静默通过。

② 什么时候算"方案有问题"？

③ 这套东西的天花板在哪？

权限限制挡不住的部分——子进程、动态拼接命令、换 shell、主会话直改——是结构性边界，靠加规则解决不了。要突破需要组织级策略管控或隔离执行环境，那是独立立项。写明了，团队知道哪里还需要人工兜底；不写明，所有人都以为已经安全了。

合计约 4 周达到可用状态。

但这只是第一版——我们后续用了两个多月做十轮全量评审，才达到可发布状态。

四端异构 · SVN 主线 · 三个月 · 十轮全量评审

下一篇：搭建手册与配置实样