引言

最近加入了一个新项目，它有一个巨大的前端，会按照一定规则，把请求转发到老系统和新系统。我需要实现一个功能：当客户重新激活某条广告时，把这条广告迁移到新系统。

AI 帮我分析并实现了这个功能——但它实现的地方，是老系统的老页面。而以前的团队其实已经在前端搭好了新的迁移流程。

AI 为什么选错？因为它只看到了老系统的渲染页面，看不到前置做路由的前端代码——而且它们根本不在同一个代码库。

作为新人、作为新团队，我们没有发现问题。直到部署上线，才发现迁移根本不工作。我们花了一整周，排查原因、梳理迁移流程，才搞清新老系统和前端三者之间是怎么交互的——一共涉及三个代码库：前端负责路由，老系统前后端都有，新系统只有后端，每个库都是几百万行代码。

这不是 AI 的问题——AI 不是不会写这段代码，它只是不知道"迁移该走新流程"。它缺的不是写代码的能力，而是"在哪里做"的知识——这正是在复杂系统中的生存指南。

大多数 AI 编码的最佳实践都基于一个隐含假设：你在一个相对干净的代码库上工作。但在这类复杂系统中，这个假设不成立——隐式依赖、特殊逻辑、dead code 里的活逻辑，这些才是复杂系统的日常。

本文的思路是：不要把 AI 当作自由发挥的编码助手，而要把复杂系统生存指南写进它的上下文里。生存指南，就是把我们在复杂系统中积累的生存经验，组织成 AI 可以直接使用的上下文。让 AI 的独特能力——阅读速度快、全局记忆强、严格执行规则不疲劳——为这些指南服务。

但一个人会写生存指南还不够。更大的挑战是：如何让整个团队共享这些生存指南，并且在实践中持续进化它们？ Senior 的经验如何变成团队资产？新人如何快速获得复杂系统上下文？团队踩过的坑如何保证不再重蹈覆辙？

以下是我从真实项目中总结的一套完整框架——从个人上下文到团队上下文的循环。它包括五层方法论（知识层 / 技能层 / 规则层 / 验证层 / 进化层）。

回头看开头那个事故，它恰好同时缺了两个层面：AI 不知道"迁移该走新流程"，缺的是知识层；没有先勘探、先确认方案再动手、也没有人在上线前把关，缺的是验证层——AI 和人如何协同、人在哪里把关。这套框架，正是为堵住这些缺口而设计的。

五层之中，进化层正是连接个人与团队的关键机制——它让个人经验沉淀为团队资产，让 AI 在复杂系统中越用越好，而不是越用越乱。也正因为进化层让 AI 越来越可靠，验证层的形态才会随之演进——人从"在回路中逐点把关"，逐渐走向"在回路上方决定边界"。

复杂系统：AI 编码的挑战与独特优势

常规 AI 编码的隐含假设

主流 AI 编码实践大多默认你在一个相对干净的代码库上工作——这句话里藏着三个前提：接口明确、模块边界清晰、测试覆盖足够——它们共同保证：AI 自由生成代码的风险可控，错了大不了回滚，影响范围有限。

逐一拆开看，这三个前提每一个都依赖代码库的"干净"：

• 接口明确：AI 只需要对着签名写实现，不需要揣测调用方的约定和隐式依赖

• 模块边界清晰：改动被隔离在一个模块内，不会沿着未知的调用链波及到别处

• 测试覆盖足够：AI 改错了能被测试拦下来，而不是部署上线后才发现

下面会看到，在复杂系统中，这三个前提一个都不成立。

复杂系统的现实

但真正落到复杂系统上，情况完全不同。还记得开头那个前端吗？一个请求要穿过三个代码库——前端负责路由，老系统前后端都有，新系统只有后端——每个库都有几百万行代码。复杂系统之所以棘手，不只是"代码写得烂"，更是它让你在做任何修改时都陷入一个三重困境：

困境一：无法通过增量修改实现新功能

你的新需求其实不复杂——加一个支付渠道、支持一种新的订单类型、增加一个配置项。按道理，这种增量修改应该很安全。

但复杂系统不给你这个选项：

• 类似的业务散落在各处，实现方式各不相同。 你想参考已有的实现来写新功能，结果发现 A 模块用一种方式、B 模块用另一种、C 模块又是一种——你不知道哪一种是当前团队认同的"正确演进方向"。更糟的是，它们可能都是对的，只是适用场景不同，而没人说得清场景划分。

• 现有逻辑和新增功能直接冲突。 你想加一个新支付渠道，但现有的支付路由逻辑里 hardcode 了渠道列表，且分布在三个文件里、用着不同的判断条件。你加了第四种渠道，然后发现系统在特定条件下走了错误的渠道——因为某个老的条件分支没有覆盖到新渠道。

• 现有逻辑本质上不可扩展。 函数签名没有预留扩展点，配置结构没有设计灵活度，数据库表设计假设了"永远只有三种状态"。你加一个功能，不是在已有框架上"填空"，而是在和既有框架"打架"——改完这里发现那里不兼容，修完那里发现另一处也受影响。

困境二：添加逻辑分支工作量小，但无法判断影响范围

增量修改走不通时，最直接的应对方式就是加条件分支——"如果新渠道就走新逻辑，否则走老逻辑"。这是工作量最小的方案，加一两行代码的事。

但风险在于：你无法判断这一两行代码的影响范围。

• 逻辑复杂，没有明显边界。 代码模块之间的依赖不是通过接口，而是通过共享的可变状态、全局配置、隐式的调用链。你的新分支可能会被某个上游模块在特定条件下触发，而写代码的人根本不知道这个上游的存在。

• 分支叠加分支，逻辑回路越来越复杂。 复杂系统中的代码逻辑往往不是线性的，而是多个条件分支相互叠加的结果——"如果 A 且 B 就走 X，如果 A 且不 B 且 C 就走 Y，如果……"。每加一个新分支，组合数就翻一倍，最终没人能说清所有路径覆盖了什么场景。

• 测试覆盖不到现实。 复杂系统中的测试通常以集成测试或手工测试为主，单元测试覆盖率极低。你加了一个分支，现有测试全绿，但那是"测试通过"，不是"没有副作用"。副作用往往体现在测试没覆盖到的边缘场景里。

困境三：重构工作量大，且更加无法判断影响范围

既然增量修改走不通、加分支风险高，那不如重构吧——把混乱的部分理清楚，再基于干净的代码加新功能。

但重构在复杂系统中是一个更大的陷阱：

• 重构的工作量远超预期。 你想把一段耦合的逻辑解耦，结果发现它依赖了十几个模块。你想"只解耦核心逻辑"，但复杂系统中的耦合不是局部的——你动一个点，牵出一张网。

• 重构后的影响范围更加不可判断。 增量修改至少还能说"我只改了这一个文件"，心里有个大概的影响范围。重构不同——你重新组织了模块边界、提取了公共逻辑、改变了调用链。重构完，你心里完全没底——"我是不是漏了某个隐式依赖？新结构的测试覆盖到了所有旧场景吗？"

• 理解成本本身就超过了重构收益。 要重构一段代码，你首先得完全理解它。但在复杂系统中，理解一段"看似简单"的代码可能需要追踪层叠的条件分支、隐式的全局状态、跨模块的调用链——理解所花的时间，可能已经超过了"用老代码加分支凑合用"的时间。更何况，理解完了你还不一定有信心重构对。

三重困境的本质：决策瘫痪

这三重困境不是三个独立的问题，它们背后有一个共同的根源：复杂系统把开发变成了一场决策的噩梦。

