Knowave

Appearance

AI 友好化改造的意义和终局 ​

整理日期：2026-04-02
来源：学城心得（王龙冲，2026-04-02）+ SDD/TDD 行业研究 + 个人知识库已有积累

一、我们在讨论什么 ​

"AI 友好化改造"这个词，在过去一年里被说了很多次。但大多数时候，它停留在一个相当浅的层次：加 CLAUDE.md、拆大文件、统一命名规范。这些事情是对的，但如果只做到这里，就像给一辆马车装了更好的轮子——方向没有变。

真正的问题是：AI 友好化改造，最终要把软件工程带向哪里？

这篇文章试图回答这个问题。

二、现在的代码仓库缺了什么 ​

现有代码仓库本质上是研发的单一视角切片。它记录了代码逻辑（怎么实现）、技术架构（用什么实现）、变更历史（什么时候改了什么）。但它缺失了三样东西：

为什么这么实现。 一段代码背后的业务决策、当时的约束条件、被否定的方案——这些都不在仓库里。

这段代码对应什么业务。 代码和需求之间存在一条断层。产品知识散落在 PRD（学城/km）、会议纪要、口口相传、研发脑子里，没有任何机制把它们和代码关联起来。

验收标准是什么。 一个功能"做完了"意味着什么？这个问题的答案通常只存在于产品经理的脑子里，或者一个没人维护的测试用例文档里。

这三个缺失，对人类开发者来说是"可以接受的不便"——毕竟可以问人、可以翻历史记录、可以靠经验猜。但对 AI Agent 来说，这是致命的。AI 没有"问人"这个选项，它只能靠仓库里有的东西工作。

三、SDD 和 TDD 在 AI 时代的新含义 ​

软件工程界在 2025-2026 年间出现了一个新共识，可以用一句话概括：在 AI 时代，代码不再是资产，规格（Specification）才是资产。

这个判断背后有一个深刻的逻辑转变。

传统的 TDD（测试驱动开发）要求先写测试，再写代码。它的核心价值是：测试是对"代码应该做什么"的精确描述，而不只是"代码做了什么"的验证。当 AI 来写代码时，这个价值被放大了——AI 需要一个精确的目标，而测试恰好是最精确的目标描述形式之一。

SDD（规格驱动开发，Spec-Driven Development）把这个逻辑推得更远。它说：不只是测试，整个开发流程都应该以规格文档为核心驱动力。规格文档是"单一事实来源"（Single Source of Truth），代码是从规格派生出来的产物，而不是相反。

这两个范式在 AI 时代的新含义是：规格和测试，是人类和 AI 之间的契约。 人类负责定义"做什么"（规格）和"怎么算做对"（测试），AI 负责执行"怎么做"（代码）。这是一个清晰的分工，也是一个可以持续运转的协作模型。

四、文件即上下文：一个关键的设计原则 ​

在 Agent 驱动的开发流程里，有一个原则值得单独拿出来说：上一个 Agent 产生的文件，就是下一个 Agent 的上下文。

这个设计看起来简单，但它解决了一个根本性的工程问题：跨 Agent 的上下文传递。

传统的多 Agent 协作方案，通常需要一个"协调者"来在 Agent 之间传递信息，或者依赖共享内存、消息队列等基础设施。这些方案都有一个共同的脆弱点：信息在传递过程中会失真、丢失、或者因为格式不兼容而无法被下游 Agent 理解。

"文件即上下文"的方案绕开了这个问题。每个 Agent 独立读取分支上的文件，不需要跨 session 传话，不需要协调者，不需要共享内存。文件是持久化的、可审查的、格式固定的——这些特性天然地解决了跨 Agent 协作的可靠性问题。

更重要的是，这个设计让人工卡点变得自然。每个关键节点（PRD 完成、技术方案完成、代码完成）都对应一个文件，人类可以在任何节点介入审查，通过或打回。这不是一个额外的流程设计，而是"文件即上下文"这个原则的自然推论。

五、仓库的职责升级：从代码仓库到知识仓库 ​

把前面几个思路合在一起，可以看到一个清晰的方向：仓库的职责正在从"存代码"升级为"存知识"。

这个升级有三个层次，成本和收益都依次递增：

