谈谈最小 Diff 是如何害了文档的,以及解法

全文约 3,957 字 · 预计阅读 8 分钟

摘要：写代码讲究“改动越小越安全”，可把这套思路生搬硬套到文档维护上，往往会让结构积重难返。面对 AI 协作下的新旧矛盾与格式打架，解法之一是把排版交给本地只读工具，把关键结论钉在开头隔离审核。

1. 为什么两句随手加的“补充说明”，能让整篇文档彻底报废？

在代码世界里，“改动行数越少越安全”是一条颠扑不破的铁律，可生搬硬套到项目文档里，它却成了把文档推向混乱的罪魁祸首。写代码时，为了修复一个边界情况，挑出最关键的那两三行打个补丁，既不会破坏现有调用，也不会给代码评审带来额外负担。但项目文档由自然语言组织，有着内在的逻辑脉络与上下文依赖，一旦习惯了用“打补丁”代替重构，文字的结构就会在一次次微小改动中悄然瓦解。面对 AI 时代越来越普遍的人机协作，这种“图省事的改法”正演变成一场灾难：解决文档越改越乱的根本办法，是把排版格式交给本地只读检查工具，把关键结论钉在文档开头，并由人工把关“四个核心”。

这个教训来自一次令我心力交瘁的真实翻车。当时为整理过往项目经历，我反复拿网页端的大模型修改同一篇功能设计文档。几个轮次修改下来，当我把导出的文档放进编辑器通读时，才惊觉正文里竟然同时并存着三套自相矛盾的实现方案：一段写着采用方案 A，紧接着一段用加粗字体注明“现已改为方案 B”，末尾又轻飘飘附上一句“注意：因接口调整，请直接参考方案 C”。不仅如此，翻开旧知识库时，大半关键引用因为位置挪动而纷纷弹出 404 失效报错。那一瞬间，面对一堆看似完整实则真假难辨的文字废墟，排查修复的阻力甚至超过了重写代码。

图：混乱的文档现场截图-1。

图：混乱的文档现场截图-2。

文档之所以迅速退化，根源在于混淆了代码补丁与文档结构的本质差异。代码是给编译器看的，只要语法合法、逻辑跑得通，函数放在哪里都能正常跳转；但文档是给人以及后续接手的 AI 理解的，它的可信度建立在全局叙述的前后一致上。当维护者为了追求所谓的“最小改动”，舍不得重写旧章节，只想让 AI 在末尾追加两句说明时，文档的逻辑链条就已经断裂了。

2. 直觉误判一：写代码讲究“最小改动”，为什么写文档反而成了坏习惯？

为了省事而保留不合理的旧章节，是让文档沦为“补丁堆”的第一步诱因。每次需求迭代或架构微调时，很多人为了不破坏原文排版，下意识的做法就是让 AI“在文末补充一段注意事项”，或者在旧结论旁边硬生生插上一句“注：以下内容已废弃”。这种偷懒的做法看似把眼前的改动降到了最低，实际上却把最沉重的理解负担推给了后来的读者。旧表述留得越多，上下文里的噪音就越大，后来的阅读者不得不一边通读、一边在脑海中人工比对哪句话才是最新事实，原本顺畅的阅读变成了疲于奔命的“考据”。

残留的过期表述不仅折磨阅读者，还会直接把后续接手的 AI 带进沟里。大语言模型的本质是根据上下文预测下文，它的逻辑推理极度依赖前文事实的一致性。当一篇文档里同时塞满了“过去怎么做”和“现在怎么做”时，AI 根本没有明辨是非的神通，反而会顺着那些被废弃的陈旧细节展开联想，煞有介事地把新旧做法杂糅在一起，胡编乱造出完全不可行的折中方案。我原以为保留旧文字是留下一条历史线索，但在 AI 眼里，那些早已失效的陈词滥调全是它用来产出下一段荒谬幻觉的合法素材。

要拔掉这颗毒瘤，首要之策就是强制结论前置，在文档开头立下一目了然的硬契约。我在实践中推行了一套规则：任何重要文档的最上方，必须包含一个由 YAML frontmatter 构成的卡片，明明白白写清“四个核心”——读者是谁、用途是什么、正文包含哪些范围、坚决不碰哪些范围。把这些总领全局的结论牢牢钉在最顶端，无论是人工点开文档还是 AI 载入上下文，一眼扫过去就能把控文档的适用边界，人工审阅的阅读负担也因此大幅降低。更重要的是，有了开头这面镜子，拿四个核心与正文相互对照，正文哪里跑了题、哪里在打马虎眼，全都会暴露无遗。这种对照机制能够直接促使维护者痛下决心整段重写，从根本上阻断了无休止打补丁的侥幸心理。

