仓库 AI 标准化改造：标准、评估与验证方法

把 AI 编码工具接进仓库，AI 并不会自动获得稳定交付需求的能力。模型需要知道系统边界在哪里、改动应该落在哪个模块、哪些业务规则不可违反，以及改完之后用什么手段验证。缺少这些信息时，Agent 仍然能搜索代码、生成代码，但它选择参考实现、理解领域术语和判断完成条件的过程会带有明显的随机性。

仓库 AI 标准化改造要做的，是把影响 Agent 判断的条件拆成可逐条检查的标准，再用真实任务检验改造是否减少了错误路径、人工返工和结果波动。评估分数衡量的是信息完整度，不能直接当作改造目标。

本文给出一套可独立执行的路径：先定义仓库需要向 AI 提供哪些信息，按统一口径评估缺口，按优先级改造，最后用真实任务验证正确性和稳定性。所有环节的评判标尺只有一个：Agent 能否因此更高质量地交付任务。

AI-Ready 解决的是什么问题

AI 在仓库中完成一个需求，要沿一条任务路径经过五个阶段，每个阶段都有必须回答的问题：

1. 定位：需求属于哪个系统、哪个模块，哪些文件不在改动范围内，沿哪条调用链找到实现位置？
2. 理解：需求中的业务概念、状态约束和禁止行为具体指什么？
3. 实施：参照哪个已有模式落地改动，现有代码能否作为可靠样例？
4. 验证：改动后运行哪些检查，凭什么判断结果达到验收要求？
5. 沉淀：本次经验如何回流到仓库，已有信息如何随代码演进保持有效？

这条任务路径是全文的主线：后文的评估维度、改造动作和实验设计，都围绕五个阶段的信息供给展开。

传统研发依靠开发者的项目经验、口头沟通和历史记忆完成这些判断。Agent 默认拿不到这些背景，只能从当前会话和仓库内容中推断。改造的目标，是把其中可以稳定书写的部分转化为可访问、可验证、可维护的工程资产。

改造要收敛的是结果的随机性，文档数量本身不构成目标。内容过期、路径不明或范围含糊的文档会误导模型，效果可能不如没有文档，后文的注释消融实验给出了直接证据。

这一问题在实际仓库中相当普遍。一次覆盖 上百个内部仓库的批量评估显示，没有任何仓库达到 80 分。换言之，绝大多数仓库目前不具备让 Agent 独立完成常规任务的信息条件，这部分基础工作多数团队都要补。

任务路径上的五个阶段与 11 个评估维度

评估框架沿这条任务路径展开：每个阶段 Agent 要回答的问题，回答质量取决于该阶段的信息供给。11 个评估维度按其所支撑的阶段归类。

有两点需要说明。其一，代码质量（D4 至 D6）不是一个独立阶段，它是实施阶段的输入条件：Agent 会把存量代码当作实现样例，代码的可读性和技术债直接决定实施阶段的产出质量。其二，各阶段不是严格的先后关系，Agent 实际执行中会在定位和理解之间反复跳转；表格描述的是信息起作用的环节，不是执行顺序。

其中跨边界信息主要压在定位和理解两个阶段，也是整条路径上最容易缺失的一环。Agent 只能直接读到当前仓库的代码，仓库之间的连接方式和外部领域的概念对应关系无法从单仓代码推出：前端体现为跨 Bundle、跨仓库的跳转协议和路由约定，后端体现为微服务之间的接口契约和领域知识映射。定位阶段的系统拓扑需要写清本仓库与外部如何连接，理解阶段的领域建模需要覆盖跨微服务的领域知识，否则 Agent 遇到跨仓需求时只能猜测另一端的语义。

评分标准：权重、证据与等级

11 个维度用于批量扫描和形成改造清单，采用 100 分加权评分。下表编号沿用评估体系的原始顺序，所属阶段列标明该维度在任务路径上的作用位置。权重给出两套：先验权重是按 Agent 在陌生仓库中的典型失败模式做出的专家估计，推导权重按下一小节的方法从结果指标反推。以下是一种可落地的评分细则示例：每个维度先按证据评出 0、25、50、75 或 100 分，再乘以权重。单项得分必须能追溯到仓库中的文件、配置、CI 记录或可运行命令，不能只依据评估者的主观判断；具体分档粒度可以按团队自身的评估工具调整，不必与此完全一致。