回到干净的代码库上修改一个功能是什么体验？决策很轻——接口签名是明确的，模块边界是清晰的，调用链是可追溯的，测试覆盖率给了你改动的信心。你只需要对一个点做判断："这个实现方式对不对？"

但在复杂系统中，一个简单的修改会打开密密麻麻的决策点：

• "这条路能不能走通？" — 我打算做增量修改，但现有代码绑死了接口。我应该改接口还是绕过接口？改接口会影响多少调用方？绕过接口会引入技术债到什么时候能还？

• "这样改安不安全？" — 加一个 else if 分支，成本极低。但有没有一个隐式依赖会因为这个分支而出现问题？是不是有一个模块在特定条件下依赖于旧分支的行为？

• "值不值得重构？" — 这块代码太烂了，但重构的工作量预估不出来——这里的耦合到底有多深？重构到 60% 发现还有隐藏依赖怎么办？

• "这条路会不会封死未来的路？" — 今天我选择加分支来快速交付，但明天需求再叠加一层时，这个决策会不会让改造成本翻倍？如果我今天选择重构，未来的人会感激我还是骂我过度设计？

• "我怎么知道我的假设是对的？" — 我觉得这样改是安全的，但我的判断是基于我对代码的理解，而我的理解可能不完整。那些我没读过的代码里，有没有一个逻辑会让我的方案失效？

这些不是抽象的问题——它们是你在写每一行代码时都在面对的微观决策。一个架构良好的代码库上，一次修改只需要做1-2个关键决策（"接口怎么设计"、"数据存在哪"）。在复杂系统中，一次修改可能要做十几个甚至几十个这样的微观决策。每个决策看起来都很小，但加在一起，就构成了决策疲劳——你才做了一半的决策就已精疲力尽，开始凭直觉做判断，然后出错。

更糟糕的是，这些决策有几个共同的特征，让它们本质上就很困难：

1. 信息不对称 — 你永远不知道是否掌握了做对决策所需的全部信息。复杂系统中的隐式依赖、特殊逻辑、未文档化的行为，让你只能基于"我看到的这些代码"来猜测——而不是像干净代码库那样，可以基于接口和类型系统来推理。你不知道你不知道什么。

2. 决策的不可逆性不对称 — "做错一个决定"的代价远大于"不做决定"。干净代码库里错了可以回滚——有测试兜底、有 CI 拦截；复杂系统里，一个错误决策可能在几周后才暴露（某个罕见的条件分支被触发了），而因为你同时做了十几个决策，甚至无法定位是哪一个出了问题。这种不可逆性让你倾向于"什么都不做"。

3. 缺乏决策框架 — 干净代码库有明确的架构原则，遇到问题可以"按照分层架构，这个逻辑放在 Service 层"；复杂系统中没有框架，每次决策都是 case by case 的权衡——同一个问题，今天选 A、明天选 B，取决于当天值班的人是谁。这条路没有路标，往哪拐全凭当天的司机。

4. 决策点的连锁反应 — 复杂系统中的决策不是孤立的：加一个 if-else，会影响未来十个决策的选项空间；选择重构，会影响几十个模块。每个决策都打开或关闭了未来的决策路径，而在信息不足时，你无法预判现在做的决定会封死哪些路。

这三个困境——增量修改走不通、加分支影响不可知、重构风险更高——都是这些根本因素的具体体现。它们构成了一个死循环：

代码就是在这样的循环中一天天变烂的。你每次的选择都在"风险小但会让系统更臭"和"风险大但能让系统变好"之间摇摆——而大多数时候，你会选择风险小的那个。这不能怪你。在信息不足、决策点过多、且没有决策框架的情况下，保守是理性的选择。

那么，把这个难题直接丢给 AI——让它自由发挥，会怎样？下面先看三种典型的失败模式。

AI 自由发挥的三种典型失败模式

在复杂系统中让 AI 自由发挥，通常会出现三种失败模式：

模式一："先上线再后悔"

1. AI 自信地给出一个方案，看起来合理，但基于错误的假设（比如忽略了某个隐式依赖）

2. 程序员贸然接受，因为代码量太大看不全上下文

3. 部署后出问题——某个边界场景没覆盖到，或者某个已有功能被意外破坏了

4. 回退、修复、浪费更多时间——比人手工做还慢

开头的翻车故事正是这种模式的现实版：AI 自信地给出了迁移方案，却不知道前端早已有一条新的迁移流程；作为新人的我们因为看不全上下文而接受了方案；上线后迁移根本不工作，我们花了一整周排查和梳理流程。

模式二："反复调试到放弃"

1. AI 给出一个方案，程序员测试发现问题

2. 程序员把问题描述给 AI，要求修改，AI 修改后再测——还是有别的问题

3. 如此反复多轮——改了一个 bug 引出另一个 bug，修了边缘情况忘了主流程，AI 每次修改都是"打地鼠"，没有从根本上修正错误的假设

4. 程序员最终放弃，自己动手从头开始解决问题

模式二比模式一更隐蔽，也更消耗精力。模式一至少是一次性的痛苦——出问题、回退、重新来过。模式二是持续的痛苦——你觉得"再给 AI 一次机会就能好"，但结果每次都让你失望。

模式二的本质是跳过根因分析、直接修症状——从头到尾没有人停下来问"为什么会这样"。正确的补救不是继续让 AI 改代码，而是先停下来做一次根因分析——复现问题、沿调用链反向追踪、区分症状与根因，找到真正的病根后再让 AI 动手。这个顺序反了，模式二就会无限循环。

模式三："团队踩过的坑持续被踩"

1. 团队里有人已经解决过某个问题——也许是另一个程序员之前踩过一个坑，花了不少时间找到了正确的解法。但这段经验只存在于那个人的脑子里，或者只存在于那条对话记录里。

2. AI 遇到类似场景时，仍然在犯同样的错误——因为 AI 不知道"有人已经踩过这个坑了"。它没有从团队的集体经验中学习，每次都是"新人"的状态。

3. 不同成员反复浪费精力纠正同样的问题——A 纠正过了，B 不知道，C 也不知道。每个人都在重新发现和解决同一个问题，团队没有因为上次的教训而变得更强。

4. 持续的"对齐拉通"成本——团队中发现一个共性问题，需要开会对齐、写文档、通知所有人——每次都要额外消耗精力来确保知识不被丢失。

模式三与前两种不同——它不是一次对话中的失败，而是团队层面的知识断层。一个人和一个 AI 的对话出了问题，最多浪费一个人的时间。但团队踩过的坑持续被 AI 踩，意味着整个团队的知识积累机制出了问题。每一次重复踩坑，都是对团队效率的一次慢性消耗。

三种模式表面不同，但根因归结为两个层面：

个人层面：AI 缺乏复杂系统生存指南——它不知道什么时候该问、什么时候该停、什么可以碰、什么不能碰。

团队层面：团队缺乏知识循环机制——个人经验的沉淀、团队共识的固化、AI 行为的一致性，没有一个系统来保障。

这两个根因分别对应后文框架的不同层面——个人层面的"AI 缺乏生存指南"，由知识层、技能层、规则层解决（让它知道什么、会做什么、何时该做什么）；团队层面的"缺乏知识循环机制"，由进化层解决（让个人经验沉淀为团队资产）。至于验证层，则是另一条线索：无论 AI 多强，人在关键节点的把关都不可少。

AI 在复杂系统上的独特优势

但正因为复杂系统如此棘手，AI 的某些能力反而变得格外有价值：

这些能力的价值只有在配上正确的上下文时才得以发挥。AI 跑得快，但如果方向错了，跑得越快破坏越大。 上下文就是方向。

