这个系列记录我们团队怎么让 Claude Code 和 Codex 参与整个研发流程。开发阶段拆成三篇:上一篇(AI-SDLC 实践 05)讲了多仓库的工程结构——用一个主仓登记二十多个业务仓库,Agent 统一在主仓启动,代码则写在每个业务仓库从基线切出来的 worktree 里。这一篇讲开发阶段的知识库,下一篇讲 D2C。
让 Agent 真正进项目写代码,光看得懂语法不够,它至少得知道两类东西:一是团队的编码规范和架构约定,二是当前这个页面、这个模块的业务规则。
最常见的起步做法,是把能想到的要求全塞进 CLAUDE.md 或 AGENTS.md。但这套做法很快就会撞墙:文件越塞越长,上下文被大量无关规则挤占;更麻烦的是,真实的业务规则散落在文档平台、二十多个代码仓和老员工脑子里,根本塞不进单个引导文件,塞进去了也没人维护。
折腾一圈后,我们把开发阶段的知识管理收敛成三条做法:
- 按「怎么读」给知识分三层(K0 / K1 / K2),管住加载方式和上下文体积;
- 业务知识放回负责它的代码仓,而且只记代码里看不出来的东西;
- 开发中不改正式知识,等交付验证通过后再统一核对回写。
这背后最大的教训其实就一句话:代码是最好的知识,没必要用一份大而全的文档再描述一遍代码。
1. 知识按「怎么读」分三层:K0 / K1 / K2
很多团队给文档分级,习惯按「重要程度」分 P0、P1、P2,结果所有人写文档都觉得自己那份是 P0。我们换了个维度,严格按 Agent 的加载方式 把知识分成三层:
| 层级 | 定位 | 内容特征 | 加载方式 |
|---|---|---|---|
| K0 | 一定不能犯的错(防错规则) | 短、可执行、明确写出适用条件和例外 | 按当前涉及的仓库、平台、模块完整直读,不经搜索、不挑着读 |
| K1 | 正确做法(方法文档) | 架构模式、实现步骤、代码示例、验证方法 | 当前执行哪个 Skill,就精确读取该 Skill 登记的那几份 |
| K2 | 按需查的事实 | 接口定义、组件能力、业务字段、来源信息、历史资料 | 用到时才查,读取时记录来源、版本与内容 hash |
理解这三层,最关键的一点是:分层看的是怎么读,不是重要程度,也不是冲突时的优先级。
把标准卡死在「怎么读」之后,K0 的体积自然就被压下来了。在我们的实际工程里,规范与方法文档一共有 244 份、约 1.45 万行;但真正划进 K0 防错规则的只有 19 份、共 206 行,只占总行数的 1.4% 左右。在知识登记表里,K0 规则一共 19 条,而 K1 方法条目有 259 条。200 多行的体量,哪怕每次任务全量塞进上下文,负担也极小。
为了防止 K1、K2 往 K0 里膨胀,或者历史文档误导实现,我们定了两条硬性判定规则:
- 文档里写了「必须」,不代表整份文档就是 K0。 比如我们有一份标题就叫《强制规则》的架构文档,里面讲的是模块分层的完整做法和示例,篇幅长、需要结合具体开发动作看,它依然登记在 K1,由对应的开发 Skill 精确加载,而不是无脑塞进 K0。
- 历史资料只能作参考,不能单独支撑关键的架构、接口或业务规则判断。 过去的需求文档、旧方案全归在 K2,没跟当前代码核对过,不能直接当成实现依据。
同时,我们严格把 「知识」和「证据」分开:当前分支的代码、运行日志、界面截图、测试结果属于证据。证据用来验证当前状态,不当成正式知识沉淀;反过来,也不能拿历史知识去代替当前的运行证据。
2. 每层知识在开发时怎么加载
有了分层,下一步是怎么让 Agent 在正确的时间读到正确的文件,而不是靠它自己「猜着搜」。
每次开发任务启动时,我们的 CLI 会根据本次交付涉及的仓库和平台,直接算出一份当前步骤的阅读清单:
- 设计交接记录、任务图、适用的 K0 防错规则:全部必读;
- K1 方法文档:只列当前 Skill 登记过的文档,再细分为「必读」和「满足条件才读」。
K1 的双向索引与归属约束
K1 能做到精确加载,靠的是一张结构化的登记表。每份 K1 方法文档都必须在登记表里声明清楚四件事:给哪些 Skill 用、默认什么条件下读、对哪些 Skill 是必读、以及每个 Skill 各自的触发读取条件。
登记表会自动生成 「方法 → Skill」 和 「Skill → 方法」 的双向索引。消费关系只在登记表这一处维护,文档正文里绝不重复写「本文档供某某模块使用」,省得改起来两边不一致。如果一份方法文档连明确的使用者都说不清,必须先补齐归属——登记表里不允许出现「Agent 按需读取」这种等于没说的模糊描述。
K2 的读取与去 MCP 化
K2 事实资料不做预加载:本地仓库有的文件直接读本地;放在文档平台上的资料,直接调用文档平台的命令行工具拉取。每次读取都会记下来源路径、版本号或内容 hash、以及读取时间。
异常处理也做了区分:查不到、没权限、网络失败、没命中会分别如实记录状态;如果是 K2 的历史参考资料没命中,记录下来即可,不阻塞正常开发流程。
顺带提一个我们踩过的架构演进:早期我们专门搭过一个统一的「知识 MCP 服务」来收口文档查询,后来干脆把它去掉了,全面改成本地文件直读加文档平台 CLI 调用,开发前也不再做什么 MCP 就绪检查。原因很简单——少一层常驻中间服务,就少一堆连接超时、鉴权过期和环境初始化的破事,CLI 加本地文件在终端工作流里稳得多。
派发子 Agent 时的上下文传递
复杂任务经常需要主会话派发子 Agent 去跑独立子任务。这里有个非常容易漏掉的坑:父会话读过规则,不代表子 Agent 读过。
因此我们规定,派发任务时必须把任务定义路径、任务 ID、目标 worktree 路径、规则文件路径一并传过去,由子 Agent 自己读取并核对。尤其是适用的 K0 防错规则,派发时必须直接带上规则正文和来源,只传一个文件名过去让子 Agent 自己找是不算数的。
和宿主自带机制的关系
看到这里可能会有人问:Claude Code 本身就有 CLAUDE.md、支持带 paths 字段按路径触发的 .claude/rules、还有 Skill 渐进加载;Codex 也有分层的 AGENTS.md,为什么不直接全靠宿主自带的机制?
核心原因在于上一篇讲过的工程结构:Agent 的启动目录是主仓,而不是具体的业务仓库。 一次跨端或跨模块交付,往往同时涉及多个业务仓和特定平台,我们需要在任务启动那一刻,按「本次交付涉及哪些仓库、平台、模块」把规则先筛出来,宿主基于单一当前工作目录的默认机制覆盖不了这个维度。
3. 业务知识放回负责它的代码仓
解决了规范和方法怎么读,更难啃的其实是业务知识。
早期我们也试过把某个模块的逻辑整理成详尽的说明文档喂给 Agent,很快就发现纯属给自己挖坑:代码一改,文档就过期;Agent 读了过期的长文档,反而把原本写对的代码改错了。
这就是开篇说的那个教训:代码是最好的知识,没必要用一份大而全的文档再描述一遍代码。 函数怎么调、字段怎么拼、状态流转怎么写,代码里一眼能看出来的实现细节,让 Agent 直接读源码就够了。知识文档只记代码里看不出来的东西:
- 业务规则与边界约束;
- 特殊交互约定与异常兜底逻辑;
- 跨仓库的隐性依赖;
- 为什么这么定(背后的业务背景或历史取舍)。
存放位置与唯一正文
这些业务知识不单独建集中的「知识库仓库」,而是直接放回负责该模块的代码目录旁边的 docs/ 下,跟代码同仓管理。共用组件的约定放在组件自己的仓库里,业务方只做引用,绝不复制粘贴。
在每个模块下,一个页面或模块只维护一份 Spec,作为这个模块当前有效业务规则的唯一正文。我们不会为每一次需求迭代都新建一份需求副本——新需求来了,只在这份 Spec 上更新确实变了的部分;废弃的老规则要么明确删掉,要么标清楚被哪条新规则替代。
为了让引用不因文档重构而断掉,Spec 的核心章节(场景、业务规则、界面、验收、不变量)全部带有稳定编号:移动章节位置时保留原编号,章节改名时也保留旧编号映射。
双重状态标记与受管入口
为了防止 Agent 把猜测当成定论,每份业务知识文档都必须标清楚两个维度的状态:
- 生效状态:
草稿/生效/废弃 - 结论性质:
已确认/从代码观察到/未定
只有结论性质为「已确认」的内容,才允许标为「生效」(注意:「生效」代表它是当前认可的业务规则基线,不代表代码已经上线)。还不确定的事项单独列为「缺口」,所有结论的来源都要精确写到具体的代码提交(commit)。
至于业务仓库根目录的 AGENTS.md,里面只放入口链接和工程约束,不放具体业务事实。工具自动回写索引时,也只允许修改 AGENTS.md 里划定的一小段「受管链接块」,块外原有的手写内容一行都不碰。
轻量交付记录与历史决策
除了维护当前有效的模块 Spec,每次需求交付还会留下一份很短的交付记录,只记五件事:原行为、本次新行为、生效条件、明确保持不变的部分、验证结论与来源链接。
技术方案、代码评审、缺陷单这些过程产物,一律以团队原有的系统为准,交付记录里只放链接;原系统里没有某项产物就不建空文件,绝不为了形式整齐默认生成一整套阶段文档。长期有效的架构或业务大决定,则单独记在决策目录里;所有历史资料都只作背景参考,不能覆盖当前生效的知识正文。
4. 规则冲突时听谁的
主仓有通用规范,业务线有自己的习惯,具体到某个老业务仓又有历史包袱,三边撞车时 Agent 听谁的?
我们定了三层工程规则优先级,序号越大越优先:
- 主仓的通用默认规则:兜底补足上层没有规定的事项;
- 当前业务线的规则:业务线的差异化要求优先于通用默认;
- 目标仓库 worktree 里适用的
AGENTS.md规则链:优先级最高,直接覆盖前两层的同一事项。
只有当这三层全都没规定时,Agent 才从目标业务仓库同模块、同技术栈的现有代码和 lint 配置里归纳习惯,不允许凭模型自己的偏好另造规范。
举个最直观的例子:假设主仓通用规则要求文件名用 kebab-case,某条业务线规则要求用 PascalCase,而目标业务仓的 AGENTS.md 明确要求 snake_case,那在这个仓里写代码就用 snake_case;如果业务仓没提,就按业务线的 PascalCase 来;业务线也没提,最后才落回通用的 kebab-case。
这里有两个边界必须拎清:
- 这套优先级只管命名、编码、架构、目录布局这类工程规则,绝不改变用户的明确指令、动作授权和工具权限;
- 再次强调,K0 / K1 / K2 是加载方式,不是优先级:哪怕主仓里某条命名约束标了 K0 必读,只要目标业务仓的
AGENTS.md对同一命名事项有明确约定,依然以业务仓为准。
为什么不靠宿主自动加载,而要强制 Agent 自己读规则链?
这一条是我们专门对照 Claude Code 和 Codex 的官方文档核验后定下来的硬要求:
- Claude Code 的加载机制(参考官方文档 Memory 说明):启动时会加载当前工作目录及上级目录的
CLAUDE.md;子目录里的CLAUDE.md要等真正读写那个子目录的文件时才会按需加载。更关键的是,在默认设置下,只要工作目录或上级目录存在CLAUDE.md,它就不会去读AGENTS.md;而AGENTS.override.md在任何设置下都不会读。因为我们的主仓根目录放了CLAUDE.md,业务仓里的AGENTS.md默认根本不会被 Claude Code 自动加载。 - Codex 的加载机制(参考官方文档 AGENTS.md 指南):Codex 是在启动时一次性构建指令链,从项目根目录往下走到当前工作目录,每一层依次查找
AGENTS.override.md、AGENTS.md和备用文件名,默认拼接到 32 KiB 上限为止。当 Agent 的启动目录是主仓时,业务仓切出来的 worktree 压根不在这条启动路径上。 - 存量仓库的现实情况:二十多个业务仓的历史演进不同,有的只有
AGENTS.md,有的只有CLAUDE.md,有的两个都有,还有不少一个都没有。
指望宿主自动兜底,必然会出现「换个宿主或者换个目录,规则就静默失效」的情况。所以我们直接在流程里规定了显式的读取顺序:
- 从目标业务仓 worktree 的根目录开始,一层层往下读到目标修改文件所在的目录;
- 在同一层目录里,先读非空的
AGENTS.override.md,再读AGENTS.md,最后读宿主的备用规则文件(如CLAUDE.md); - 目录层级越深,对同一事项的约定越优先;
- 文件不存在要如实记录「不存在」;如果文件找到了但因为权限或编码读不了,必须报错或记录异常,「找到但读不了」绝不等于「没规定」。
在执行时,只要能按这套优先级算清楚的差异,Agent 直接按高优先级执行,不用每条都停下来问人;只需在输出记录里简短记一笔「采用了哪条规则、来自哪个文件、覆盖了哪条低层规则」。后续做自动代码评审时,评审器也不能拿已经被覆盖的低层规则来误报问题。只有当同一层级、同一作用范围内部自相矛盾时,才把冲突点拎出来交给用户裁决,同时不阻塞其他无冲突部分的推进。
5. 开发中不改正式知识,交付后统一回写
如果允许 Agent 在写代码的过程中随时顺手改仓库里的知识文档,用不了几次迭代,未验证的半成品方案、中途推翻的改动就会把正式 Spec 污染得没法看。
我们的原则很明确:开发授权不等于业务知识的写入授权。
开发期间的隔离
开发过程中如果需求变了,先分清楚到底是「实现写错了要纠错」,还是「需求本身变了」。如果是需求确实变了,开发期间只改本次交付自己的临时 Spec 和技术方案,在里面写清楚改了什么、哪些保持不变、当前采用哪个版本;业务仓里正式的模块 Spec、知识正文和索引文件一概不动。
用户在对话里随口给出的纠正意见,也只是先存为「候选条目」,不会直接写进正式知识正文。反过来,如果在某个任务执行期间外部合入了新写的知识,也不会静默替换当前任务已经采用的依据;确实需要切换依据的,必须明确列出变化和影响范围,走返工或阶段修订流程。
验证通过后的统一回写
等代码开发完、测试和验证全部通过后,才会进入专门的知识回写阶段,把本次交付最终真正生效的变化统一核对落盘:
- 一次预览、分项确认:Agent 把准备更新的条目一次性列出来预览,由人逐项确认。每一项都可以独立选择「写入」「保留本地」或「调整后再定」;如果修改后目标路径或内容发生了实质变化,只需要重新确认受影响的那几项,不用全盘重审。
- 写后回读校验:文件写完后,Agent 会再读一遍落盘的实际内容和 git diff,按 写入、无变化、保留本地、失败 四种状态分别给出明确报告,确保没有写串或静默失败。
PR Review 意见的四类归因
代码提了 PR 之后,Review 阶段的意见是知识迭代最重要的输入,但也最容易被滥用——常见误区是只要 Review 指出一个问题,就往规范文档里加一条禁令,最后规范又变回垃圾桶。
我们要求对每条有效的 Review 意见按四类做归因(每条定一个主因,必要时补一个次因),各回各处:
| 归因类别 | 典型表现 | 处理动作与去向 |
|---|---|---|
| 1. 需求与业务知识 | 需求变更、验收条件遗漏、业务隐性知识缺失 | 开发期间只改本次交付 Spec 与方案;回写阶段统一写回业务仓 docs/ |
| 2. 规则与技术方法 | 编码规范、架构约束、平台限制、实现方法有误 / 缺失 / 冲突 | 提 Issue 修规则:通用的归主仓,业务线特有的归业务线,组件自身的归组件仓 |
| 3. 实现与验证 | 要求其实已经写得很明确,纯粹是这次代码没做到或测试漏覆盖 | 直接修代码、补测试,绝不为一次性的实现失误新增规则 |
| 4. 工具与流程 | 知识存在但没加载、流程步骤漏执行、检查器误报、CLI 故障 | 提 Issue 修加载流程、检查器或 CLI 工具 |
对于纯粹属于个人风格偏好、重复提出、或者核实后不成立的意见,只记录处理结论,不沉淀成规则;根因还没查清的意见,先保留为候选条目并标出证据缺口,不写进正式知识。
在真正动手改知识库之前,还得先查一遍现有知识,对症下药:
- 知识压根不存在 → 补正文;
- 知识早就写了,但这次 Agent 没读到 → 修登记索引、触发条件或加载机制;
- 读到了但没遵守 → 修实现方法或拆分执行步骤;
- 多处文档说法冲突 → 先拍板定下哪份是唯一准绳,再清理其他地方的引用。
6. 知识怎么保鲜
先说清楚一点:我们的知识库没有设「过期时间」。设一个固定天数让文档自动过期,除了制造一堆没人处理的提醒,解决不了真问题。知识保鲜靠两件事:一是随需求迭代更新,在需求开始、代码评审、交付收尾这三个时间点把知识和代码对一遍;二是每周对照代码扫一遍各业务仓库。除此之外,还有两条底层约束兜底:每条结论绑定代码版本,以及一次工作流里用到的知识先冻结。
随交付流程的三个核对点
日常迭代中,知识不是等写完代码才想起来补,而是在三个节点分别和代码、需求做核对:
- 需求开始时核对:只要目标仓库接入了仓内知识,需求阶段就先读这个模块当前的 Spec(读取固定提交上的版本)。每条需求、每条验收标准都要明确说明对现有知识来说属于新增、修改、废弃,还是保持不变。涉及修改的,写清楚原行为、本次行为和怎么验收;同时把这次要保护的不变行为列出来。Spec 和真实需求对不上的地方,在这一步就会暴露出来。
- 代码评审时核对:评审先读本次确认版本对应的模块 Spec,再读交付记录,逐项核对需求范围、原行为和本次行为、代码版本、实际验证和来源。以前的评审通过、缺陷关闭只当作历史证据,不能代替这次评审。评审意见里如果发现「业务知识缺失」,就按第 5 节的四类归因进入回写流程。
- 交付收尾时核对(回写阶段):收尾时对照本次确认的变化准备 Spec 增量,同时保护不变的规则。哪怕这次 Spec 没变,也要检查交付记录;哪怕知识正文没变,也要检查受影响目录里
AGENTS.md的入口链接。
回写阶段的准入门槛卡得很严:前提必须是单元测试结果通过、架构验收通过,并记下实际验证时的代码提交——光是「测试能跑」或者「安装成功」不算验证通过。对于已取消或被替代的方案、没解决的评审问题、没确认的根因猜测、一次性的测试现象,一律不写进正式知识。如果业务方已经自己更新过正式知识,只引用他们的更新记录,不重复写;遇到权限不够或来源读不到的情况,必须如实报告缺口,不能记成「无变化」混过去。
每周定时扫代码仓库
靠需求驱动更新有一个盲区:长期没有新需求去碰的模块,万一有人直接改了代码没走流程,Spec 就会慢慢脱节。
我们的出发点很明确——代码是唯一事实。因此,除了跟需求走,每周还会定时扫一次各业务代码仓库,对照代码检查各仓的业务知识(Spec)。扫描发现和代码对不上的地方,会整理成更新候选,由人确认后才写入正式知识,不自动直接改。这样一来,哪怕长期没有需求碰到的模块,Spec 也会定期和代码对一遍。
版本绑定、工作流冻结与自动索引
为了让上面的核对机制不跑偏,我们在底层加了三条硬性约束:
- 每条结论绑定代码版本:文档的来源精确写到具体的代码提交;跨仓依赖则同时绑定仓库、文档、完整提交和合同版本。读基线时只用已提交的版本,本地没提交的改动单独记录,绝不冒充已提交版本;文档平台上的资料也会记下内容 ID、版本或内容 hash,以及读取时间。以后看到任何一条结论,都能明确知道它是在哪个版本的代码上观察到的。
- 一次工作流里知识保持不变:工作流开始时,会把用到的规则和方法按内容 hash 冻结成快照,执行中途就算外部知识更新了,也不会被悄悄换进来。如果确实要用新版本,必须显式做一次阶段修订:原来的证据保留,同时不能因为正文还在,就默认旧的验证仍然成立。
- 索引不靠手写:方法文档和 Skill 之间的双向索引全部由登记表自动生成,生成的文件头直接注明「改登记表,不改这里」。一旦登记表里有重复或找不到的主题、登记了但文件缺失、或者索引损坏,工具直接报错,绝不静默跳过。
7. 存量仓库还没有知识怎么办
二十多个业务仓库不可能一夜之间全补齐规范和 Spec。面对还没做知识整理的存量老仓,我们的策略是实事求是、不卡研发。
遇到这类仓库,系统会直接标记为 「知识未接入、待回补」,不阻塞开发任务,Agent 照常基于真实需求描述、现有源码和运行验证证据推进开发。但「未接入知识库」不代表老业务没有潜规则——一旦读代码时撞上关键的业务语义缺口(比如某个魔数状态码看不出业务含义),依然必须停下来找人确认,不能瞎猜。同时,「知识未接入」的豁免只针对尚未建档的业务仓;如果是已接入仓库的索引损坏、登记在册的文档丢失或读取没权限,照样严格报错,不蒙混过关。
至于存量仓库的业务知识怎么补,依然回到那句核心认知:代码本身就是知识,平时让 Agent 直接读代码就行。 只有当某个模块需要整理业务基线时,才圈定具体范围从现有代码里反向梳理。梳理出来的内容必须严格区分 已确认、从代码观察到、推断、未知 四种状态——绝不搞全仓自动批量生成文档的运动,落盘写入同样要经过预览和人工授权。
到这里,开发阶段「工程结构怎么摆」和「规则与业务知识怎么喂」这两块底座就搭齐了。有了一套既不撑爆上下文、又不会跟代码脱节的知识加载机制,Agent 才能在二十多个仓库里稳住下限。下一篇(AI-SDLC 实践 07),我们接着聊前端与客户端开发里最直观的一环:D2C(设计稿到代码)在真实业务里怎么跑通。