第一层：关联。 代码里加 @see km链接，建立代码和需求文档之间的索引。AI 可以跨源检索，找到一段代码对应的业务背景。成本低，现在就能做。

第二层：内嵌。 代码注释里直接写业务背景，比 PRD 更精准，因为它就在代码旁边，不会因为 PRD 更新而失同步。这需要培养习惯，但一旦养成，收益是持续的。

第三层：仓库即知识库。 仓库包含 /docs/business/、/docs/product/、/docs/domain/，AI 直接查仓库就能回答"为什么这么实现"。这是 Agent 驱动开发工作流的终态——仓库不只是代码的容器，而是整个项目知识的单一来源。

第三层对应的工作流，大致是这样的：

feature/xxx/
  docs/
    prd.md          ← PRD Agent 产出（需求 + 验收标准）
    tasks.md        ← PRD Agent 产出（任务拆解）
    design.md       ← Dev Agent 产出（技术方案）
    test-report.md  ← QA Agent 产出（测试结果）
  src/              ← Dev Agent 产出（代码实现）
  tests/            ← QA Agent 产出（自动化测试）

需求合入主干时，需求 + 实现 + 测试全部归档，永远可追溯。这不只是对 AI 友好，也是对未来的人类开发者友好——任何人打开这个仓库，都能理解每一个决策的来龙去脉。

六、AI 友好化改造的真正意义 ​

现在可以回答开头的问题了：AI 友好化改造的意义，不只是让 AI 写出更好的代码。

它的更深层意义是：借 AI 的压力，把软件工程的知识管理问题逼到台面上来解决。

软件工程里有一个长期存在的问题：知识的流失。一个系统运行了五年，最初的设计者早已离开，当年的决策理由无从追溯，只剩下代码本身——而代码只告诉你"是什么"，不告诉你"为什么"。这个问题对人类来说是"可以接受的不便"，但对 AI 来说是不可接受的障碍。

AI 的到来，把这个长期被搁置的问题变成了一个紧迫的工程问题。要让 AI 有效工作，就必须把知识显式化、结构化、持久化。而这件事做完之后，受益的不只是 AI，也是所有未来的人类开发者。

这是 AI 友好化改造最深层的价值：它不是为了 AI 而做的，而是借 AI 的压力，把软件工程应该早就做好的事情做好。

七、终局：人负责定义，AI 负责执行 ​

如果把这个方向推到极致，终局是什么样的？

人类的工作重心，从"写代码"转移到"定义规格"。 产品经理、架构师、研发负责人的核心产出，是高质量的规格文档——清晰的需求、精确的验收标准、明确的边界。这些文档是人类和 AI 之间的契约，也是整个开发流程的驱动力。

AI 的工作，是在规格约束下生成代码、测试、文档。 不是自由发挥，而是在人类定义的边界内高效执行。每一行 AI 生成的代码，都能追溯到规格中的具体条款。

仓库成为项目知识的单一来源。 代码、需求、技术方案、测试报告、变更历史——全部在仓库里，全部可追溯，全部可被 AI 检索和理解。

人工卡点保留在关键决策节点。 AI 负责生产，人负责 Review。不是"AI 替代人"，而是"AI 承担执行，人承担判断"。这是一个更合理的分工，也是一个更可持续的协作模型。

这个终局不是遥远的未来。它的每一个组成部分——SDD 工具链、Agent 驱动的开发流程、仓库即知识库的设计——今天都已经有了可用的实践。差的只是把它们连接起来，以及在团队里建立相应的工程文化。

八、如何落地：用评分驱动改造 ​

"AI 友好化改造"最容易陷入的困境是：知道方向，但不知道从哪里下手，也不知道做到什么程度算"够了"。解决这个问题的关键，是把改造目标量化——用一套评分体系，把抽象的"AI 友好"变成可测量的分数。

评分体系的设计逻辑 ​

一套完整的 AI 友好度评分体系，应该覆盖七个通用维度：仓库定位与导航（AI 能否快速理解这是什么项目）、架构文档完整性（AI 能否理解模块分工和数据流）、业务上下文可读性（AI 能否理解业务语义）、代码可读性（AI 能否在有限上下文窗口内理解单个模块）、编码规范与自动化护栏（规范是否被 lint 强制执行）、测试验证（AI 改完代码能否自证正确性）、反馈回路（AI 能否从错误信息中快速定位问题）。