与此同时，必须通过规范把“修改开头核心”与“修改正文细节”在流程上拆成两步独立操作，杜绝偷梁换柱。在日常人机协作中，AI 常常会为了“圆谎”而在重写正文的同时，自作主张修改开头的核心定义。为此我定下了一条高压线：AI 在修改正文时，绝对禁止顺手改动开头的四个核心；如果事实真的发生漂移、确实需要重构核心定义，必须先停下工具，单独由人工审核确认之后，才能开启下一阶段的写作。用流程上的物理隔离，把文档最重要的方向牢牢锚定在高可信基准线上。

图：YAML frontmatter 四个核心结构示意。

文档维护要守住的是前后一致的结论。先在开头明确读者、用途与范围，再据此重写失效段落；涉及这四个核心的变化，必须单独由人工确认。

3. 直觉误判二：以为自动修复省时省力，结果工具“左右互搏”还改坏了源文件

试图让工具在保存时自动修复格式，是我在自动化治理中踩过的最痛的一个坑。很多做开发的朋友习惯了在 IDE 里配置“保存时自动格式化”，觉得格式问题既然有了统一规范，交给工具直接在原地修改源文件（诸如开启 --write 或 --fix）必然是最优雅的解法。我在早期也抱有这种天真直觉，甚至想过直接挂一个大模型 API 来实时诊断纠错，以为这样就能一劳永逸。

然而现实很快给这种偷懒的直觉泼了一盆冷水：自动化工具不仅可能彼此打架，还会把文档改得面目全非。首先，大模型的输出存在概率波动，同样的语病这次能挑出来，下次可能视而不见，根本无法作为非黑即白的阻断底座；其次，不同的排版工具在底层规则上存在无法调和的冲突。在我的实际排查中，格式化工具 Prettier 默认会把独立的斜体强行输出为下划线形式（_文字_），而 Markdown 结构检查工具 rumdl 却偏偏要求斜体必须统一为星号（*文字*）。两个工具一旦同时开启自动修复，就会在同一个单词上陷入你改过来、我改过去的无限“左右互搏”。更离奇的是，Prettier 还会自作聪明地把正文代码块里故意写出来的“反面错误示范”当成不合规语法自动“修平”。自动化脚本甚至一度误伤过代码仓库里的历史文件，逼得我不得不手忙脚乱地用 Git 回滚救火。

碰壁之后我得到的深刻教训是：面向文档的检查流水线，必须坚持“只动嘴不动手”的本地只读原则。检查工具只负责指出具体的报错行号与原因，绝对不允许它们直接触碰和改动原文件；整套检查流水线完全在本地离线运行，不依赖任何外部网络。面对 Prettier 与检查工具在斜体上的死锁，我没有因噎废食地直接关掉 Prettier——因为那样会彻底丢掉中文宽表格对齐与缩进规范化的能力——而是写了一个仅有 22 行的本地小插件，直接拦截 Prettier 的打印输出，强行把下划线还原为星号，并彻底关闭对代码块内容的内嵌格式化，让所有工具在边界上安分守己。

为了既能享受自动排版的便利，又不至于被不稳定的格式改坏文件，我引入了严格的二次排版验证与隔离预览机制。系统在后台调用格式化生成预览副本时，会像做考卷一样进行二次验算：如果拿第一次排版出来的结果再去排版一次，文本内容发生了哪怕一个字节的变动，就说明当前排版存在不稳定逻辑（例如复杂的嵌套列表缩进在二次折行时会漂移）。遇到这种情况，门禁会立即判定为故障并直接报警隔离，坚决不把不稳定的排版结果推给用户；所有通过检验的修复建议，也会在独立的比对窗口里呈现，供人工审查，审查时由维护者自己决定是否合入。让机器负责挑刺，让人始终能重新接管修改流程，才是工具链安全的底线。

图：只读比对窗口截图。

图：格式化工具冲突报错。