回头看前面的三重困境，这些能力恰好逐一对症：阅读速度 + 全局记忆 缓解"信息不对称"，严格执行规则 压缩"决策点过多"的选项空间，多方案并行评估 直接对症"缺乏决策框架"——AI 一次性生成多个候选方案并对比评估，本质就是在为一次决策搭建判断框架，结构化输出 则把零散判断沉淀成可审查的决策材料。至于决策的不可逆性不对称和决策点的连锁反应，单靠 AI 的能力化解不了——前者要靠验证层的人在关键节点把关、规则层的可回退原则兜底，后者要靠规则层的最小改动与单次职责压缩连锁半径。决策瘫痪正是这些根源叠加的结果，由"严格执行规则（约束选项空间）+ 多方案并行评估（提供判断框架）"共同缓解。

以「多方案并行评估」为例，它最典型的落地场景是 ADR（Architecture Decision Record）的生成——ADR 本身就要求列出多种候选方案并逐一评估。但多方案评估不是替人做决策——它只是压缩了决策空间，最终的选择权仍握在验证层「确定方案」阶段的人手上。

三种失败模式与这些独特优势放在一起，正好回答了那个更根本的问题：如果复杂系统的问题本质上是决策困难——信息不足、决策点过多、缺乏框架——那么 AI 能不能帮上忙？ 直觉上不能——三种失败模式已经证明，把决策交给一个同样不了解系统的 AI，只会错上加错。但答案恰恰相反：AI 的这些独特能力，天生就是困境的对症药，前提是它被规则约束、被引导方向，而不是自由发挥。这剂药怎么配、怎么用，正是下一章方法论框架要回答的。

方法论框架：五层体系

在回答"怎么写上下文"之前，先往深一层问：我们到底需要 AI 具备什么？

让 AI 在复杂系统上安全地编码，不是随便写一些上下文就够了。一份真正有用的上下文需要经过设计：它需要知道"是什么"（知识）、知道"怎么做"（技能）、知道"什么时候该做什么"（规则），还需要人和 AI 按正确的步骤协同，在关键节点验证 AI 的输出是否安全（验证），并且每次修改后能学到新东西（进化）。

我们把答案拆成了五个层面，从基础到上层依次展开：

前三个层面（知识、技能、规则）定义了 AI 的内在能力——它知道什么、会做什么、怎么决策。第四个层面（验证）定义了 AI 和人的协同与验证方式——Human in the Loop。最后一个层面（进化）让整个体系能够自我更新——它推动整个系统从"Human in the Loop"走向"Human on the Loop"，但最终判断权始终留在人手上。

这五层合起来，就是我们写给 AI 的那份生存指南——它最终以上下文的形式进入 AI：知识是它对系统的认知，技能是它的操作手册，规则是它的决策依据，验证是人的安全护栏，进化让这份指南永远跟得上系统。

下面逐层展开。其中，验证层与进化层如何共同推动"从 Human in the Loop 走向 Human on the Loop"的演进，将在最后一章专门对比展开。

知识层：AI 需要知道什么

先厘清三个术语：系统指代码库对应的软件系统（如开头的"老系统""新系统"）；系统代码库指某个系统的代码仓库——前端、老系统、新系统各有自己的系统代码库；项目指团队当前正在推进的特定工作举措（如一次系统迁移、一次架构现代化）。相应地，系统知识是关于系统的知识，项目知识是关于当前项目的知识——两类知识各自的构成与生命周期差异，正是本章接下来要展开的核心。

在让 AI 做事之前，先得让它知道足够多的背景信息。知识层回答的是 What / When / Where / Why 的问题，可以简称为 "是什么"：系统里有哪些模块、业务规则是什么、架构是怎么组织的、哪些地方埋着已知的坑，以及——尤其关键的——代码在什么时间、什么条件下会触发什么逻辑、这段逻辑在哪里、为什么是这么设计的。

但知识层里的 When（什么时间 / 什么条件）是事实层面的记录，不是决策——它只描述代码在什么条件下会走什么逻辑，不评判、不选择。至于"在什么条件下应该用什么技能、走哪条路径"的决策，是规则层的职责；"具体怎么做"则是技能层的执行职责——两者的边界都将在对应章节展开。

知识层的内容通常写在 Claude 的项目说明文件 CLAUDE.md、Agent 提示词、Skill 定义中，或者通过 MCP 工具连接的外部知识库中供 AI 按需检索。这些内容的存放位置遵循一条简单的边界规则：只把明确属于该系统代码库独有上下文的知识（系统内架构、编码规范、技术栈版本、坑史）放进该系统代码库的 CLAUDE.md 和 .claude/ 目录中；跨系统的架构知识、业务知识和项目策略等不属于任何单一系统代码库的，都放到工作区根目录。

知识的类型

从团队实践来看，AI 需要的知识可以按来源和稳定性分为两大类、四个层次。

第一类：系统知识

这一类知识是客观存在的——它们要么已记录在某个可靠载体（文档、代码、配置）中，要么需要通过持续发现来揭示。它们有明确的 Source of Truth，不因项目不同而改变其真实性。

业务知识：业务流程、业务规则、领域概念、特殊逻辑的含义。AI 不知道这些，就无法区分"这是 bug 还是业务要求"，也无法判断一个功能"应该接入哪条流程、不该碰哪条流程"。业务知识属于跨系统代码库的领域上下文，即使体现在某个系统代码库的代码中，也不属于任何单一系统代码库 → 存于工作区根目录的 CLAUDE.md。

架构知识：跨系统的架构设计——系统间依赖关系、部署架构、技术选型原则，相当于 C4 模型中的 C1（系统上下文）和 C2（容器）。AI 不知道这些，就无法判断"这个系统依赖哪个上游"、"部署架构是否允许新增服务"——开头翻车故事正是缺失这类知识的典型：AI 只看到了老系统的渲染页面，看不到前置做路由的前端代码；"请求由哪个系统负责路由、迁移该发生在哪个系统"横跨前端、老系统、新系统三个代码库，属于典型的跨系统架构知识。这类决策本身独立记录在 ADR/Wiki 中，工作区根目录的 CLAUDE.md 只负责引用，不重复记录。

系统代码库知识：绑定在单个系统代码库上的全部上下文，包括：

• 系统内架构——模块划分、分层结构、核心数据流，相当于 C4 模型中的 C3（组件）和 C4（代码）。AI 不知道这些，就无法判断"新功能应该放在哪个模块"、"修改这个函数会影响哪些调用方"——比如 AI 可能把本该走 Controller → Service 分层的接口逻辑直接堆进 Repository，或把新功能塞进职责无关的老模块

• 编码规范、命名惯例、测试策略——AI 不知道这些，生成的代码风格各异、无法融入已有代码库

• 技术栈版本和已知限制——AI 不知道这些，可能生成不兼容或过时的代码

• 坑史——哪些模块曾经出过事、哪些修改风险高、哪些模式已被验证不可行。AI 不知道这些，就会重复踩坑——这正是第三种失败模式的根源

这些系统代码库知识都属于该系统代码库独有，存于该系统代码库的 CLAUDE.md 和 .claude/ 目录，随版本管理，每个 clone 系统代码库的人自动获得。

这三类知识有一个共同特征：无论 AI 用不用、团队记不记得，它们就在那里。 业务规则不会因为没人知道就变成 bug，架构依赖不会因为没人记录就消失，系统代码库里的坑不会因为没人踩就不存在。团队的工作是持续发现、准确记录，而不是创造它们。

第二类：项目知识

第二类知识与第一类有本质不同——它不是"客观存在等你去发现"的，而是为达成某个阶段性目标而主动建构的。

项目知识：针对当前团队正在推进的特定工作或举措的知识体系，例如老旧系统迁移、架构现代化、大规模重构、依赖升级、依赖迁移等。这类知识包括：