在通用维度之上，还需要针对具体技术栈的专项检查。以 MRN（美团 React Native）为例，专项检查包括：组件结构规范（Props 类型是否紧贴组件）、禁止 Barrel Imports（导入路径是否直达文件）、列表性能规范（是否用 FlashList 替代 ScrollView+map）、样式管理规范（是否用 StyleSheet.create 替代内联样式）、自定义 Hook 抽象（业务逻辑是否从组件中分离）等。

每个检查项采用四档评分（0 / 50 / 75 / 100 分），判断标准明确到可以让 AI 自动执行——比如"统计 500+ 行文件占比"、"grep 统计 any 类型使用次数"、"检查是否存在 barrel index 文件"。这意味着评分本身可以自动化：写一个 Skill，让 AI 扫描仓库、逐项打分、输出体检报告。

分数的意义：AI 协作成熟度分级 ​

分数不只是一个数字，它对应着 AI 在这个仓库里能做什么：

得分率低于 30%（L0），AI 无法参与——缺乏基本文档，AI 连项目是什么都搞不清楚，更别说写代码。

得分率 30%-50%（L1），AI 辅助参与——AI 可以回答简单问题，但复杂任务需要大量人工引导，每次都要重新解释上下文。

得分率 50%-75%（L2），AI 受监督执行——AI 可以完成单个功能开发，但需要人工审查所有输出，偶尔会出现幻觉或不符合规范的代码。

得分率超过 75%（L3），AI 自主迭代——AI 可以独立完成完整功能，通过自动化测试验证，人只需要做最终 Review。

这个分级的价值在于：它给了团队一个清晰的目标。不是"把代码库改造得更好"（这个目标太模糊），而是"把这个仓库从 L1 提升到 L2"（这个目标可以拆解成具体的改进项）。

改造路线图：三阶段渐进推进 ​

有了评分体系，改造路线图就自然清晰了。

第一阶段（1-2 周）：建立文档基础，快速拿分。 这一阶段的核心是"给 AI 一张地图"，成本极低但收益极高。主要工作是：写 CLAUDE.md（覆盖项目是什么、技术栈、目录结构、禁止事项、参考文件、常用命令这六个问题）、在主要功能目录下加 README.md、在 CLAUDE.md 里标注项目里写得最好的参考文件。这三件事通常可以把得分率从 20% 提升到 40%，直接从 L0 跨入 L1。

第二阶段（3-4 周）：建立自动化护栏，让规范有牙齿。 这一阶段的核心是"让 AI 难以犯错"。主要工作是：启用 Linter 并把重要规则设为 error 级别（禁止 barrel imports、禁止内联样式、禁止 ScrollView+map 等）、开启 TypeScript strict 模式、建立快速验证构建（只跑 lint + 单元测试，供 AI Agent 迭代时使用）。这一阶段完成后，AI 生成的代码会自动被 lint 拦截并修正，幻觉率显著下降。

第三阶段（持续迭代）：结构优化，从改动最频繁的模块开始。 这一阶段才涉及代码结构本身的改造。核心原则是：不要专门开一个"AI 友好化"的大项目，而是每次修改一个模块时，顺手把它改造成 AI 友好的形式。优先从改动最频繁的模块开始——这些模块 AI 介入最多，改造收益最大。具体工作包括：拆分 500+ 行的上帝文件、把 Props 类型迁移到紧贴组件的位置、消除 barrel imports、把业务逻辑抽离为自定义 Hook。

评分的另一个价值：让改造可见 ​

评分体系还解决了一个管理问题：AI 友好化改造的进展很难向上汇报，因为它没有直接的业务产出。但如果有分数，就有了可以汇报的指标——"这个月我们把搜索仓库的 AI 友好度从 42 分提升到了 67 分，从 L1 进入了 L2，AI 出码率从 30% 提升到了 55%"。

这不只是管理层面的价值。对团队成员来说，看到分数在提升，是一种具体的正反馈。改造不再是一件"做了也看不出效果"的事，而是每一个改进都能在分数上得到体现。

分数是手段，不是目的。真正的目的是让 AI 在这个仓库里能做更多事情。但有了分数，这个目的就有了一条清晰的路径。

参考来源 ​