评分等级可统一解释为：0 分表示没有发现可用证据；25 分表示存在零散材料但无法支持典型任务；50 分表示覆盖主要路径但有明显空白或内容未验证；75 分表示覆盖主要路径且能够在任务中使用；100 分表示覆盖完整、可自动检查，并且维护机制已实际运行。

总分可用于划分改造阶段：低于 50 分为不及格，仓库缺少 Agent 完成常规任务所需的基础信息；50 至 59 分仍属待改进区间，材料零散，不足以支撑完整任务；60 至 79 分为一般，部分任务已具备协作条件，但 Agent 仍会频繁出错，需要按薄弱维度补齐；80 分及以上为优秀，信息、验证和维护机制相对完整。等级不替代任务实验。即使总分较高，验证阶段缺失（D10 很低）的仓库仍不适合让 Agent 在无人工保护的情况下提交改动；定位（D2）或理解（D7）薄弱时，跨模块和规则密集型需求也应优先安排人工复核。

同样是 60 分的两个仓库，可能一个缺领域规则，另一个缺测试入口，它们对不同类型任务的影响并不相同。只追求总分，会引导团队去补齐容易计数的文档，忽略真实任务中的定位、理解和验证问题。

权重如何推导：先定结果指标，再按影响反推

权重不应在设计评分表时直接指定，它应该是推导出来的，且顺序固定：先由任务路径确定维度（上一节已完成），再定义“高质量交付”由哪些可测量的结果指标构成，最后按每个维度对结果指标的影响程度分配权重。维度先于权重，权重来自影响。

第一步，把交付质量拆成四个可测量指标。占比是可调整的假设，反映团队对各项结果的重视程度：

第二步，评估每个维度对四项指标的影响档位。判断依据是机制分析加已有的实验证据：导航直接决定搜索轮次（成本），死代码和相似候选造成实现选择的随机性（稳定性），业务规则缺失造成的错误只能靠人兜底（人工介入）：

第三步，将高、中、低按 3、2、1 取值，按结果指标占比加权并归一化到 100，即得上表中的推导权重。

先验权重的定法值得单独说明。它按 Agent 在陌生仓库中的典型失败模式分配预算：改错位置（定位）、误解业务规则（理解）、模仿错误或过期样例（实施）、无法自证（验证）、经验不回流（沉淀）。与原始评估体系的权重（D7 最高为 14%、D2 仅 6%）相比，本文的先验把文档类维度下调、把代码治理和验证上调，依据是两个判断：Agent 的第一输入是代码而不是文档；文本规则对输出的约束力弱于可执行检查。

推导值与先验值的差异本身值得分析。上升最多的是 D2（9% 到 12%）和 D5（9% 到 12%）：导航同时影响定位正确率和搜索成本，死代码与重复实现同时影响正确性和稳定性。下降最多的是 D7（13% 到 9%）、D10（14% 到 10%）和 D11（8% 到 4%）：D7 的高先验只有在跨仓依赖重的仓库才成立；D10 的先验偏高，是因为它在为无人值守交付的能力定价，而推导矩阵只按单次任务计分，计不进这个门条件作用；D11 对单次任务的四项指标几乎没有直接影响。其余维度的推导值与先验值接近，经验判断和结构化推导在这些维度上互相印证。这个推导方向也与两组消融实验的实测杠杆一致：导航是翻单实验中回报最高的提分项，清理死代码是收益最大的单项治理，领域知识库在单仓任务中边际贡献有限。先验权重、推导权重和实验数据三者方向吻合，说明这套权重可用；不吻合的维度，就是下一轮实验要重点校准的对象。

按阶段聚合后，先验权重的分布为实施 30%、定位 26%、理解 22%、验证 14%、沉淀 8%；推导权重的分布为实施 38%、定位 31%、理解 17%、验证 10%、沉淀 4%。推导相对先验进一步向实施和定位集中，把文档理解和维护机制的份额让了出来。有两点需要补充。其一，D11 的 4% 是单次任务视角的结果；上下文维护的价值体现在时间维度上，决定建设成果的退化速度，应为它分配独立的长期预算，而不是按 4% 理解它的重要性。其二，D7 的影响档位随任务类型波动最大，跨仓需求占比高的仓库应明显上调。另外评分是加法、任务效果是乘法：定位是前置条件，定位出错时后续阶段得分再高也无法挽回，这是线性权重表表达不出来的部分。