• 该工作要达成的目标和验收标准

• 该工作采用的策略和路线图（如"先剥离模块 A 和 B，再替换中间件 C"）

• 该工作对系统知识的重新组织和优先级排序——同一个系统，在"性能优化"和"安全合规"两种项目下，需要关注的知识点完全不同

• 工作过程中积累的临时性决策和实验结论

项目知识有两个与系统知识截然不同的特征：

第一，它是迭代建构的，而非一次性准备好的。 项目启动时，我们能提前准备的项目知识是有限的——大方向和大策略可以先定下来，但大量具体的决策依赖在执行过程中逐层展开。随着工作推进，微决策不断累积，原有的策略可能需要修正、补充甚至推翻。项目知识的更新是通过进化层来完成的——同样，在项目的执行过程中，系统知识也可能被修正：发现新的业务规则、纠正架构误解、补充坑史。这正是前文讨论的微决策问题的自然延伸：决策点越多，知识需要的调整就越频繁。

第二，它是可卸载的。 项目结束后，这套知识体系的使命就完成了。它应该被归档（供未来类似项目参考），而非继续占据 AI 的上下文空间。下一个项目有自己的目标、策略和路线图，需要加载一套全新的项目知识。如果说系统知识是"永久内存"，那项目知识就是"工作内存"——项目启动时加载，运行中持续刷新，结束时卸载。

在实践中，项目知识的载体是工作区根目录下的 CLAUDE.md、.claude 等文件（即 Claude 的项目说明、Agent 提示词、Skill 和 Rule 文件），以及 mcp.json 中配置的 MCP 工具。每个项目对应一个独立的工作区，其生命周期如下：

• 加载：为新项目创建新的工作区，先写好 CLAUDE.md 说明该工作的上下文和策略，再配置 agents/、skills/、rules/ 等子目录，并设置 mcp.json 连接所需的知识库

• 运行中更新：随着工作推进，通过进化层持续修正 CLAUDE.md 和 .claude/ 各子目录中的内容

• 卸载：项目完成后，将整个工作区的 .claude/ 目录归档（压缩保存或存入共享知识库），然后关闭或删除工作区。下一个项目启动时，重复以上流程

这种模式意味着：同一个系统代码库可以同时存在于多个工作区中，每个工作区服务于不同的项目。一个团队可能在上午处理"老旧系统迁移"工作区，下午切换到"性能优化"工作区——两个工作区看到的代码完全一样，但 AI 看到的 CLAUDE.md、Agent、Skill 和 Rule 完全不同，因此对同一段代码的理解和操作方式也截然不同。

项目知识与系统知识的关键区别：

两类知识的关系

项目知识不是对系统知识的替代，而是对其的重新编排。对同一个系统而言，系统知识是固定的——模块 A 依赖模块 B，数据库有 15 张表，支付流程走三个步骤。但在不同的项目下，这些系统知识被组织成不同的视图：

• 老旧系统迁移：关注模块间的依赖关系、外部接口清单、数据迁移策略

• 性能优化：关注热点路径、数据库查询模式、缓存策略

• 安全合规：关注数据流向、权限模型、审计日志

系统知识是"地图"，项目知识是"导航路线"。地图不变，但不同的行程有不同的路线。AI 需要同时拥有地图和当前行程的路线，才能做出正确的决策。

但导航路线不是出发前就能完全定死的。项目启动时，你知道终点和大致路径，但具体在哪个路口转弯、哪条路更通畅，需要在行进中不断重新评估。每次遇到新路况（新的业务约束、技术限制、团队发现），都是一次微决策——你是继续走原路，还是临时调整路线？这些调整反过来更新项目知识，形成"计划 → 执行 → 发现 → 调整 → 更新"的迭代循环。

无论地图还是导航路线，关键原则始终是：让 AI 在需要的时候能拿到它需要的信息——地图随身带、细节按需查、导航只加载当前行程，而不是把所有知识一股脑地塞进上下文。

技能层：AI 自己怎么做

知识层告诉 AI "是什么"，技能层告诉 AI "具体怎么做"，规则层告诉 AI "什么时候该做什么"。

技能层定义的是 AI 独立完成一个任务时的具体步骤和方法——不涉及人类介入，是 AI 自己的执行流程。这与后面的验证层不同：验证层定义的是 AI 和人的协同流程与验证检查点（什么时候该让人介入），技能层定义的是 AI 在没有人介入时怎么把事情做对。

技能的分类

在复杂系统场景中，技能可以按通用性分为两类。

通用型技能（适用于所有场景）

这类技能不依赖具体代码库的特征——只要不局限于特定项目或代码库，都可以称为通用。它们在任何复杂系统中都有用，既包括认知型技能（产出理解与评估，目的是在动手前消除不确定性），也包括执行型技能（产出测试与实现，目的是在动手时把质量内建）。它们通常是提前设计的。例如：

技能 1：复杂系统勘探
当接到一个不熟悉模块的新功能需求时，AI 应遵循：

1. 从业务层开始：分析这个功能涉及哪些业务流程

2. 再 zoom in 到系统层：涉及哪些模块、调用链、数据流

3. 最后到代码层：关键函数的实现、隐式依赖、风险点

4. 输出分层的勘探报告——按四层结构组织：业务层（目标功能、涉及业务流程、业务规则、交互系统、与现有功能的关系）、系统层（涉及模块、调用关系、数据流向、配置依赖、潜在影响范围）、代码层（入口函数、关键实现、隐式依赖、特殊逻辑、风险评级）、建议策略（可直接复用 / 封装后复用 / 建议新增 / 待确认事项）

技能 2：变更影响分析
当需要修改一个已有函数时，AI 应：

1. 查找该函数的所有调用方

2. 检查调用方是否有对返回值的特定假设

3. 检查函数内部是否有隐式依赖（全局状态、外部调用）

4. 输出影响范围评估

技能 3：根因分析
当系统出现线上问题、bug 或测试失败时，AI 应：

1. 复现问题并锁定触发条件，确认影响范围

2. 从现象出发，沿调用链反向追踪直接原因

3. 区分"症状"与"根因"——复杂系统中一个问题往往由多个因素叠加导致，找到症状不等于找到根因

4. 输出带证据链的根因分析报告（每个结论附代码位置或日志证据）

技能 4：代码考古
当遇到看不懂的代码、特殊逻辑或疑似 dead code 时，AI 应：

1. 用 git blame 定位该代码的引入时间和对应 commit

2. 追溯关联的 PR / Issue，理解当时的设计约束和业务背景

3. 判断这段代码是"有意设计"还是"历史遗留"——不确定时按"有意设计"处理，不擅动；把"看起来像 bug 的行为"先当作业务需要保留，是复杂系统上修改的安全前提

4. 输出理解报告（含"为什么这么写"的结论与可改动性评估）

技能 5：假设验证
当对代码行为存在多个假设、无法确定时，AI 应：

1. 列出全部候选假设

2. 为每个假设设计最小验证实验（日志、断点、临时脚本），明确"什么证据能证明或证伪"

3. 执行实验，收集证据，逐个确认或排除假设

4. 输出验证结论（哪些假设成立、哪些被排除、剩余的不确定性）

技能 6：测试先行（TDD）
当需要新增或修改一段行为明确的逻辑时，AI 应遵循 Red-Green-Refactor 循环：

1. Red：先为期望的行为编写一个失败的测试——明确"这段代码应该做什么"，此时功能尚未实现，测试必然失败

2. Green：写刚好让测试通过的最小实现，不做多余的提前设计

3. Refactor：在测试的保护下重构，清理重复和坏味道，测试保持绿色

4. 循环直至功能完成，输出测试 + 实现代码 + 差异声明