格式检查的确定性，要靠本地只读、规则兼容和二次验算共同保证。工具负责报告问题、生成稳定的预览副本，流程保留必要时暂停排查的能力；经过反复使用、没有发现问题后，可以让 Agent 自动推进。

4. 直觉误判三：给 AI 看的指引文件，为什么写得越像“大百科”越没用？

给 AI 编写的指令文件若陷入“巨细靡遗”的误区，往往会把原本聪明的模型拖入茫然失措的境地。很多项目在根目录下维护 AGENTS.md 时，恨不得把整套代码仓库的所有目录树、历史架构变迁、长篇大论的部署流程一股脑全倒进去。我在起步阶段也犯过同样的毛病，以为信息给得越全，AI 就越能理解全局，结果整篇指引臃肿得像一本包罗万象的百科全书。

这种“大而全”的做法带来的直接恶果，就是严重稀释了 AI 的注意力空间，让核心行动指令彻底失效。大模型在处理过长上下文时，注意力的衰减是客观存在的工程规律。当几千字的目录说明和低频架构细节占满了宝贵的上下文窗口时，写在角落里的核心构建命令和红线约束反而会被模型完全忽略。实际运行中，AI 依然频繁跨目录乱翻文件、遇到报错不知所措，甚至照样去踩那些我以为“早就写明了”的禁区。

这个痛点并非孤例，翻看 GitHub 上数万 Star 的顶级开源项目，也能得到充分印证。去研究 Next.js、Kubernetes、Rust 以及 VS Code 等知名开源仓库中的代理指引就会发现，成熟的大型项目根本不会把 AGENTS.md 写成代码说明书：它们无一例外把目录全景压缩成清晰的“职责地图”，只标出核心入口；构建与测试命令高度分层，改哪部分就给哪一条明确命令；而规则全部写成“禁止做什么 + 可以用什么替代”的刚性闭环。这些顶级仓库的事实证明，AI 需要的是可执行的操作路由，而不是事无巨细的架构宣讲。

经过反复碰壁与行业验证，我彻底推翻了百科式的写法，把面向 AI 的指引收敛为极简的行动三件套：职责地图、分级命令与替代方案。首先，大段大段的目录树被彻底砍掉，只保留核心文件夹对应的一句话职责说明；其次，放弃抽象流程叙述，针对“改文档”和“改脚本”分别给出可以一键复制执行的验证命令，让模型明确知道改完之后跑哪条命令自检；最后，在制定禁止行为时，坚决摒弃苍白的说教，必须严格采用“禁止做什么，以及你可以用什么替代”的双向结构。把百科全书改成可执行的行动手册，AI 在仓库里的动作才算真正有了准绳。

AGENTS 的价值在于快速路由：到哪里找、改完怎么验证、遇到限制用什么替代。把职责地图、分级命令和替代方案写清楚，比继续堆积低频背景更有用。

5. 收束行动：心里一块石头落地，以及 3 条可直接照抄的清单

当这套双层防线完整跑通之后，日常写作和人机协作中的心理负担很快就减轻了。以前只靠一句单薄的提示词让 AI“帮我审审这篇文档”，心里永远提心吊胆，生怕它悄悄改坏了什么细节，改出来的文字自己也缺乏信心去细看。如今，杂乱的格式、全角半角、英文空格与潜在死链，全部被底层的只读检查工具挡在了门外；而整篇文档的核心立意与边界，又在开头由人工死死把守。不需要再拿肉眼去盯错别字和缩进排版，审阅流程分层解耦，长期萦绕在心头的心理负担终于彻底放下。

图：双层防线极简架构示意图。

如果你也深受文档越改越乱、新旧说法互相矛盾的折磨，不妨把这套思路压缩成以下 3 条可立即落地的行动小抄：

• 开头定规矩
  ：在关键文档顶部统一置顶包含“读者、用途、范围、不碰范围”的四个核心卡片，正文任何变动只要触碰这四条基准，必须停下由人工前置确认；
• 工具只动嘴不动手
  ：排版与格式检查完全在本地离线只读运行，绝不允许工具擅自改动源文件，排版预览必须通过二次验算，流程在必要时能暂停排查；经过反复使用、没有发现问题后，可以让 Agent 自动推进；
• AI 指引只留行动
  ：给 AI 的协作文档扔掉长篇目录树与架构百科，只保留“目录职责、怎么验证、碰壁后有什么替代方案”。