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

将 AI 编码工具接入仓库后，Agent 仍需要系统边界、改动模块、不可违反的业务规则和验证方式等信息，才能稳定交付需求。缺少这些信息时，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 分时，部分任务已具备协作条件，但仍需按薄弱维度补齐；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% 来自单次任务视角；上下文维护影响的是建设成果随时间失效的速度，应单独分配长期预算。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 用于调整标准与上下文。权重还应按业务类型调整：跨服务需求更依赖系统边界和契约，规则密集型需求更依赖领域建模，重构任务更依赖代码结构、测试和架构约束。

按阶段实施仓库改造

下表将改造动作组织为操作流程。存量仓库无需一开始追求 11 个维度全部满分，应先解决定位、理解、实施、验证和维护中的主要缺口。

第 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 走错路径的次数是否下降，产物是否更容易验证，以及多轮运行的结果是否保持可预测。若这些指标没有改善，评分体系不能证明改造有效。