以上六个是复杂系统场景中最常见的通用技能。它们不依赖具体代码库，可以提前设计，也可以在实践发现新的模式后补充——通用型技能的清单是开放的。

代码修改型技能（因代码库而异）

这类技能定义的是"完成一种特定类型的代码修改需要哪些步骤"。它们因项目而异——同一个操作（比如"添加一个新 API"）在不同代码库中的标准步骤可能完全不同。以下是两个代表性示例：

示例 A：添加一个新 API
当需要新增一个 API 端点时，AI 应：

1. 找到该模块中现有 API 的实现作为参考模板

2. 确认路由注册方式（注解式、配置文件式还是代码注册式）

3. 确认参数校验和数据序列化的标准方式

4. 确认错误处理模式（异常结构、错误码、响应格式）

5. 按上述模板生成代码，输出差异声明

示例 B：增加产品属性
当需要为产品模型增加一个新属性时，AI 应：

1. 找到 Product 模型的数据库映射层（Schema 或 Migration）

2. 确认新增属性的类型、默认值、是否为 nullable

3. 更新序列化/反序列化逻辑（如有）

4. 更新业务逻辑中用到 Product 完整字段的代码

5. 检查是否有查询或缓存逻辑假设了固定的字段集合

6. 按顺序完成数据库、模型层、业务层的修改，输出差异声明

技能的来源

技能通常有两个来源：

1. 提前设计：在开始开发前，团队可以基于对代码库的理解，预定义一些常见操作的步骤模板——比如"在这个项目里加一个 API 永远要走这五步"，或者"新功能接入先找类似实现、评估新增还是修改、再找接入点"、"改数据库结构先判断是否有迁移需求、再同步所有读写路径"。这只需要一次架构梳理就能写出来

2. 实践中发现：更多时候，技能是在开发过程中被摸索和总结出来的。当你完成一次特定类型的修改后意识到"这个步骤可以复用"时，你就发现了一个新技能。比如你花了大半天才摸清加一个产品属性要走多少步，下一次自然会想到把它写成一个技能文档

这两种来源并不互斥。提前设计的技能在执行过程中会被修正和细化，实践中发现的技能也会反哺到团队的知识体系中。关键是：只要一个操作模式被验证为"可以在类似场景中复用"，它就值得被提炼为一个代码修改型技能。

至此，技能层回答了"AI 自己怎么做"——通用型技能是常备工具，代码修改型技能是为当前代码库定制的专用工具；而"什么场景该用哪个工具"，正是下一章规则层的职责。

规则层：通用规则与定制规则

规则层回答的是 "什么时候该做什么" 的问题——具体来说，就是在什么场景下用什么知识和什么技能。前面有了知识（AI 知道什么）和技能（AI 怎么做事），规则就是把这些串起来的决策框架。

这里要特别区分知识层里的 When（什么时候）：知识层的"什么时候"是事实——"当 order.status 为 completed 时，代码会走完成流程"，它记录的是代码的客观行为；规则层的"什么时候"是决策——"当任务是新增 API 时，应该使用 API 扩展技能"，它给出的是行动指引。规则层的条件比知识层高一个层次：知识层描述代码会怎么走，规则层决定你应该怎么选。

与技能层类似，规则也分为两类：通用规则（适用于任何复杂系统的决策准则）和定制规则（特定于当前系统代码库或项目的规则）。通用规则是团队的默认行为底线，定制规则是每个系统代码库或项目独有的经验浓缩——两者都通过进化层持续更新。

通用规则

通用规则不依赖具体代码库，通常是一些整个团队需要遵守的基本原则，例如：

1. 最小改动原则：尽量做小改动，能不改就不改——只修改目标函数内部实现，不改变接口签名和外部行为契约。

2. 新增优先原则：新功能优先新增代码（新类、新函数、新模块），而不是修改已有代码——新增的风险远低于修改。

3. 持续小重构原则：每次修改顺手清理一点附近代码，不等"大重构"的机会——目标是让代码逐渐变好，而不是一次到位。

4. 双向理解原则：AI 编码前先用自然语言输出它对相关代码的理解，程序员确认理解正确后再动手——不止 AI 要理解，程序员也要确认 AI 的理解是否正确。

5. 行为守恒原则：修改已有代码时优先保留现有行为，包括那些看起来可能不对的"特性"——未经确认不要"擅自修复"，你认为是 bug 的可能是业务需要的特殊逻辑。

6. 变更差异声明：每次修改完成后，AI 必须输出结构化的差异声明，从技术层（代码变动）和业务层（对用户和业务流程的影响）说明变更内容和影响范围。

7. 显式假设声明：AI 编码前必须输出它对自己理解做出的关键假设——假设错了整个方案就错了，显式声明让程序员能在编码前拦截错误。

8. 单次职责：一次 AI 请求只完成一个逻辑变更——多个变更分多次请求，聚焦单一目标，便于 review、回退和定位问题。

9. 可回退原则：每次修改预留回退路径——新增代码通过 feature flag 或适配层控制，修改现有代码时保留旧路径，出问题可以快速回退。

以上 9 条只是示例，你的团队可以定义自己的通用规则。

定制规则

定制规则特定于当前系统代码库或项目，随系统代码库或项目不同而不同。它们主要来自两个来源：

1. 任务类型 → 技能匹配：每个代码库有自己的代码修改型技能（见技能层），相应地需要"什么任务用哪个技能"的匹配规则。这类规则以 任务类型 → 技能 的形式表达，例如：

   • 在已有模块中增加完整业务功能 → 新功能接入技能（涉及多代码层、有明确业务入口）

   • 新增一个 API 端点 → 添加新 API 技能（聚焦接口契约，不涉及深层业务流程变更）

   • 为模型增加一个新属性 → 增加产品属性技能（看似简单，但往往涉及数据库、序列化、业务逻辑、缓存多处联动）

   • 修改数据库表结构 → 修改数据库结构技能（重点考虑数据迁移和向后兼容）

   • 没有任何技能匹配 → 回退到通用流程（先勘探、再影响分析），由程序员判断是否需要提炼为新技能

2. 项目特定约束：团队在实践和踩坑中固化的规则，例如"不要修改跨仓库引用的接口签名"、"orders 表的改动必须走数据迁移流程"。这类规则通常由进化层沉淀而来，一条一句话即可。

与通用规则不同，定制规则没有"固定清单"——它们随系统代码库演化、随项目变化。通用规则保证 AI 在任何复杂系统上都有行为底线，定制规则让 AI 在当前系统代码库或项目里做出正确的具体选择——二者配合技能层的执行路径，AI 才能从"知道怎么做事"到达"知道在什么情况下做正确的事"，而且这个"什么情况"会随团队经验的积累不断更新。

至此，规则层回答了"什么时候该做什么"——如果知识是地图、技能是工具箱，规则就是路标：在哪个路口转弯、什么时候该停下来确认、遇到什么路况该用工具箱里的哪个工具，都由它决定。三者合在一起，AI 才真正知道在什么情况下做正确的事；而"什么时候该让人介入把关"，正是下一章验证层的职责。

验证层：Human in the Loop——AI 和人的协同与验证

前三层（知识、技能、规则）定义了 AI 知道什么（是什么）、怎么做、什么时候该做什么——三者各司其职。但这些机制都是"自运转"的——AI 按预设的知识、技能和规则执行，过程中没有人的干预。问题在于：AI 的理解可能有偏差，规则可能有盲区，复杂系统中的特殊情况可能超出预设框架。

这就是验证层存在的意义——把人放回回路中。

