本文是「Agent-first 大型项目文档分层」系列的第三篇。第①篇把文档体系看成给 Agent 用的路由系统,留下三个问题;第②篇回答了「该读哪几份」,并把放置规则、模板留到了这里。本篇回答第二个问题:去哪找、信哪份。素材仍来自某企业级支付审批系统;这个项目已按本系列的思路做完一轮文档治理,文中「治理前 / 治理后」的数字由同一份脚本在两棵树上量出。
一、搬完 235 个文件之后
9 月 3 日,项目做了一次文档信息架构重整,动了 235 个文件。在那之前,测试资料散在四个地方,plan 根目录下几种分法并列,Agent 找一份文档基本靠猜文件名。重整之后,测试资料合到一处;plan 收成三类:结构化变更 bundle(一次变更的需求、设计、实现记录、用例同放一个目录)、长期专题、早期单文件 plan;文档总入口开头写明先按职责找文档、不再按文件名猜位置(见第②篇)。
位置有了,问题没有结束。
- 编号撞了。 两个变更的编号都是
F-20260909-005:两个目录,同一个号。当时 plan 取号没有规则,也没有校验。 - 迁移也撞了。 9 月 29 日,两条同号的数据库迁移脚本都已经在生产执行,只能搬移返工,事后才立了「取号前先查所有并行分支和 worktree(同一仓库同时检出的多个工作目录)」。
- 包名分不清。 9 月 30 日,一个同名的旧包被误部署,此后包名强制带上时分秒。
- 说法不止一份。 变更目录的 README 声明「不维护第二份状态表」,自己却维护着一份带状态的清单,停在 9 月 22 日。
目录只回答了「在哪一片」。Agent 要找到并信任一份文档,还要知道是哪一份(编号)、还算不算数(状态与替代)、信息在哪一节(模板)。我把这四层合起来叫寻址。
二、症状与根因
寻址失败在这个项目里有五种样子:
- 靠猜。 迁移、bundle、测试报告用「日期 + 英文短名(slug)」命名,早期单文件 plan 和事故报告却是中文长标题,没法用一个模式 glob 出同类文档。
- 同号。 两个目录一个编号,从编号出发的 Agent 不知道该进哪个。
- 一事多处。 状态写在 bundle 头部、索引、目录 README 三处;用例主索引外还有两份人工同步的视图。几处不一致,Agent 只能挑一处信。
- 目录名被读成状态。 早期 plan 放在
legacy/下,字面是「遗留」,很容易被读成「做完归档了」。 - 文档内找不到节。 同一类报告每一版的章节都不一样,找「回滚步骤」只能从头读到尾。
根因只有一条:位置、身份、状态、结构这四样信息,要么只靠约定,要么写在不止一处,要么借别的东西来表达------拿目录名表达状态,拿上一份文档表达结构。人会意会,按字面执行的 Agent 不会:目录叫什么就是什么,上一份长什么样,这一份就长什么样。
三、三条原则
原则 1:按职责分目录,不按类型、不按状态分;做完不挪位置。(对应「能 grep / glob / 跑脚本」)目录只回答「这份文档干什么用」,类型和状态都写成字段。一旦按状态分目录,变更做完就得搬家,所有指向它的引用------别的文档、提交说明、迁移脚本里的注释------一起失效。路径稳定,Agent 才能靠模式而不是靠记忆找到它。
原则 2:一个事实只有一个源,其余都是派生视图。(对应「同时是主要作者」)两份手工维护的副本一定会漂移:这次会话改了 bundle 头部,下次会话未必记得改索引。所以只指定一个源,其余位置要么只放链接,要么由脚本生成。
原则 3:状态写在文档里,不靠目录表达。(对应「按字面执行、不会意会」)状态是有固定词表的字段,替代关系是指向新编号的字段;目录名只表示职责。
再补一句命名:统一命名的理由是机器可匹配 ,不是美观(同样对应「能 grep / glob」)。YYYYMMDD-<slug> 能被一个正则描述,中文长标题不能。
四、机制 1:职责目录 + 放置规则
稳态目录结构如下(节选;「稳态」指新项目第一天就该有的样子,与存量项目接入的区别见机制 6):
text
docs/
├── README.md 文档总入口:按职责分流 + 放置规则
├── overview.md 系统是什么、边界在哪(当前事实)
├── roadmap.md 全局路线图
├── handbook/ 长期有效的规范
│ └── templates/ 每种文档一个模板
├── testing/
│ ├── guides/ 测试规范
│ └── cases/ 全局用例主索引与派生视图
├── deployment/ 当前可执行的部署 runbook(操作手册)
├── plans/
│ ├── index.md 变更主索引
│ ├── YYYYMMDD-<t>NNN-<slug>/ 每个变更一个 bundle,平铺,完成后原地不动
│ └── tracks/<主题>/ 长期专题导航
├── reports/ 执行证据:测试、审计、事故、迁移
└── releases/ 交付物:更新日志、交接说明
两处取舍:reports/ 是 L3 证据、给 Agent 下钻,releases/ 是交付物、给业务用户和运维,所以分开;plans/ 下没有 done/、bugfix/ 这样的子目录,类型和状态都是字段。
每个一级目录的 README 有两节:「导航」给读的 Agent,「放置规则」给写的 Agent。放置规则长这样:
markdown
## 放置规则
| 目录 | 放什么 | 新增策略 |
|---|---|---|
| plans/ 下的 bundle | 一次可交付的变更 | 先取号再建目录;类型与状态写元信息,不拆物理目录 |
| tracks/ | 跨多次变更的长期专题 | 只写导航与关联 bundle 链接,不放 plan、不写状态 |
| 本目录不放 | 执行证据、交付物 | 分别进 reports/、releases/ |
放置规则是给「写」用的路由:Agent 新建文档前读一次目标目录的 README,就知道该落在哪、用哪个模板。
五、机制 2:稳定编号体系
Stable ID 是文档的固定编号:建档时取定,之后不随标题、目录、类型变化而改。编号体系是这套机制里最适合直接抄走的部分:
| 对象 | 编号 / 文件名 | 机械关系 |
|---|---|---|
| 变更 | <T>-YYYYMMDD-NNN ↔ 目录 YYYYMMDD-<t>NNN-<slug> |
两者可互推,首字母由建档时的类型决定 |
| 数据库迁移 | NNNN-YYYYMMDD-<slug>.sql |
全局序号决定执行顺序 |
| 用例 | TC-<模块>-NNN |
模块可从编号读出 |
| 报告等记录类 | YYYYMMDD-<slug>.md |
按日期排序;封板测试报告的 slug 带版本(test-report-vX.Y.Z),可按版本 grep |
| 发布文档 | vX.Y.Z.md / vX.Y.Z-delivery.md |
更新日志与交接说明按版本成对 |
| 发布包 | vX.Y.Z-YYYYMMDD-HHMMSS-dist.zip |
同日多包可区分 |
Agent 手里有 D-20261014-001,不查索引就能拼出 20261014-d001-* 去 glob;手里有目录名,也能反推编号。这一条治理前就做得好:51 个 bundle 里带 Stable ID 的 35 个,目录名与编号 35/35 零错位。
首字母映射有个小坑。通用层推荐 release 用 V(取 version);我们项目用的是 C,来自早期的 chore/release 类型。编号一旦发出就不能改,所以首字母映射由项目层定义,定了不动;新 ID 的首字母由建档时的类型决定,之后类型变了也不改 ID。同理,治理时发现 9 个旧格式的用例编号,处理方式是在接入配置里豁免,而不是改名:Stable ID 的全部价值就在于不变。
取号规则最容易被低估。多个 Agent 在不同分支、不同 worktree 里并行,各看自己那份目录取「下一个号」,撞号几乎必然,开场两次都是这个形状。规则是:
- 取号前扫描所有本地分支、远端分支和所有 worktree,取第一个全局未占用的号;bundle 编号的这一步,治理时做成了一条取号命令(见第④篇);
- 撞号时后占方搬移:目录、编号、所有引用一起改,内容不变,并在迁出记录里写明原号。
迁移撞号代价更高,因为序号就是执行顺序。发布包加时分秒是同一个道理:编号要让「这一份」与「另一份」在机器眼里不可能混淆,同一天出两个包,日期就不够用了。
六、机制 3:bundle 与轻量形态
bundle 的四件套各回答一个问题:
| 文件 | 回答 | 何时写 |
|---|---|---|
| requirements | 要什么 | 建档时;头部带元信息块 |
| design | 打算怎么做 | 批准前 |
| implementation | 实际怎么做、偏离了什么 | 实施中回填 |
| test-cases | 怎么证明 | 与实现同步 |
只定义四件套,现实会自己长出别的文件。治理前 bundle 里有 7 份手工用例、5 份影响面分析、4 份交接文档、十几个阶段分册,甚至还有 .mjs 脚本,规范一个都没定义。治理后改为可选文件白名单:
markdown
| 可选文件 | 何时需要 | 阅读时机 |
|---|---|---|
| impact-map.md | 跨层 / 跨模块影响面大 | design 之后 |
| handoff.md | 交给另一个 Agent 执行或审核 | 执行或审核时 |
| manual-test-cases.md | 有必须人工验收的用例 | 验收时 |
| review-<agent>-YYYYMMDD.md | 独立复审记录 | 审核时 |
| stages.md + 阶段分册 | 分阶段的大型变更 | 进入对应阶段时 |
白名单外的存量文件原地保留、登记豁免(共 14 个);新增白名单外文件一律报错,脚本进 scripts/。
另一头是小变更。治理前有 20 个 bundle 只有一份 requirements,18 个已完成的 bundle 没有 implementation:规范没定义小变更长什么样,回写闭环在这里断开。治理后定义了轻量形态:小范围 bugfix、文档、发版类变更只要 requirements,状态推进到「已实现」时,文档里必须有一节「实施记录」。形态由一个可判定的条件区分:有没有 design。
短期和长期也要分开。 bundle 是短期的:一次可交付的变更,多阶段的大变更也只是一个 bundle 加一份阶段划分。track 是长期的:跨多个独立变更的主题导航,只写为什么做、先后顺序、边界和关联 bundle 的链接,不放 plan、不写状态。第①篇提过,我们的重构专题装进了上百份短期 plan 和一份带状态标记的 roadmap;此外还有 3 项搁置事项没登记索引,roadmap 里的编号和文件名也对不上。在 track 里写状态,就是造了第二个状态源,违反原则 2。
七、机制 4:薄主索引 + 派生视图
主索引只回答「去哪读」,不回答「是什么」。治理后的表头固定六列:
markdown
| Stable ID | Type | 标题 | 状态 | 下一步 | Plan |
|---|---|---|---|---|---|
配套几条硬规则:标题不超过 50 字,下一步不超过 80 字,终态的下一步写 -;Plan 列只放 bundle 入口链接;索引里不许出现日期横幅(以日期开头的进展公告)。版本动态写 roadmap,进度写 bundle。
更关键的是源与投影:bundle 头部的元信息块是状态的唯一事实源,索引是它的投影,两者不一致由检查器报错。这是原则 2 的落点;开场那份停在 9 月 22 日的 README 清单,在这套规则下没有立足之地。
未登记也一样:治理前有一个 bundle 没登记索引,对从索引进门的 Agent 来说它不存在;现在未登记直接报错。
用例索引同理。主表是唯一源,按层级、按模块的两份视图由脚本从主表生成,不许手改。治理前,主表之上堆着按批次写的叙述,叙述里的 ID 不少不在主表;两份视图也各有一批主表里没有的 ID。Agent 从不同入口进来,看到的「全部用例」都不一样。治理后,叙述里的 ID 迁回所属变更,视图改为生成(数字见第十一节)。人看进度,由 Agent 现场汇总或跑脚本生成视图。
八、机制 5:状态机 + 替代链 + 归档
状态词表的每个值,都要对应 Agent 的一种用法。只写「含义」不够,Agent 需要知道读到这个状态之后该怎么做:
| 状态 | 含义 | Agent 用法 |
|---|---|---|
| draft | 讨论中 | 只作背景,不得作为实现依据 |
| approved | 已批准,未实现 | 可作为实现依据 |
| in-progress | 实施中 | 实现时同步回填 |
| implemented | 代码已落地,验证未完整 | 读实施记录与测试记录 |
| verified | 实现与验证均确认 | 可作为当前事实 |
| superseded | 被新变更接管 | 必须跳到 Replaced by |
| deprecated | 不再代表当前行为 | 只用于追溯 |
| obsolete | 已失效 | 不得作为实现依据 |
| cancelled | 决定不做 | 不得作为实现依据,看取消原因 |
治理前,索引里有 completed、done、in_progress 和自由发挥的中文;类型里 bug 和 fix 混用,还有 feature/fix 这样的组合。词表允许近义写法,Agent 就得意会 done 是不是 verified。治理时旧写法由一次性迁移脚本映射到词表,映射表只记在项目层,不进通用层和检查器。
替代链 是一对字段:旧文档写 Replaced by: <新 ID>,新文档写 Replaces: <旧 ID>。Agent 读到 superseded 就必须跳转,不许在旧文档里继续找答案。第①篇说过这条规则空转的原因:字段不在。治理后每个 bundle 都写了 Replaced by,没有就写 none------显式的「没有」也是信息。
最后是归档 ,最容易被用错的一个词。归档只指被替代的历史 ,比如被新的部署 runbook 取代的旧手册:移出当前目录,原位置留下指向新文档的链接。做完的变更不归档,原地不动,状态写在元信息里。理由回到原则 1:做完的变更正是被引用最多的,挪走它就打断所有引用。
九、机制 6:稳态规则 vs 存量接入
从一个项目里抽象通用规范,最容易把项目历史当成通用结构。源项目文档模型规范的通用部分,「推荐目标结构」里画着 legacy/YYYYMM/;审阅中先后指出,legacy/ 和 changes/ 都是接入产物。按日期划界的特例更隐蔽,散落在规则正文和检查代码里。检查代码里的另一例见第④篇。
所以规范要分两种情形写。
稳态 :新项目第一天就按规则建档,没有冻结区,没有日期特例,豁免基线为零。plans/ 下只有主索引、直接平铺的 bundle 和 tracks/;bundle 靠名字模式 YYYYMMDD-<t>NNN- 与 tracks/ 区分,不需要再套一层 changes/。这一层在我们项目里只为与冻结区区分而存在;而且「change」按字面是「修改」,新项目的第一个功能并不是修改任何东西,按字面执行的 Agent 会被名字误导。
存量接入 :中途接入的老项目,需要四个接入件,并且全部集中在一份接入配置里,规则正文和检查代码里不出现任何日期常量或历史路径:
| 接入件 | 作用 | 退出条件 |
|---|---|---|
| 冻结区 | 接入前的旧格式文档,只读不新增 | 被触及时迁为标准 bundle 并标替代关系 |
| 规则生效日期 | 此前建档的对象免检该规则(如编号首字母) | 永久,只对存量生效 |
| 豁免基线 | 存量违规清单与计数 | 只降不升,降到零就删 |
| 历史目录层级 | 已被大量引用、改名代价过高的目录层级 | 随大版本迁移,或永久保留 |
我们项目的 changes/ 就是第四件:它已被 73 个文件引用 564 处,其中 13 份已执行迁移脚本的注释不可改,于是保留,由接入配置声明 bundle 根目录在哪。接入配置的骨架:
json
{
"bundle_root": "docs/plans/changes",
"rules_effective_since": "20261014",
"frozen_dirs": ["<冻结目录>"],
"template_exceptions": ["<接入前不合模板的存量路径>"],
"naming_exceptions": ["<接入前不合命名的存量路径>"]
}
新项目没有这个文件,检查器就按零豁免全量检查。
冻结区的名字要特别小心。冻结区只表示旧格式 ,不表示已完成 ,仍需推进的事项必须登记主索引。legacy 这个词天然把人往「已完成归档」上引:我们的 legacy/202504/ 目录下只有一份文件,文件名以「后续再做」结尾------一件明确没做完的事,躺在一个看起来像「已归档」的目录里。人一眼能看出不对,按字面执行的 Agent 却会把它当成已完成。
十、机制 7:模板 = 文档内寻址
目录和编号解决「文档在哪」,模板解决「信息在哪一节」:章节名固定,Agent 就能直接跳到「回滚与验收边界」,不必通读。
没有模板会怎样,我们有完整的反面记录。第②篇提过,立规时的封板规范关于交接说明写的是「模板照 v2.0.2-delivery.md」:指定一份历史文档当样板,等于把仿写写成了规定,交接说明从 v2.0.3 起就缺了 SHA-256。偏差远不止这一处:回滚章节从 v2.0.1 到 v2.2.0 连续 8 版缺失,v2.2.1 才补回;更新日志从 v2.0.3 起丢了「本版测试」「构建追溯」两节;封板测试报告的章节数依次是 6→3→5→5→5→4→8→6→6→6;事故 5 份、审计 13 份、迁移交接 10 份,几乎每份自创结构。唯一一直稳定的,是交接说明的「交付结果」一节,14 份里 14 份都有。我把这叫仿写漂移:每一代只是「照上一份写」,偏差却一代代传下去。
模板的规则:
- 一种文档一个模板,全部放在同一个模板目录,目录 README 用「类型|模板|适用于|写 / 读」一张表登记;
- 模板头注释声明适用路径 和必含字段,模板的 H2 就是必备章节,顺序固定;
- 模板本身就是 lint 规则:检查器直接读模板,不另维护一份规则清单;
- 新建文档先复制模板、删掉头注释再填,禁止参考上一份同类文档。
交接说明的模板(节选,脱敏):
markdown
<!-- template
applies-to: docs/releases/v*-delivery.md
must-contain: SHA-256;回滚;tag
-->
# vX.Y.Z 制品交接说明
## 交付结果
## 产物与验证
## 发布范围
## 部署顺序与冒烟
## 回滚与验收边界
## 记录
must-contain 里的前两个词,正是仿写漂移里丢过的东西。规则写在模板里,模板改了,检查跟着改,不存在「规范说一套、检查查另一套」。
治理后,文档模型规范从 1123 行的混合体(约 460 行是模板)拆成 252 行的项目层、一份独立的通用层和 31 个模板;模板覆盖全仓 338 份适用文档,没有一份没人管,也没有一份归两个模板管。
十一、治理前后对比
测量口径:治理前取治理分支的起点(10 月 14 日),治理后取治理合入后的状态(10 月 15 日);两棵树由同一份统计脚本逐项量出,可复现。下表只选与寻址相关的行,检查器违规数、入口文件和断链见第④篇:
| 指标 | 治理前 | 治理后 |
|---|---|---|
| plan 索引列数 / 行数 | 8 列 / 56 行,4 行列数错位 | 6 列 / 62 行,0 行错位 |
| 索引行宽(字符)平均 / 最大 | 394 / 1128 | 157 / 227 |
| 状态写法种数 | 9(含错位行里的 done) |
实际用到 6 个(词表 9 个) |
| 类型写法种数 | 13 | 6 |
| 重复 Stable ID | 1 | 0 |
| 未登记索引的 bundle | 1(共 51 个) | 0(共 53 个) |
无 Stable ID / 无 Replaced by 的 bundle |
16 / 35 | 0 / 0 |
| 元信息格式 | 3 种并存 | 1 种 |
| 用例主索引 | 457 行,主表 86 个 ID;叙述里另有 83 个 ID 不在主表 | 169 行,主表 86 个 ID 不变;叙述 0 个 |
| 用例派生视图 | 按层级 204 行(25 个 ID 不在主表)、按模块 248 行(18 个) | 123 行 / 148 行,0 个,脚本生成 |
| 文档模板 | 0 | 31 |
索引变薄不是删了信息:行数没少,变窄的是每一行,进度叙述回到了 bundle。治理前的检查器 ERROR(怎么量、量出多少见第④篇)里,排前四位的都是寻址问题:用例叙述混在主表之前 102、类型不在词表 39、bundle 缺元信息 35、状态不在词表 28。
十二、每类文档放哪、叫什么、信哪份
| 文档类型 | 放哪 | 命名 / 编号 | 事实源 | 派生视图 | 模板 | 人的角色 |
|---|---|---|---|---|---|---|
| 需求 / 设计 | plans/ 下的 bundle |
<T>-YYYYMMDD-NNN ↔ 目录 |
bundle 元信息块 | 主索引一行 | 需求、设计各一个 | 批准 plan,对范围拍板 |
| 实现记录 | 同一 bundle(轻量形态为需求里的「实施记录」一节) | 随 bundle | 本文 | --- | 实现记录 | 确认偏离可接受 |
| 长期专题 | plans/tracks/<主题>/ |
主题名 | 关联 bundle 的元信息 | --- | 专题 README | 对专题优先级与收口拍板 |
| 用例 | 全局用例主索引 + bundle 的 test-cases | TC-<模块>-NNN |
主索引主表 | 按层级 / 按模块(生成) | 用例索引、用例 | 验收时确认覆盖缺口可接受 |
| 数据库迁移 | 迁移目录 | NNNN-YYYYMMDD-<slug>.sql |
脚本本身,序号定顺序 | --- | ---(不是文档) | 部署前确认执行清单 |
| 封板测试报告(L3) | reports/ |
YYYYMMDD-test-report-vX.Y.Z.md |
报告本身 | --- | 封板测试报告 | 封板验收:按证据放行 |
| 事故报告(L3) | reports/ 按月 |
YYYYMMDD-<slug>.md |
报告本身 | --- | 事故报告 | 确认根因,决定是否立规 |
| 规范(L1) | handbook/、testing/guides/ |
固定文件名,通用层 / 项目层成对 | 本文 | --- | 规范文档 | 立规时拍板 |
| 部署 runbook | deployment/ |
按环境 / 主题 | 本文 | --- | 部署手册 | 批准上生产 |
| 更新日志 / 交接说明(交付物) | releases/ |
vX.Y.Z.md / vX.Y.Z-delivery.md |
本文 | --- | 各一个 | 确认交付物 |
| 用户手册(交付物) | 文档根目录 | 固定文件名 | 本文 | --- | 用户手册 | 抽查后确认交付物 |
「派生视图」一列大多是「---」:只在确有多种读法时才建,建了就由脚本生成。交付物不进路由体系,也有模板,因为它们一样会仿写漂移。「人的角色」一列全是批准、拍板、验收、确认:人不需要知道文档放哪、叫什么,寻址是给 Agent 的。
十三、寻址会怎么坏
坏法一:豁免让模板主要管住新文档
存量文档大多在接入前写成,不合模板,只能进豁免。所以模板上线后,管住的主要是新文档,存量要等被触及时再迁。命名豁免也一样:40 个存量文件名不合规则,按原则 1 不挪位置,除非有人迁移,按模式 glob 会一直漏掉它们。豁免清单本该只降不升,「只降不升」靠什么兑现,见第④篇。
对策:冻结区和豁免文件被触及时,顺手迁成标准形态,让清单真的往下走。
坏法二:规则合入前开着的工作,合并时才撞上新规则
v2.3.2 的更新日志与交接说明在 10 月 15 日上午提交到主开发分支,约 30 分钟后,治理才合并进来。写它们的时候,主开发分支上还没有 doc-lint,也没有模板,能参考的「上一份」只有旧格式:登记时沿用旧的八列索引,章节也没按模板。合并时检查报了出来,按模板补齐章节才通过。这不是谁违规,而是规则合入前就开着的工作,合并时才撞上新规则。
对策:治理时已把「新建文档先复制模板、禁止仿写上一份」写进路由表那一行,以及文档模型规范开头的 AI Quick Path;但规则落地前就开出的分支读不到它。合并时重跑检查是最后一道关,这一次就是在那里拦下的。
坏法三:模板过严,逼 Agent 填空话
每一节都必填,Agent 就会为过检查往里塞套话,而套话看起来和真内容一样,裁决者分不出。对策是必备章节压到最少:其余标「(可选)」,不用就删;没内容就写「无」,比一段套话诚实;允许模板外的章节。模板规定的是在哪找 ,不是写多少。
坏法四:适用范围按内容判断
模板检查最初按正文里的字样判断一份文档是不是生成视图、该不该跳过,结果把一份提到了生成命令的设计文档整份漏检,是拿治理计划自己的文档跑检查时才发现的。适用范围是寻址问题,就该按路径判断:模板头注释里的适用路径,比任何正文特征都可靠。工具自身怎么测,留给第④篇。
十四、小结
- 寻址分四层:目录回答在哪一片,编号回答是哪一份,状态与替代链回答还算不算数,模板回答信息在哪一节。少一层,Agent 就只能猜。
- 三条原则:按职责分目录、做完不挪(能 grep / glob);一个事实一个源,其余是派生视图(同时是主要作者);状态写在文档里,不靠目录表达(按字面执行)。
- 编号要机械可互推;取号要扫所有并行分支和 worktree;撞号时后占方搬移、注明原号;已经发出的编号宁可豁免也不改名。
- 稳态规则和存量接入分开写:新项目零豁免、无冻结区;老项目的冻结区、生效日期、豁免基线、历史目录层级全部收进一份接入配置。名字会被按字面理解,
legacy、changes都一样。 - 模板就是文档内寻址,也是检查规则本身;没有模板,Agent 只会仿写上一份。它会坏在:豁免让模板主要管新文档,规则合入前开着的工作合并时才撞上新规则,过严逼出空话,以及按内容而非路径判断适用范围。
系列导航
- Agent 不是失忆,是找不到入口------大型项目文档分层设计(一)
- 让 Agent 只读该读的------文档路由设计(二)
- 让每份文档都有唯一的位置------文档寻址设计(三)(本篇)
- 让文档不烂------Agent 时代的文档生命周期(四)