维度拆分本身遵循“可检查、可执行”原则：每个维度对应独立的证据来源和治理动作，不追求语义上的纯净分类。有两处边界值得留意。一是 D9 与 D11 在历史案例上存在重叠：D11 是产生案例的机制，D9 是案例的存量可用性，评估时应区分“机制是否存在”和“产物是否足够”。二是 D4 至 D6 沿用了人读代码的质量分类；对 Agent 而言真正起作用的变量是“样例是否会被模仿”和“扩展点是否可见”，保留三分是因为命名治理、耦合治理和扩展点文档是三件不同的工作。

最后，权重不是一次定死的。完整的校准闭环是：先验权重，按结果指标推导，消融实验实测各维度杠杆，再用实测结果更新权重和改造顺序。后文“用消融实验验证改造收益”一节给出实验设计，测出的维度贡献应回流到本节的权重表中；权重表回答的是“什么是完备”，实验回答的是“先改什么”。

定位：先打通进入仓库的导航路径

定位阶段的建设从入口开始：让 Agent 从仓库入口出发，经过尽量少的跳转找到完成任务所需的资料，而不是先写很长的项目说明。

一个仓库级入口文件可以是 AGENTS.md、CLAUDE.md 或团队使用工具对应的规则文件。它应当保持短小，并提供明确路由：

# 仓库协作入口

## 系统边界

- 本仓库负责：订单履约状态编排。
- 不负责：库存扣减、支付结算；这些能力通过下游服务调用。

## 任务路由

| 任务                 | 先阅读                     |
| -------------------- | -------------------------- |
| 理解模块与调用链     | docs/architecture.md       |
| 修改状态机和领域规则 | docs/domain/order-state.md |
| 编码约束             | docs/rules/coding.md       |
| 编写和运行测试       | docs/testing.md            |

## 验证

pnpm typecheck && pnpm test

入口文件承担的是导航职责，不应堆入所有业务知识。导航验收至少包括四项：能说明仓库负责和不负责什么；能路由到架构、领域、规则和测试四类资料；关键资料从入口出发两次跳转以内可到达；路由中的本地路径、命令和链接可自动检查。大仓库可以将局部规则放在子目录，按任务或路径加载；生成代码、构建产物和 vendor 目录也应排除在主要上下文之外。这样能缩短检索路径，也避免 Agent 到不相关模块中寻找参考代码。

导航质量直接决定“在哪改”。在一组翻单任务的对照实验中，信息完整的一组能更快、更稳定地找到正确实现方式；缺少导航和上下文的一组经常从错误案例起步，选中正确实现框架的成功率只有 20% 左右。第一轮清理废弃代码（删除 687 个不再使用的 Java 文件）后，这一成功率提升到约 70%。这说明导航改造和代码治理需要配套进行：入口能把 Agent 带到正确区域的前提，是正确区域没有被大量相似但已失效的实现淹没。

清理也有代价。被删除的历史代码中混有此前翻单需求的实现，信息完整的一组在清理后短期承压，代码采纳率从第一轮的 85% 回落到 60%。单项改造对一个薄弱环节是净收益，也可能扰动另一个已经较好的环节，分数与效果之间不存在单调的线性关系，判断依据应放在多轮迭代的终态结果上，不能只看单轮波动。随后一轮基于接口和抽象类的代码重构把采纳率拉回到 80%；再叠加需求描述、知识库和编码约束的多轮优化后，该场景下信息完整组的采纳率最终稳定在 90% 以上，个别 PR 评审未发现问题，两组的框架选择正确率都接近 100%。走到这一步，实验才算走完整个闭环。

理解：领域知识只记录代码无法表达的部分

理解阶段依赖的主要材料是领域知识库。它常见的误区是把代码已经表达的流程再用自然语言复述一遍。在单仓、边界清晰的任务中，模型从代码结构里就能读出大量信息；重复描述既占用上下文长度，还可能制造互相矛盾的版本。

知识库的增量价值集中在代码本身无法可靠推出的信息上：