验证层回答两个问题：AI 和人如何协同（哪些步骤由 AI 做、哪些由人做），以及人在哪些关键节点、以什么方式验证 AI 的输出。这两件事本质上是同一件事——流程中每一个"人参与的步骤"，都是在验证 AI 的工作。每一次验证，都是一次 Human in the Loop（人在回路中）的质量把关。

在我们的实践中，有两类典型的协同流程：新功能开发流程——把新能力安全地加进系统；故障处理流程——把出问题的系统安全地救回来。两者的目标不同、步骤不同，但结构相同：AI 主导执行，程序员在关键节点把关——每个 AI 主导的步骤之后，都跟着一道由人把守的"拦截门"。

下面的对比表只是示意——它展示验证层在真实协同中长什么样（AI 做什么、人什么时候把关），而不是可以直接复用的标准模板。每个团队都应结合自己的系统代码库和项目，定制属于自己的步骤和检查点。

两条流程的差异集中在两端：开发流程的第一步是"勘探怎么做"，故障流程的第一步是"定位为什么错"；开发流程以"功能上线"收尾，故障流程则多了一道"确认不复发"的关口——目标是"系统回到健康状态"。

验证层的核心原则：人做判断，机器做检查

验证层的设计遵循一条原则：程序员的精力应用在高价值的判断上，而不是低价值的机械检查上。

表格的核心意思是：AI 产出的验证材料（差异声明、影响分析等）是为了让程序员的判断更高效，而不是为了替代程序员的判断。 差异声明是验证层的核心产出物，但它的价值在于让程序员"一眼看出风险在哪里"，而不是让程序员"相信差异声明就够了"。

这里有一个容易混淆的点需要澄清：第一章困境二说"你无法判断这一两行代码的影响范围"，这里又说"影响范围枚举"可以由 AI + 工具完成——两者并不矛盾。AI 能做的是枚举：快速扫描调用链和依赖，产出"哪些地方可能受影响"的候选清单，替代人的机械扫描；而判断——这些候选里哪些是真实风险、影响多大、如何应对——始终由人完成。枚举解决的是"信息不全"，判断解决的才是"决策"。

总结一下：验证层是整个框架中 Human in the Loop 的集中体现。前三层（知识→技能→规则）让 AI 在大部分时间里自主运转，但验证层确保在关键决策节点上，最终判断权始终在人手上。没有验证层，AI 在复杂系统中搞破坏的速度远快于它帮你构建的速度——引言里那个翻车故事，正是知识层与验证层同时缺位的后果。

进化层：让整个体系自我更新

前四层（知识、技能、规则、验证）定义了 AI 当前应该怎么做。但复杂系统是演化的，需求是变化的，团队的经验是持续积累的。如果没有一个机制让 AI 从每次修改中学习、并把学到的东西更新回前面的层面，那这套体系就是静态的——今天有效，三个月后就过时了。

进化层回答的是：如何让 AI 从本次修改中学习到新东西，并更新到前面的层级？ 进化层的更新目标主要是三个内容层面——知识、技能、规则；验证层本身不直接接收更新，它的形态会随前三层的变化而调整（详见最后一章）。其中技能层——尤其是代码修改型技能——更新最频繁：知识层变化相对低频（业务规则不天天改），规则层追求稳定（改规则需要团队共识），而技能层直接反映日常开发中"怎么做效率最高"的实践积累。当然，知识层同样通过进化层持续修正——系统知识与项目知识都在更新之列（两者如何区分、如何回流，知识层已详述，此处不重复）。

本章将分五步展开：进化信号从哪来（三个来源）→ 什么信号值得被记录（质量关卡）→ 信号回流到哪个层面（三条回路，以及「新内容更新到哪里」的判断）→ 由谁以什么方式触发进化（进化与团队协同）→ 整个体系如何因进化而自我更新（五层体系的进化视角）。

进化的三个来源

新知识、新技能、新规则不会凭空产生。它们来自日常开发的三个渠道。参考 learn-from-history 技能框架中的信号检测模型，团队可以从以下三个来源提取进化信号：

来源一：代码变更过程（User Story + PR）

每一次功能开发都经过"需求→设计→实现→评审→合并"的完整周期，每个环节都可能产生对知识、技能或规则的修正：

来源二：AI 对话历史（Chat History）

团队使用 AI 的对话记录中，包含两种直接触发进化的信号：

显式反馈：用户明确纠正 AI 的回答或补充上下文。

"不要修改这个函数的签名，所有调用方都在另一个仓库里。" → 这条反馈应该更新规则层（新增一条"禁止修改跨仓库接口"的规则）或知识层（补充"这个签名被多个仓库引用"的事实）

"这里的折扣逻辑不是 bug，是业务要求。" → 这条反馈应该更新知识层（补充"特定客户类型折扣为 0"的业务知识）

AI 自主发现：AI 在推理中发现的、不在上下文中的正确知识。

"我发现这个模块的所有 Repository 都继承了一个未文档化的锁机制。" → 如果验证为正确，这条发现应该更新知识层（补充"BaseRepository 有隐式锁机制"的知识点）

来源三：团队沟通记录（Teams、Slack 等）

日常沟通中的对话也可能包含进化信号，但提取门槛最高，因为噪音多、信号弱。以下信号尤其值得捕捉：

扫描节奏建议按团队沟通密度调整——高密度的核心团队可每周一次，低密度的小团队每月一次即可。核对时逐个回答：同个问题是否被多人/多次问起（没有对应知识条目则补知识层，有则检查是否足够显眼）；聊天中是否达成过技术决策（决策理由沉淀为知识层、决策规则沉淀为规则层）；是否有"某人报错 + 另一人给出可复用方案"的对话（解决步骤可标准化则沉淀为技能层）；是否有人主动分享了可复用的做法（而非一次性提醒，沉淀为知识层或技能层）。

质量关卡：不是所有信号都值得更新

三个来源每天产生大量信号，但不是每个信号都值得变成正式的更新。参考 learn-from-history 技能中的五维质量评估框架，一条候选信号必须依次通过五道关卡，任何一道不过就不记录——低质量更新的危害比不更新更大，它会稀释有用知识的密度，让 AI 变得"什么都记但什么都记不准"：

1. 可复用性：适用于一类问题，而非单次事件？

2. 非显而易见性：需要本项目特定经验才能知道，而非通用知识？

3. 可操作性：可以写成明确的条目或步骤？

4. 非重复性：现有知识/技能/规则集中还没有？

5. 具体性：包含明确的上下文和执行条件？

只有全部通过才更新到对应的层面；未通过的候选可以留待下次回顾时重新评估。

需要注意的是，项目知识同样适用这套质量关卡，但各个维度的含义需要根据项目知识的特性调整：

区别在于：系统知识追求"长期有效"，所以对可复用性和非显而易见性的要求更高；项目知识追求"当前工作有效"，所以可复用性的门槛更低——只要在当前项目的后续阶段仍然有用，就值得记录；项目结束后即归档，不会永久占用上下文空间。

进化的三条回路

通过质量关卡的信号，沿着三条回路反馈到前面的层面：

回路 1：发现新事实 → 更新知识层
  例如：发现"模块 X 有隐式依赖" → 写入知识层的坑史

回路 2：发现更好的执行方式 → 更新技能层
  例如：完成一次"增加产品属性"的修改后，提炼出标准步骤 → 新增一条"在产品模型中增加属性"的代码修改型技能

回路 3：发现更优的决策依据 → 更新规则层
  例如：发现两条规则在场景 Y 下相互冲突 → 补充优先级规则