• 跨仓或跨服务的调用契约、数据归属和领域边界，例如前端的跨 Bundle 跳转协议与路由约定、后端微服务之间的领域概念对应关系。
• 业务术语、枚举值的业务含义、状态流转和时效约束。
• 无法从类型定义看出的边界条件和例外处理。
• 出于技术或合规原因的禁止行为。
• 关键架构决策的取舍原因，以及历史需求中可复用的实现模式。

例如，PENDING(0) 只说明一个枚举值存在，说明不了它在什么条件下允许迁移、是否允许回退、是否影响下游计费。这类规则应紧贴领域模型或状态机文档维护，并由入口文件路由到对应位置。

编码规范也应尽量转成可执行检查。文本规则适合说明意图和例外，格式化、类型检查、依赖限制、安全扫描和架构边界校验则应进入 CI。否则 Agent 即使读懂了规范，也无法在本地获得足够快、足够确定的反馈。

实施：代码质量也是上下文质量

实施阶段的输入不只是文档，还有存量代码本身：AI 会把它检索到的现有代码当作实现样例。死代码、重复实现、混淆命名和职责不清的模块，会让搜索结果里同时出现多个看似合理的候选路径。模型并不知道哪个版本已经废弃，通常会模仿它检索到的实现，存量代码的质量因此构成生成质量的上限。

因此，AI 标准化改造不能只补说明文件，还需要做与日常工程质量同标准的治理：

• 删除已废弃且不再需要兼容的代码，或清晰标记迁移边界。
• 合并表达同一业务概念的重复实现，减少相似候选。
• 优先修复类、方法和字段的命名，使名称直接表达职责和适用范围。
• 对扩展点、SPI 注册、Builder 配置等结构上不易发现的位置补充导航性说明。
• 清除过期或范围不完整的注释，避免其成为错误的强信号。

最后一条需要展开。一组基于真实合同服务仓库的消融实验，以一次真实需求变更（新增一种费率模式）的影响面分析为任务，覆盖 10 个业务场景、22 个标准修改点，每组独立运行 3 轮。保留全部信息的基线组平均分为 47.0，标准差约为 7.1；移除全部注释的组平均分为 47.5，标准差约为 0.8。这组数据推不出“不要写注释”的结论，注释的价值取决于位置、密度和准确性。

在扩展点隐蔽、逻辑分散的场景，注释可以帮助模型发现注册点和配置位置；在多渠道并存、多条链路并列的场景，某条路径上过细的注释会牵引模型沿该路径持续推理，遗漏注释稀疏但同样需要修改的路径。这一实验中出现过三种具体的负向机制。一是渠道吸附：当某个渠道的注释明显比其他渠道详尽时，模型会被吸附在该渠道的上下文里定位问题，即便真正需要改动的是另一个渠道；去掉注释后，模型转而依靠命名和代码结构，三轮反而都做出了正确判断。二是链路挤占：同一场景下若干条并列实现链路中，注释最完整的一条拿走了大部分注意力，模型沿这条路径推理到底后就误判任务已经完成，漏掉了注释稀疏的并列链路。三是旧类复用倾向：当某个存量类的功能被注释描述得很完整时，模型容易得出“已有逻辑可以复用”的结论，给出扩展旧类而非新建实现的错误方案。高质量的注释应声明能力边界，避免混入其他渠道的历史背景，并让并列链路的说明密度大致对称。

这组实验中，命名消融造成的均分损失是三个信息维度中最大的：混淆命名后，平均得分从 47.0 降到 45.0。拆分子项看，命名消融主要拉低“能否定位到正确位置”的得分，对“能否描述改造语义”影响有限；可以说命名决定模型能走到哪，注释和领域信息影响它到达之后能说出什么。领域知识库在单仓影响面分析中的边际贡献较小，因为模型直接读代码就足以完成定位和语义理解，它的增量价值在单仓代码触及不到的信息上：跨仓交互契约、服务拓扑和跨服务的领域边界划分。三个信息维度同时移除时，均分损失明显大于逐项损失之和，说明名称、代码结构和领域信息之间存在互相印证的关系。全消融组还出现过更极端的表现：在信息极度匮乏时，模型把唯一能确认的一条业务约束反复套用到了几乎所有场景。改造时应保证这几类信息都有最低限度的供给，不要只押注某一种资料。