三条回路一一对应三个内容层面，更新的都是与系统或项目相关的知识、规则、技能：回路 1 更新 AI 对系统的认知（事实），回路 2 更新 AI 做事的方法（步骤），回路 3 更新 AI 决策的依据（准则）。之所以没有第四条回路，是因为 项目知识并不是一种独立类型的更新目标——它仍然是一种知识，最终仍落入回路 1（知识层），只是生命周期不同。一条信号到底该更新到哪个层面、以及该归入系统知识还是项目知识，统一由下一小节「新内容更新到哪里」裁决。

新内容更新到哪里

上一节的质量关卡回答"值不值得记"，本节回答"记到哪里"——两者构成进化的两步流水线：先过滤，再路由。一条通过质量关卡的信号，该更新到哪个层面，取决于它的形式与内容。这里复用 learn-from-history 的「形式 → 路由」思路——先按形式把可沉淀内容分成「单条知识/规则」（一句话可表达）与「技能/能力」（多步骤流程），再按内容路由到目标。映射到本框架，判断分两步：

第一步：按形式与内容选择层面

先从形式入手——这条信号能否用一句话说清？

• 需要有序步骤、参数或条件分支（"完成 X 类型修改要走哪几步"）→ 技能层。learn-from-history 称之为 procedure（能力），对应技能层的通用型与代码修改型技能

• 单句可表达（一条指令或一个事实）→ 再按内容细分（对应前文知识层与规则层的边界）：

  • 描述系统或项目的客观状态（模块依赖、业务规则、架构事实、坑史）→ 知识层

  • 描述决策准则或路由触发——"当 X 场景时该用哪个技能 / 走哪条路径"，与 learn-from-history 的规则格式 "When [scenario] → apply [capability]"、以及定制规则中"任务类型 → 技能"的匹配规则一致 → 规则层

一个实用提示：存疑时默认按技能处理。learn-from-history 的原则是——多步骤内容沉淀为技能更安全，之后可随时简化为一条知识或规则；反之把多步骤压成一句话，容易丢失执行细节。

用一个边界案例说明："模块 X 的订单校验要先查缓存、再查库，缓存未命中回退默认值"——它既像一条事实（模块行为描述，可进知识层），又含"先 → 再 → 回退"的步骤结构（可进技能层）。按默认原则先按技能沉淀，把步骤固化成可执行的校验流程；即使后来发现它其实只是一条简单事实，也可以随时简化回知识层——但反过来，如果一开始就压成一句话，那三个步骤的细节就丢了。

第二步：判断归属——系统知识还是项目知识

无论信号落入知识、技能还是规则层，都需要再做一次归属判断：这条内容属于系统知识（长期有效），还是属于项目知识（只在当前工作周期内有效）？判断标准是生命周期：

• 系统知识：长期有效，随系统存在，不因项目结束而失效 → 更新到系统级上下文（该系统代码库的 CLAUDE.md、.claude/ 或工作区根目录），随版本管理长期保留，变更要经过严格的质量把关（尤其可复用性与非显而易见性）

• 项目知识：只在当前工作周期内有效 → 更新到项目级上下文，不需要评估"是否值得长期保留"，项目结束即归档

用回路 1 的另一个例子说明：迁移中发现"模块 C 的依赖关系比预想复杂，原计划'先迁移 C'不合理"——这是一条事实（模块 C 的依赖关系），进知识层；但它只对当前迁移项目有效，属于 项目知识，随项目结束归档，而不是写进长期有效的系统知识。

这三条回路可以有人触发，也可以自动运行，具体取决于团队的 AI 成熟度。成熟度较低的阶段以人工触发为主——触发者可以是任何团队成员，在一次 PR review 中发现了一个未记录的知识点，在一次 AI 对话中纠正了一个错误，在聊天记录里看到一个问题反复出现，都可以启动一条回路；成熟度较高的阶段，工具可以自动扫描信号、生成更新候选，人只做最终确认。两种模式的分工、代价与演进路径，正是下一节「进化与团队协同」要展开的。

进化与团队协同

进化的触发是个人行为，但更新的生效需要团队共识。这套体系的理想形态，是从 Human in the Loop 走向 Human on the Loop——进化层做得越好，需要人来亲手验证的就越少。本节讨论的两种触发模式，正是这个演进在进化层内部的体现。

前面提到的三条回路和三个进化来源，在多数团队目前所处的阶段都依赖人工发现和手动触发——有人在 PR review 中发现了未记录的知识点，有人在与 AI 的对话中纠正了错误，有人在聊天记录里看到重复问题，然后这个人决定"应该把这个记下来"。这是一种 Human in the Loop 的模式：人在回路中，发现→判断→触发，机器只是被动的执行者。

但这不是唯一的模式。还有一种 Human on the Loop 的模式：AI 或工具自动扫描信号，自动通过质量关卡初筛，自动生成更新候选，人只需要在关键节点做最终确认——人不在回路中，而是在回路上方监督和把关。

当前我们描述的机制——定期回顾、PR 中的手动发现，以及下文将展开的共享上下文仓库——都属于 Human in the Loop。它们的问题是：认知负担全部压在个人身上。团队里的每个人都需要同时做两件事——完成本职工作，同时保持对"这可能会是一条新知识"的警觉。没人有额外的精力做这件事。结果就是，进化机制虽然理论上存在，但实际运行起来断断续续。

我们应该努力向 Human on the Loop 演进。 具体来说，工具层面可以逐步做到以下自动化：

1. 信号采集自动化：AI 对话历史、PR 讨论、聊天记录中的进化信号，由工具按预设模式自动扫描，输出候选信号清单。人不需要主动去想"这周有没有新知识"，只需要每周花 15 分钟过一遍工具生成的候选清单。

2. 质量初筛自动化：质量关卡的五个维度（可复用性、非显而易见性、可操作性、非重复性、具体性）中，至少前两个——可复用性（是否适用于一类问题）和非重复性（是否已记录）——可以通过比对现有知识库自动化判断。将"候选信号 vs 已有知识"的比对交给 AI 做，人只需要做最终裁决。

3. 更新执行辅助化：通过质量关卡的信号，由 AI 自动生成更新建议——"建议在知识层新增以下条目……"、 "建议在技能层新增以下步骤……"——格式与现有知识/技能/规则集一致。人只需要 Review 和确认，不需要从零开始写。

4. 异常信号主动推送：不仅是"等人来看"，工具还应主动推送值得关注的异常信号——"最近一周，模块 X 在 AI 对话中被标记了 3 次'隐式依赖未记录'，建议补充至坑史。" 这种推送可以嵌入每日站会或每周同步中，成为团队节奏的一部分。

这四条自动化路径不是一步到位的。我们可以从第 1 步（信号采集自动化）开始，逐步推进到第 4 步。每完成一步，团队在进化上的认知负担就减轻一分。最终目标是一个半自动化的进化管线——工具持续扫描、自动初筛、生成候选，人只在最终确认环节介入。

在这个目标达成之前，以下是一些轻量级的过渡机制，帮助团队在 Human in the Loop 模式下也能维持进化的节奏。它们的自动化程度不同——前两条完全依赖人工执行，最后一条已经是半自动形态，是通往完整自动化管线最自然的第一步：

1. 共享上下文仓库：包含知识集、技能集、规则集、案例库、坑史、勘探报告库。这是团队经验的最终载体。

   它最常见的物理形态是一个 workspace 下有多个系统代码库——workspace 与每个系统代码库各自维护独立的 CLAUDE.md 和 .claude/ 文件夹，与知识层说过的存放边界规则一致：

   • workspace 级 CLAUDE.md + .claude/：存放跨系统代码库的共享上下文——业务知识、跨系统架构、通用规则，以及指向各系统代码库上下文的索引

   • 系统代码库级 CLAUDE.md + .claude/：存放该系统代码库独有的上下文——系统内架构、编码规范、坑史、定制规则

   新人 onboarding 也依托这套结构：新成员先读 workspace 级 CLAUDE.md 建立跨系统的全局认知，再进入具体系统代码库读系统代码库级 CLAUDE.md 掌握目标模块的上下文，然后实操一遍"勘探 → 提取候选信号 → 质量关卡评估 → review 确认"的完整进化流程。这既完成了培训，也顺势为知识库做了一次"体检"——新人的新鲜视角最容易发现"手册与实际代码不符"的知识缺口，这本身就是优质的进化信号来源。

2. 定期回顾：在迭代 retrospective 中固定一个"进化回顾"环节——"这周发现了什么新知识？修正了什么规则？新增了什么技能？"

3. 进化 Skill（半自动）：把"发现 → 评估 → 更新"的流程本身做成一个可复用的 Skill——成员完成一次 PR review、AI 对话或故障处理后，只要觉得"可能有值得沉淀的东西"，就随时运行它：自动扫描信号源提取候选信号、按五维质量关卡初筛、生成格式统一的更新建议，成员只需做最终确认。learn-from-history 技能 就是这样一个进化 Skill 的实例，团队可以直接复用或在其基础上定制。

与前两条机制相比，进化 Skill 把认知负担从"人的记忆"转移到了"Skill 的流程"上——成员不用再时刻记住要留意什么信号、如何评估，只需要在觉得有收获时运行它、在最后做判断。它已经踩在 Human on the Loop 的门槛上，本质上是上文四条自动化路径第 1-3 步的轻量实现：团队可以先从它起步，再逐步向持续运行的自动化管线推进。

五层体系的进化视角

把进化层和前面的四个层面放在一起看，整个体系的运作方式是这样的：

每一层都依赖上面层级的支撑，而进化层又通过三条回路把新学到的内容反馈回上面层级，形成一个自我更新的闭环——这正是整套框架的灵魂：不是一套静态的规则，而是一个持续进化的复杂系统生存系统。

回顾整个进化层：三个来源回答"信号从哪来"，质量关卡决定"什么值得记录"，三条回路与更新位置判断把信号送回对应层面，进化与团队协同决定"由谁以什么方式触发"，五层体系的进化视角展示了整个闭环如何运转。至此，五层框架的每一层都已完整展开——下一章把它们放在一起，看验证层与进化层如何共同推动整套框架演进。

验证层与进化层：从 Human in the Loop 走向 Human on the Loop

上一章在讨论进化触发方式时，已经接触过一次"从 Human in the Loop 走向 Human on the Loop"；本章换一个角度——从验证负担的转移来看——验证层与进化层如何共同推动这个演进。

验证层的存在，本质上是承认一件事：当前的知识、技能、规则还不够完整——AI 的理解可能有偏差、规则可能有盲区、特殊情况可能超出预设框架。而进化层的职责，正是让这些层面越来越完整。两者因此形成一种此消彼长的关系：

进化层做得越好——知识越完整、技能越成熟、规则越准确——AI 的勘探报告、假设声明、差异声明就越可靠，需要人来逐点把关的偏差和盲区就越少。

• 初期：知识残缺、规则粗糙，AI 的输出不可预测 → 大部分验证都必须由人亲手完成，人承担着主要的验证负担

• 中期：进化层持续修正知识、沉淀技能、固化规则 → 越来越多的机械检查可以委托给 AI 和工具，人开始聚焦在高价值判断上

• 理想形态：知识足够完整、规则足够准确 → 所有可自动化的检查都委托给 AI 和工具完成，人只保留最终判断权

但这里有一个关键前提，也是验证层不会消失的根本原因："哪些检查可以委托给 AI、哪些必须由人来判断"——这个边界本身，永远由人来决定。 最终判断权始终在人手上：人可以决定把越来越多的检查委托出去，也可以随时把某类检查收回人工判断。所以验证层不会消失，变薄的只是"人亲手执行的验证负担"；验证层的形态会改变——从"人在回路中逐点执行"，走向"人在回路上方决定边界"。

这个演进有一个更深刻的含义：进化层最终要走向的形态，正是 Human on the Loop（人在回路上）——当大部分检查都委托给了 AI 和工具，人退到"回路上方"，主要通过进化层间接控制 AI 的行为——发现 AI 犯错，把教训写进知识、技能、规则，AI 下次不再犯。人在回路中的执行职责被逐步委托出去，人在回路上方的判断职责，才是人最终的形态。

但必须诚实：复杂系统的根本特征是"特殊情况总是超出预设框架"——知识再完整，也总有没记录到的隐式依赖；规则再准确，也总有覆盖不到的边缘场景。这意味着无论进化层多强，总会留下一些必须由人判断的验证。但方向是清晰的：进化层越强，人需要亲手验证的越少，而"把精力放在哪里的判断"越重要。

这套框架的价值，最终要落到一个具体的问题上：有了它，开头那个翻车故事还会重演吗？

结论

回到开头那个翻车故事——如果当时我们有这套生存指南，故事会是另一个结局。AI 在动手前会先完成复杂系统勘探：顺着请求链路往前查，它会发现请求先经过前置路由的前端，而前端早已有一条新的迁移流程——迁移应该发生在这里，而不是老系统的老页面，哪怕这段前端代码在另一个代码库里。这是一道层层兜底的防御纵深：即使勘探这一步有所遗漏，规则层定义、由验证层检查点强制的"先说明理解、再声明假设"也会兜底——AI 必须先说出"我只看到了老系统的老页面"，再把方案假设摆到桌面上——"我打算在老系统的老页面实现广告迁移"——哪怕我们是新人，也能立刻意识到"不对，我们已经有新流程了"。而知识层会从一开始就让它知道：这个功能应该落在哪里。每一道关卡单独生效，那个事故都不会重演。

但比个人用对生存指南更重要的，是团队一起用对生存指南。

复杂系统不是一天建成的，也不会因为用了 AI 就自动消失。AI 不是魔法棒——它跑得快，但方向要靠你来定。而方向不能只靠一个人定——Senior 的经验、新人发现的新坑、团队达成的共识，需要有一种机制持续地汇入这份生存指南。

这套框架的五个层次，从下到上各回答一个问题——知识层"是什么"、技能层"怎么做"、规则层"什么时候该用什么"、验证层"人做什么、什么时候做"、进化层"如何从本次修改中学习"——前三层定义 AI 的内在能力，验证层定义人与 AI 的协同与把关，进化层让整个体系自我更新，而最终判断权始终留在人手上。这份生存指南，说到底就是：一张地图、一套工具箱、一路上的路标——再加上验证这道安全护栏，和一台让指南永远跟得上系统的进化引擎。

这是我在一个真实项目中正在实验的方法。它还不够完美，还在迭代中。但有一个判断我越来越确信：在复杂系统中，AI 最大的价值不是写更多代码，而是严格执行那些我们总结了多年、但常常因为各种原因而没能遵守的生存指南。当这些生存指南成为团队共享的资产、并且通过进化层持续更新时，AI 就不再只是个人的编码助手，而是整个团队在复杂系统生存的基础设施。

它的最终形态，是让进化层越来越强、需要人亲手验证的越来越少——AI 不再是需要人逐点把关的工具，而是被一套持续进化的生存指南约束的可靠协作者；人退到回路上方，决定哪些交给 AI、哪些自己判断。

下一步，我们打算把这套方法论进一步工具化——做成可以直接复用的 Agents 和 Skill 文件，并建立五层体系的完整配置模板，让每个加入项目的成员都能拿到一套"复杂系统生存指南"。

如果你也在类似的代码库上挣扎，或者对这套方法有自己的经验和看法，欢迎交流。毕竟，每一个复杂系统都不一样，但对付复杂系统的经验，值得共享。