验证与沉淀：可执行验证与上下文维护

验证阶段的测试标准

验证阶段（D10）的目标是让 Agent 在提交前获得可重复的反馈，而不是只保存一份测试说明。仓库至少应满足以下标准：

• 从干净工作区开始，开发依赖、环境变量样例和启动步骤可定位。
• 入口文件列出快速检查和完整回归两组命令，并说明各自的适用范围。
• 核心业务规则至少有自动化测试覆盖；边界场景、失败路径和兼容性约束不能只留在人工经验中。
• 类型检查、格式化、静态扫描和测试中可自动执行的检查进入 CI；阻断条件应与团队的风险等级对应。
• 需求验收条件可以映射到测试、断言、构建物或明确的人工核对项。

如果 Agent 无法在仓库内运行测试、静态检查或构建，它的输出就只能依赖人工 Review 发现问题。对 AI 协作而言，测试体系除了保障质量，还承担模型反馈接口的职责。

沉淀阶段的上下文维护标准

文档与规则同样会过期。一次性补齐入口文件、领域文档和案例库，只能完成初始建设；代码、接口和业务流程继续变化之后，旧上下文会重新成为干扰。

沉淀阶段的上下文维护（D11）至少需要定义四个要素：触发时机、更新对象、校验方式和责任人。可将下列事件设为触发点：新增或删除模块、接口契约变更、领域状态或术语变更、新增禁止行为、测试命令变化，以及复杂需求交付。每次触发后，应明确更新导航、架构、领域、规则或案例中的哪一项；复杂需求应保存需求、设计、实现和验证证据的对应关系。定期检查入口链接、命令和架构描述是否仍然有效，并为关键仓库指定维护责任人。对可以自动判断的项目，例如链接失效、规则路径变化、文档未覆盖新增模块，可以直接放进 CI。

用消融实验验证改造收益

标准提供改造方向，实验回答“这项改动是否改善了目标任务”。一个基本的验证设计可以分为五步。

1. 选择真实且可评分的任务

任务应覆盖仓库中常见的开发模式，例如新增领域状态、修改跨模块调用链、增加一个扩展实现。将期望修改点、正确调用链和验收条件整理为 Ground Truth，但不要暴露给执行任务的 Agent。

2. 固定输入与执行环境

除待测维度外，模型版本、提示词、任务描述、分支、工具和执行权限尽量保持一致。代码快照一旦生成，应在多轮实验中复用，避免每次运行的仓库状态不同。

3. 构造基线和消融组

可以保留全信息基线组，再按阶段分别移除单项信息，例如定位阶段的导航、理解阶段的领域知识、实施阶段的命名与注释、验证阶段的测试入口；同时设置全消融组观察最低基线。每次只改变一个因素，才有机会将差异归因到该因素。

4. 同时记录正确性和稳定性

不要只看一次运行是否得到高分。至少重复多轮，记录均值、方差、成本和人工修正量。对影响面分析类任务，可以分开评分：

工程使用中，稳定性往往比某次峰值更重要。一个每轮都达到可预期质量的仓库，更适合接入自动化工作流；偶尔得到很高分、偶尔完全走错路径的仓库，则仍需要较强的人工保护。

5. 用 Bad Case 更新标准

实验失败不应只归因为“模型不够聪明”。需要回放 Agent 的搜索、阅读和工具调用路径：它是找错仓库、误选相似实现、缺少业务约束，还是没有可运行的验证命令？将可重复出现的失败转成具体改造项或规则，并在下一轮使用相同任务验证效果。

这会形成一个闭环：评估发现缺口，改造补充信息或清理干扰，实验验证任务结果，Bad Case 反过来调整标准与上下文。标准本身也应允许按业务类型调整权重。跨服务需求更依赖系统边界和契约；规则密集型需求更依赖领域建模；重构任务则更依赖代码结构、测试和架构约束。

改造指南：从普通仓库到 AI 标准化

前文分别回答了“改什么”（五个阶段与 11 个维度）、“权重多少”（推导方法）和“怎么验证”（消融实验）。这一节把改造动作组织成可执行的操作流程。对于大多数存量仓库，不建议一开始追求 11 个维度全部满分，按下面的顺序推进即可；总原则是：先让 Agent 找得到，再让它看得懂，然后让它改得对、证得了，最后让成果不退化。

第 0 步：打分定基线，选定基准任务

先用评分表对仓库打分，记录各维度得分和对应证据；再选取 1 至 2 个高频、有代表性的真实需求作为基准任务，整理期望修改点和验收条件作为 Ground Truth，不暴露给执行任务的 Agent。后续每一项改造的效果都用同一套基准任务衡量，避免凭感觉判断进退。

第 1 步：建立入口与导航（定位）

创建入口文件（AGENTS.md，CLAUDE.md 或工具对应的规则文件），写清系统边界、任务路由表和验证命令，为每个顶层目录写一行职责说明，并排除构建产物和生成代码。路由指向的架构、领域、规则、测试四类资料可以先有骨架再逐步充实。这一步以小时计，是回报最高的单项改造。验收标准：关键资料从入口两跳内可达，链接和命令可自动检查，Agent 用基准任务试跑时能找到正确模块。

第 2 步：清理代码干扰（实施）

删除或隔离废弃代码，合并重复实现，修复高流量路径上的混淆命名，为隐蔽扩展点补导航性注释，清掉过期注释。验收标准：基准任务试跑时，Agent 不再选中已废弃的参考实现。注意清理可能误伤：混在死代码里的历史需求实现要先确认无人依赖；清理后短期指标可能回落，按多轮终态判断。

第 3 步：沉淀代码无法表达的知识（理解）

由领域专家梳理术语表、枚举语义、状态流转、隐含规则和禁止行为，架构文档补充设计意图和关键调用链，跨仓契约单独成章，全部挂到入口路由下。这一步以人周计，是人力最重、也最依赖人的一步；内容可以由 AI 辅助起草，但正确性必须由专家确认。验收标准：只记录代码无法可靠推出的信息，每条规则能定位到对应代码位置，基准任务中 Agent 不再违反已记录的禁止行为。

第 4 步：接入可执行验证（验证）

保证干净环境下一条命令完成构建和测试，把类型检查、格式化、静态扫描和关键测试接入 CI 并设置阻断门禁，把验收条件映射为自动化检查或明确的人工核对项，验证命令写入入口文件。验收标准：Agent 在任务中能自行运行验证并根据失败结果修正，无人工介入时 CI 能拦住已知类别的错误。

第 5 步：建立保鲜机制（沉淀）

定义触发时机（模块增删、契约变更、规则新增、复杂需求交付）、更新对象、校验方式和责任人；可自动检查的项目（死链、路由失效、新增模块未被文档覆盖）放进 CI；复杂需求按需求、设计、实现、验证的对应关系归档为案例。验收标准：触发事件发生后有明确的更新动作，入口文件内容定期核对仍然有效。

第 6 步：用基准任务实验，按结果迭代

按前文“用消融实验验证改造收益”的方法跑基线与消融对照，回放 Bad Case 并归因到具体维度，决定下一项投入；每轮改造后复跑基准任务，比较正确性、稳定性、成本和人工介入四项结果指标。验收标准：基准任务的多轮结果可预期地改善，权重表按实测杠杆更新。

角色分工与常见坑

改造不是纯文档工作：知识梳理依赖领域专家，代码治理依赖仓库 owner，保鲜依赖明确的维护责任人，缺任何一方都会在对应阶段停下来。实验中踩过的几个坑值得提前避开：

• 入口文件一次写得太长太全，反而降低指令遵循率；应保持短小，知识按需分层路由。
• 喂给 Agent 的资料体量过大会被截断，截断后的内容会生成错误的需求理解，进而放大成错误代码。
• 实验前先检查基准分支是否被污染，否则对照结论不成立。
• 单次实验不可信，关键结论至少重复多轮并关注方差。
• 不只看单轮波动：清理误伤造成的短期回落不代表方向错误，按终态判断。

AI-Ready 不是一次性的状态，评分达到某个阈值也不会让仓库就此定型；仓库能否持续向 Agent 提供正确、可定位、可验证的信息，会随代码和需求变化。判断改造是否有效，最终要看具体任务：Agent 走错路径的次数是否下降，产物是否更容易验证，结果是否在多轮运行中保持可预测。这几个指标没有改善，评分体系本身就只是一张需要持续维护的表格。