夜雨聆风本文主要依据是 Anthropic 2025–2026 年公开的官方工程文章（context engineering、Agent Skills、长跑 agent 的 harness 设计、Claude Code 系统提示削减 80%），并参考同期业界公开资料与研究，出处见文末。
0. 结论
设计文档在 AI 时代的定位变了，变化有两层：
第一层（形态）：Markdown 文档是源码，Word / PPT / PDF 都是从源码渲染出来的构建产物——Office 文档成了新时代的 PDF。
第二层（更要紧的一层）：文档不再只是"给人看的说明"，它已经变成可被 AI 按需加载、直接决定 AI 干活水平的能力单元。这不是推演——Anthropic 官方把这件事做成了产品机制（Agent Skills：一个装着 Markdown 的目录，就是 agent 的一项能力），并在 2026 年 7 月宣布删掉了 Claude Code 系统提示的 80% 以上，把腾出来的空间交给按需加载的文档。模型越强，写死的规则越贱，策展好的文档越贵。
下文分三部分：官方事实与原理（§1–§6）、对底层软件与软硬件协同团队的特殊含义（§7）、业界现状与边界（§8–§9）。
1. 背景
起点是一个很实际的困惑。公司里写设计文档，历来是 Word 写完、Confluence 存档。但到了 AI 时代，这套做法越来越别扭：AI 助手读不到、也改不了这些文档；二进制格式没法 diff、没法进 PR 评审；文档和代码各存一处，改代码的人永远想不起来去同步文档。问题的症结其实不是"AI 看不懂 Word"——Word 是 zip 包加 XML，AI 提取文字毫无压力——而是这套形态把版本管理、评审流程、AI 读写、自动化整条工程链路全部切断了。Confluence 也类似：它 2025 年就推出了官方 MCP Server，AI 不是读不到[^3^]，问题是文档被关在代码库之外，注定和代码越漂越远。
从工程实践自下而上，答案早就清晰：用 Markdown 写文档、放进 git 仓库贴着代码，HTML / docx / PDF / PPT 都只是渲染产物。真正的新消息在另一头：做模型的那家公司，已经把"文档"提升成了系统的一等公民。 这不是理念呼应，是产品机制、是官方实测数据（§2）。两股道理在半山腰汇合，指向同一个结论：
文档正在被重新定义为"给人和 AI 共同消费的、可版本化、可按需加载的上下文基础设施"。
2. 事实层：模型厂商自己是怎么做的
这一节全部是可核实的官方事实，不是推演。如果按时间顺序来看，它们连起来是一条很清楚的曲线。
2.1 上下文是有限资源，不是越多越好
Anthropic 2025 年 9 月的官方文章给出了这一代 agent 工程的核心命题："上下文必须被当作一种边际收益递减的有限资源"（"Context, therefore, must be treated as a finite resource with diminishing marginal returns."）[^1^]。
理由很硬：Transformer 里每个 token 都要和其他所有 token 建立注意力关系，n 个 token 就是 n² 组关系，而训练语料里长序列本来就少。结果是模型有一份"注意力预算"（attention budget），你塞进去的每一个 token 都在花它——token 越多，模型准确召回其中信息的能力越低，所有模型都有这个衰减，只是幅度不同。业界给它起了个很形象的名字：context rot（上下文腐坏）。
由此得出的工程原则是一句反直觉的话：目标是找到"能最大化达成目标概率的、尽可能小的一组高信号 token"（"the smallest possible set of high-signal tokens"）[^1^]。注意——最小不等于短，是信噪比最高。
这一条就是全文的地基：如果上下文是一块有限、且越用越钝的内存，那么"往里装什么"就不再是文档质量问题，而是系统性能问题。写文档从此有了工程意义。
2.2 官方产品机制：一个装着 Markdown 的目录，就是 agent 的一项能力
2025 年 10 月，Anthropic 推出 Agent Skills，并在同年 12 月把它作为开放标准发布[^2^]。它的定义值得逐字看：
"organized folders of instructions, scripts, and resources that agents can discover and load dynamically" （由指令、脚本和资源组成的、agent 能自行发现并动态加载的有组织文件夹）
技术上简单到近乎朴素：一个 skill 就是一个含 SKILL.md 的目录，文件开头是 YAML frontmatter，两个必填字段——name 和 description。而它的加载方式是整套设计的精华，叫 progressive disclosure（渐进式披露），分三层：
| 启动时常驻 | ||
SKILL.md 正文 | ||
reference.md / forms.md …） |
三层设计带来一个漂亮的结论：因为有文件系统和代码执行，agent 不必把整个 skill 读进上下文窗口，所以"一个 skill 能承载的上下文量实际上是无上限的"[^2^]。
请把这句话读两遍。 上下文窗口是有限的（§2.1），但挂在文件系统上、按需加载的文档体系是无限的。这就是"文档即源码"在 2026 年最硬的技术依据——它不再是一个类比，而是官方产品的实现方式：你写的 Markdown 目录，就是 agent 的能力单元；写得好，它多一项本领；写得烂，它多一份噪声。
顺带一个细节很能说明问题：官方建议长 skill 要拆成多文件、组织成一棵可按需加载的文件树。这跟组织一个源码目录是同一件事——模块化、单一职责、按需 include。
2.3 官方实测：模型变强，规则该删而不是该加
2026 年 7 月 24 日，Anthropic 发布了一篇很反常识的文章：他们为 Claude Opus 5 / Fable 5 这一代模型，删掉了 Claude Code 系统提示的 80% 以上，在自家编码评测上"没有可测量的损失"[^3^]。
为什么能删？官方的自我批评很直白——过去是在"过度约束"（overconstraining）Claude。翻内部记录时发现，同一个请求里的指令在互相打架：一边写着"适当保留文档"，一边写着"绝对不要加注释"，模型得先花力气判断该听谁。那些护栏当年是为了防最坏情况，现在模型判断力够了，护栏本身反倒成了噪声。他们管这个动作叫 unhobbling——不是给模型加能力，是把当年给它套上的镣铐解开。
同一篇文章给出了新旧规则对照，几乎每一行都在把"塞进去"换成"按需取"：
| 渐进式披露 | |
而关于"你自己的项目文档该怎么写"，官方给了一条极具体、也极容易验证的建议：
把大部分 token 花在"代码库里的坑"上（"spend most of the tokens on gotchas inside of the codebase"）； 避免陈述那些 Claude 看一眼你的文件系统或仓库就知道的"显而易见的事"。
这一条几乎是一把尺子，可以直接量你现在的 CLAUDE.md / AGENTS.md：里面有多少内容，是模型 ls 一下就能知道的？ 那些就是纯噪声，占着注意力预算不干活。
2.4 AI 也需要"交接班文档"
最后一件事最有画面感。Anthropic 讲长跑 agent 的官方文章里，用了一个类比：让 agent 做一个跨越很多次会话的项目，等于"一个项目由轮班的工程师完成，而每位接班的人都不记得上一班发生了什么"（"each new engineer arrives with no memory of what happened on the previous shift"）[^4^]。
他们试过只靠自动压缩历史（compaction），结论是不够："compaction isn't sufficient"。两种典型翻车：一是想一口气做完，上下文中途耗尽，留下"一个做了一半、还没写文档的功能"；二是后来的 agent 环顾一圈，看到已有进展，就直接宣布任务完成。
最终有效的方案，是让 agent 像真正的工程师那样交接——官方明确说灵感就来自"高效工程师每天都在做的事"：
一份可端到端验证的特性清单（claude.ai 克隆案例里超过 200 条，每条形如"用户能打开新会话、输入问题、回车、看到回复"，初始全部标记为未通过）； 一份 claude-progress.txt进度日志；- git 历史
（可回滚、可看最近改了什么）； 一个 init.sh，一键起环境——省掉每次会话重新摸索怎么启动的开销。
而每次新会话固定三步开局：pwd 确认位置 → 读 git log 和进度文件 → 读特性清单挑最高优先级的未完成项。会话结束前，要把代码库留在下一个人能直接开工、不用先清理烂摊子的状态。
一个耐人寻味的细节：特性清单用 JSON 而不是 Markdown，理由是经验性的——模型改写 JSON 的倾向更低，不容易手滑把验收标准自己改掉。这说明连"用什么格式存哪类信息"都已经是工程决策了。
这一节的意义：过去我们说"文档是给人看的"。现在，验收标准、进度、启动方式、变更历史——这套东西第一批读者已经是 AI 了。它们不再是项目管理的附属品，而是 agent 能不能接着上一班干活的运行时依赖。
2.5 一个更早的框架：为什么这条曲线是必然的
上面四件事都是最近一年的。而它们指向的方向，早在 2025 年 6 月就被 Andrej Karpathy 在 YC 的演讲里点出了框架[^5^]：他把 LLM 类比成一台新型计算机——LLM 像 CPU，上下文窗口就是内存（RAM），并提出软件要开始为 agent 这类新读者而设计（"Build for Agents"）：给出 Markdown 形态的文档、把"点鼠标"换成可编程接口。
这个类比今天读依然好用，而且被上面的官方实践填满了细节：如果 context window 是 RAM，那 §2.2 的 progressive disclosure 就是分页调度，§2.1 的 attention budget 就是这块 RAM 越用越慢，§2.4 的进度文件就是把状态写回外存。
同一场演讲里还有一个类比，是理解"为什么必须写文档"的最短路径：LLM 有顺行性遗忘症——学识超过任何个人，但每次会话结束就忘干净。§2.4 那个"轮班工程师"，其实就是这条缺陷在工程上的正脸。
3. 原理一：MD 文档即源码
"MD 文档即源码"这句话，不是说"文档很重要"，而是说：文档从此适用软件工程的全部纪律。源码有五条定义性性质，AI 工作流里的 MD 文档五条全占：
- 唯一事实源
——产物由它生成，而不是反过来； - 版本化
——可 diff、可追溯每一行是谁改的； - 接受评审
——和代码走同一个评审流程； - 有构建流水线
——格式检查、死链检查、渲染导出，相当于编译； - 手改产物是无效改动
——直接改 Word / PDF 而不改 MD 源，等同于只改编译出的二进制文件不改源代码：下次构建就被覆盖，没人维护得了。
反过来说，Word 文档在这个模型里不是"另一种源码语言"，它的处境更尴尬：只有二进制，没有源码。 一个只能拿到 .exe、丢了工程文件的项目会怎么样，你已经知道答案了——这就是 Word 设计文档注定腐化的全部原因，跟谁写的、写得多认真无关。
这套定位有一句更通俗的说法："Office 文档是新时代的 PDF"——它们是交付与呈现的终点，不是协作与生产的起点。这也正是 docs-as-code 的核心思想：源文件纳入 git，可 diff、可评审、可 CI 检查；对外交付时一条命令渲染成 docx / PDF，汇报时让 AI 从 MD 生成 PPT。构建产物随时可以重新生成，所以从不需要"维护"——就像没人会去手工编辑编译出来的 .o 文件，要改就改源码、重新编译。 HTML 同理：它不是书写格式，只是渲染目标之一——写完 MD，网页、文档、幻灯片都是它的编译输出。
为什么文档突然配得上"源码"这个地位？三个比方：
比方一：LLM 是一个"每天都是第一天上班的天才员工"。 它有顺行性遗忘症（§2.5）——学识超过团队里任何人，但一觉醒来把你的项目忘得干干净净，昨天讲过的坑今天还要再踩一遍。这不是比喻，Anthropic 自己就是用"每班工程师都不记得上一班"来描述它的（§2.4）。带这样一个人，口头交代等于没说，唯一的办法是把一切写成他每天上班十分钟能读完的东西。你的文档体系，就是这位天才唯一的管理抓手——也是你昨天那番话唯一能活到今天的形式。
比方二：含糊的文档，等于给编译器喂"未定义行为"。 同一份含糊的需求，两个程序员会实现出两个东西，但他们会在评审会上吵起来，吵着就把歧义吵明白了。AI 不吵——它在每个语义空位里默默填一个"看起来合理"的东西，不报错、不提醒、不留痕，而且下次可能填另一个。同一份含糊文档，换 GPT 换 Claude，"编译"出两种架构，两边都自称按文档做的。歧义在人那里会变成争论，在 AI 那里直接变成实现。
比方三：文档和代码的上下游关系反转了。 以前，代码是事实，文档是事后描述——写完就开始腐化；现在，文档是意图，代码由 AI 按文档生成、按文档校验。一句话：
以前是 code is the truth, docs describe it（代码即真相，文档描述它）； 现在是 docs are the truth, code derives from it（文档即真相，代码源自它）。
最本质的一层：源码的定义性特征，是"同时面向机器和人两种读者的单一制品"——编译器消费它，维护者阅读它。MD 文档恰好也是：AI 消费它，人评审它。Word 只有人一种读者。所以"MD 文档即源码"不是修辞，是结构同构。
4. 原理二：为什么"把 prompt 写好"是一条走不远的路
很多团队学 AI 的第一站是"提示词技巧"，然后就卡在那里了。用一句计算机科学的老话（Niklaus Wirth 的经典书名）能说清卡在哪：
Algorithms + Data Structures = Programs（算法 + 数据结构 = 程序） AI 版本：Prompt + Context = 结果（指令 + 上下文 = 结果）
- Prompt 是指令流
：这次让 AI 干什么。一次性的、会话级的、说完就散。 - 文档是数据段
：AI 干活时手边的知识库——系统长什么样、约束是什么、坑在哪。持久的、跨会话的、能被版本管理的。
只有指令没有数据，程序跑不出你要的结果。 这解释了一个到处都在发生的困惑：同样用 Claude、同样一句"帮我改这个模块"，为什么在有的团队里出活、在有的团队里出事故？差的不是提示词，是数据段。
而两者的杠杆完全不在一个量级：prompt 决定这一次会话的行为，文档决定所有会话的行为。 prompt 是局部变量，随手写、写完就丢；文档是全局状态，必须进版本控制。更要紧的是趋势——§2.3 那 80% 的删减说明了什么？厂商正在亲手把"提示词技巧"这门手艺贬值掉：模型每强一代，写死的规则和精巧的话术就被吸收一批。所以正确的投资从来不是"把 prompt 写好"，而是把文档体系建好——让任何一句平平无奇的提问，落在高质量的知识底座上，都能得出正确的行为。
5. 原理三：模型变强，会吃掉什么、吃不掉什么
这是所有管理层最该问的一个问题：这些投入，会不会明年就被更强的模型作废？
答案是：一部分一定会，而且已经在被吃掉了；另一部分永远不会。 分界线非常清楚。
会被吃掉的：一切"替模型做判断"的东西。 提示词套路、few-shot 堆砌、多角色扮演、写死的步骤清单——这些当年都是在弥补模型笨。§2.3 就是官方亲手示范：模型强了一代，80% 的规则直接删掉，效果不降。你越是把功夫花在"教模型怎么想"，被通胀掉的速度就越快。
吃不掉的第一样：你的私有事实。 模型再强，也不知道你这块板子的寄存器怎么定义、你的接口为什么留了那个奇怪的对齐、三年前那个方案为什么被否决。这些永远不会进入任何人的训练语料——它们只存在于你的仓库、你的会议记录、和几个老员工的脑子里。这是唯一不随模型进步而贬值的资产，而且随时间复利。
吃不掉的第二样：确定性的边界。 官方那篇 harness 文章的经验很说明问题：让 agent 自己判断"功能好了没有"，它会宣布完工；改成必须跑通一份不许改的验收清单，才真正可靠（§2.4）。判断可以交给模型，裁决不能。 到了硬件场景，这条边界更是物理性的（§7）。
有一个必须摆出来的反面证据，防止把"文档重要"读成"文档越多越好"：ETH Zurich 的研究发现，自动生成的、面面俱到的 agent 上下文文件反而降低任务成功率，还多花约 20% 推理成本[^6^]。这跟 §2.1 的注意力预算、§2.3 的"别写显而易见的事"是同一件事的三个说法。
所以结论收得很紧：context 不是越多越好，策展质量才是胜负手。 文档要写得准、写得薄、只写代码里看不出来的东西——而这恰好是资深工程师最不可替代的那部分工作：判断什么是坑、什么是显而易见、什么必须留痕。AI 能帮你写，但没法替你判断哪句值得写进去。
还有一条推论，是"文档即源码"这个类比里最容易被漏掉的一半：源码要重构，文档也要。既然文档是源码，它就同样会积累技术债——而这里的债不是难读，是每一条长期规则都在占用模型有限的决策注意力。所以出了问题时，动作不能只有"再加一条规则"这一种，应该有五种：保留、改写、合并、移到正确的层、删除。删除也要留痕：记清这条规则原本防的是哪个失败、为什么失效（模型已经覆盖了 / 从来没被触发过 / 已经由工具或测试接管了）。新增和删除的举证责任是对等的——一个只许加不许减的反馈环，最后一定长成那种没人敢删、也没人真读的文档：每条都曾经有道理，合起来谁也说不清该信哪条。
6. 汇合：每条"老经验"，现在都有了更硬的理由
回头看，前面说的是同一件事的几个侧面：文档是 AI 干活时的数据段（§4）；是它唯一的长期记忆（§2.4、§3 比方一）；是可按需加载的能力单元（§2.2）；也是"AI 生成、人验证"这个循环里，人用来判断对不对的那把尺子。合起来一句话：文档从"写完归档的交付物"，变成了"持续维护的、人和 AI 双读者的上下文基础设施"。
这套框架真正的价值在于：那些凭工程直觉得出的"老经验"，现在每条都能指到官方依据：
7. 底层软件 / 软硬件协同场景的特殊性
互联网团队的 AI 实践不能照搬到这个场景。先给管理层三句话版本，再展开：
- 推论一
：我们的"验证器"在物理世界，AI 自主性的上限被验证速度锁死——与模型强度无关。导航软件再聪明，也不能替监理上门验房。 - 推论二
：模型通晓天下事，唯独不知道我们这块板子的寄存器怎么定义、三年前那个决定为什么这么定——这些永远不会出现在任何训练语料里。文档体系的质量，就是 AI 在我们项目里的智商上限：全球最强的模型，在一个没有文档的仓库里，也只是个聪明的实习生。 - 推论三
：NDA 与安全边界是结构性的，不随模型变强而消失。
7.1 四个结构性差异
- 事实源是 PDF 且常带 NDA
。datasheet、寄存器手册、协议规范、errata 是原厂 PDF——AI 可以读 PDF，但几百页的扫描表格不是稳定的上下文；且保密资料不能进云端模型（见 7.4）。 - 验证必须上真机，AI 无法自闭环
。互联网场景 agent 跑个测试就验证了；这里的验证是编译→烧录→跑流量→看计数器/示波器——每一步都在 AI 够不到的物理世界里。能放给 AI 多少，从来不由模型多强决定，而由"你多快能确认它没错"决定——这条链子有多长，天花板就在哪。 - 精确性极端，而这恰是模型的高风险区
。寄存器位定义、掩码、内存序、DMA 描述符格式、ABI 对齐——错一个 bit 就是莫名 hang。模型在"写代码逻辑"上远超常人，在"从 PDF 表格里准确抄 40 个寄存器偏移"这种事上偏偏不可靠：它的能力是锯齿状的，而我们的雷区正好在锯齿的低谷。 - 代码库超大、生命周期超长
。数万文件的仓库，agent 单会话根本吃不进去——注意力预算（§2.1）在这里不是理论，是每天都会撞到的墙，必须靠索引 + 文档做"寻址"；项目活十年，文档与代码漂移的代价被时间放大。
7.2 文档三层模型：把官方那套按需加载，套在自己的 PDF 和老仓库上
┌─────────────────────────────────────────────────────────┐
│ 层 3：交付产物（生成物，不维护源） │
│ docx / PDF / 评审 PPT / 对外文档 —— 从层 2 渲染生成 │
├─────────────────────────────────────────────────────────┤
│ 层 2：结构化知识（git 仓库内，AI 可读可写） │
│ 设计文档 MD / 决策记录 ADR / mermaid 流程图 / │
│ 结构化的寄存器与接口定义 / 术语表 / 勘误提炼笔记 │
├─────────────────────────────────────────────────────────┤
│ 层 1：事实源（保持原样，只做"提炼 + 指针"） │
│ datasheet PDF / 协议规范 / errata / 邮件与会议纪要原始件 │
└─────────────────────────────────────────────────────────┘操作规则：
- 层 1 不进 AI 正文，进"提炼层"
：把 datasheet 的关键章节提炼成 MD 笔记，每条结论带指向 PDF 页码/章节号的引用——AI 消费提炼层，人随时可以回查事实源。这是防止它抄错寄存器值的制度性保险：错可以有，但必须一眼能查回去。 - 层 2 是唯一被"维护"的东西
：和代码同一个仓库、同一个评审流程。 - 层 3 永远从层 2 生成
：任何人手工改交付产物都视为改 build artifact——下次构建即被覆盖。
这三层不是本文的发明，它和 §2.2 那套官方机制是同一个形状：元数据常驻、正文按需、细节更深一层才读。 换句话说，底层软件团队要做的不是另建一套，而是把这套按需加载的结构，套在自己那堆 PDF、勘误和十年老仓库上。
7.3 放手到哪一档：按验证方式，而不是按模型强弱
同一个模型，在这三类任务上该给的自由度完全不同——分界线画在"错了多久能发现"：
| 必须真机验证 |
既然天花板由验证速度决定，投资方向就很清楚：别再想办法让 AI 写得更多，去让验证变快——结构化文档、可 diff、小步提交，把仪器输出（计数器、性能文本）喂回给 AI 让它帮你读，而不是指望它替你举示波器。
这里还藏着一条反直觉的推论：任务不能拆得太细。 互联网场景鼓励小步提交，是因为那里每一步验证近乎免费；而这里每验证一次都要占硬件、跑长构建、等人回灌——切得越碎，验证次数越成倍增长，最后是人被拖死，不是 AI。所以粒度不是越小越好，而是取"一个独立可验证的功能点"：小到一次验证能覆盖，大到不必为它多跑一轮硬件回归。在验证免费的地方切得越碎越安全，在验证昂贵的地方切得越碎越危险——这是照搬互联网实践最常翻车的一处。
7.4 安全边界
- NDA / 机密 IP 不进云端模型
：datasheet 提炼笔记只写已公开或已脱敏的内容；涉密部分留在内网。 - 提示注入是新攻击面
：errata、外部邮件、第三方补丁描述喂给 AI 时，都可能夹带指令性文本——模型分不清"这是资料"还是"这是命令"。规则：外部内容进上下文前当作不可信数据处理；AI 的写操作（提交、改文档库）必须人工确认。这也是业界官方工具的安全基线："最小权限 + 高危操作人工确认"[^10^]。顺带一提，官方在讲 Agent Skills 时同样提醒：只装可信来源的 skill，来源可疑时逐个文件审计[^2^]——文档是能力单元，也就意味着它是攻击面。
8. 业界现状：有多少公司做到了这个程度？
先说诚实的答案："有多少公司完整做到"没有直接统计——这套实践 2025–2026 年才成型，还没有任何调查机构按这个口径统计过。但三组可核实的数据能拼出全景。
8.1 三组可核实的代理数据
指标 1：agent 上下文文件（CLAUDE.md / AGENTS.md）——最接近"文档即源码"的可测量行为。 AGENTS.md 发布约一年已被 6 万+ 仓库采用，现由 Linux 基金会的 Agentic AI Foundation 托管；OpenAI 自己的 Codex 仓库里嵌套了 88 个[^12^]。2026 年 2 月的一项学术研究（样本为 2853 个活跃使用 agentic 工具的工程化开源仓库）发现：90.6% 的仓库已经放了至少一种 agent 上下文文件——CLAUDE.md 占 45.9%，AGENTS.md 占约 40%[^11^]。注意样本偏差：这是"已经在用 AI agent 的开源项目"，不能外推所有公司；但它说明一旦团队真的开始用 agent，给它准备 MD 文档几乎是无一例外的动作。旁证：仅 2025 年 5–7 月三个月，GitHub 上就有 93 万个由 agent 提交的 PR，覆盖 11.6 万个仓库[^13^]。
指标 2：AI 写码普及度（文档变革的上游动力）。 Google 2024 年 10 月官宣超过 25% 新代码由 AI 生成；Stack Overflow 2025 调查 84% 开发者用 AI，JetBrains 85%，DORA 报告团队级采用率 90%[^14^]。但同一份 Stack Overflow 调查里，信任 AI 输出准确性的比例跌到 29%（同比下降 11 个百分点）[^15^]——"84–90% 在用、只有 29% 敢信"的剪刀差，说明绝大多数公司处在"用了 AI、但文档/上下文体系没跟上"的阶段。这条剪刀差就是本文全部的市场空间。
指标 3：对外文档的 AI 可读化。 Mintlify（文档托管平台）2024 年 11 月给它托管的全部文档站一键开启 /llms.txt——一夜之间数千个文档站（包括 Anthropic 和 Cursor）对 LLM 可读[^16^]；2026 年 5 月 Google 在 Lighthouse 里新增"Agentic Browsing"检测项，把"站点根目录有没有合法 llms.txt"列入评分[^17^]。连搜索引擎都开始给"你的文档 AI 读不读得动"打分了。
8.2 Anthropic 做到了吗？——分两半看
对外和对 agent 的层面：是，且有公开证据。 CLAUDE.md 这个实践就是 Anthropic 发明的；官方文档以 Markdown 为源、自动生成 llms.txt；示例仓库完全按"文档即源码"运作（公开仓库、社区 PR 评审）；Agent Skills 更是把这套做法直接标准化成了产品机制（§2.2）；CEO 公开称公司 70–90% 的代码由 Claude 编写[^18^]。
但三条保留意见，比"做到了"更有价值：
- 百分比有水分
——CEO 后来自己加了限定"在很多团队，不是全公司统一"；第三方考证认为全公司合并代码的 AI 占比平均更接近 50%，90% 只存在于少数团队[^18^]； - 它自己的内部研究反而验证了"验证是瓶颈"
——对 132 名自家工程师的调查：Claude 只承担约 60% 的工作任务，超过一半的工程师能"完全放手"给 AI 的工作不足 20%，主要用在调试和理解代码，高层设计基本不放手[^19^]。全世界最激进的 AI 公司，把自家最强的模型用在自己的代码上，内部依然是"AI 生成、人验证"——这就是"能放手到哪一档由验证速度决定"最好的实证（§7.3）； 它内部的设计文档体系外界无法验证，不宜过度推断。
8.3 全景：一条光谱
- 第一梯队（体系级做到）
：AI 原生公司 + 开发者工具公司——Anthropic、OpenAI、Cursor、Vercel、Stripe、Cloudflare、GitLab 这一小撮。数量没有统计，但从"6 万仓库 vs GitHub 数亿仓库"看，全体系落地的公司估计在个位数百分比。 - 第二梯队（单点做到）
：用了 agent、也放了 CLAUDE.md / AGENTS.md，但文档体系其余部分（设计文档、评审流程、交付链路）还是传统形态——这是那 90.6% 里的大多数。 - 第三梯队（绝大多数公司）
：84–90% 的人在用 AI，但文档还在 Word / Confluence 里，AI 只能读到零散上下文——所以信任度只有 29%。
这个分布对后来者反而是好消息："文档即源码"目前在统计学上还是先行者游戏，而原理已经清楚。在底层软件这种 AI 渗透更慢的领域先把文档体系建起来，拿到的不是"跟上潮流"，而是真实的时间差红利。
9. 两个常见误解，五条边界条件
误解一："AI 看不懂 Word，所以要换格式。" 诊断错了，但结论恰好对。Word 是 zip+XML，AI 提取文字毫无压力——真正的病不在理解力，在工程链路：二进制格式无法 diff、无法评审、无法进流水线、与代码永远脱节。文档放在哪、以什么形态流转，比 AI 读不读得懂重要得多。
误解二："模型再强一点，就不用这么认真写文档了。" 这是本文最想掰过来的一条，而且现在有官方数据可以直接反驳。模型变强确实让一批东西作废了——但作废的是写死的规则和提示词技巧（§2.3 那 80%），不是文档。恰恰相反：规则删得越多，腾出来的空间越是交给按需加载的文档。 模型越强，能消费文档、按文档独立干活的 agent 就越多，文档就越从"辅助阅读材料"变成"生产资料"。模型弱的时候，文档写差了只是人看着不舒服；模型强的时候，文档写差了是 AI 成群结队地把歧义执行成事故。
边界条件（防止把原理读成激进方案）：
- 组织摩擦是真实成本
：评审链路在 Word / Confluence 上的干系人不会因为框架正确就改变习惯——镜像层和导出层是必须保留的妥协，不是原则退让。 - MD 有真实短板
：复杂表格、批注/修订、对外正式场景（合同、标书、认证材料）仍是 docx / PDF 的领地——所以它们是"交付产物"，不是被消灭，而是被降级为生成物。 - 文档进仓库 ≠ AI 会用
：寻址（索引、入口指引）和粒度（单篇别太长、拆成可按需加载的文件树）决定它到底进不进得了上下文；且上下文不是越多越好，策展质量才是胜负手（§2.1、§5）。 - 硬件事实的最后防线永远是人 + 仪器
：寄存器值、时序、内存序，AI 生成的任何东西都先视为"待验证假设"。Demo 只要求"跑通过一次"，产品要求"每次都跑通"——这中间的距离，在硬件上只能靠人和仪器走完。 - 写进文档的红线不是护栏
：文档里的"必须 / 禁止"永远只是给模型的指令，不等于系统会强制执行。能被工具接口、权限或测试机械判定的禁区，应当下沉成参数、枚举、退出码、权限和检查项；无法机械判定的（内存序、所有权转移语义）则设人工卡点。把安全寄托在模型"记得遵守"，是"文档即源码"最常见的误用——源码里的注释拦不住任何越界，编译器和测试才能。
10. 结语
把全文收成三句话：
- 上下文是有限的，挂在文件系统上按需加载的文档体系是无限的。
所以文档不再是说明书，而是 AI 的能力单元——写得好，它多一项本领；写得烂，它多一份噪声。 - 文档与代码的关系已经反转：文档在上游，代码在下游。
写文档从文科活动变成了工科活动，从交付物变成了源码——同时也意味着它要评审、要重构、要删。 - 提示词技巧正在被厂商亲手贬值，通用工具会被商品化，验证速度被物理世界锁死——唯有你自己的私有事实，是唯一不随模型进步而贬值、且随时间复利的资产。
而 84–90% 的团队在用 AI、只有 29% 敢信它：这条剪刀差就是窗口期。现在开始存，就是最早的复利。
参考来源
官方一手来源（本文主要依据）
[^1^]: Anthropic 官方工程博客 — Effective context engineering for AI agents（2025 年 9 月 29 日；"上下文是边际收益递减的有限资源"、attention budget、最小高信号 token、compaction 与结构化笔记）：https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents [^2^]: Anthropic 官方工程博客 — Equipping agents for the real world with Agent Skills（2025 年 10 月 16 日发布，2025 年 12 月 18 日作为开放标准发布；SKILL.md 结构、progressive disclosure 三层、"一个 skill 能承载的上下文实际上无上限"、skill 安全建议）：https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills [^3^]: Claude 官方博客 — The new rules of context engineering for Claude 5 generation models（2026 年 7 月 24 日；删掉 Claude Code 系统提示 80% 以上、overconstraining 与 unhobbling、新旧规则对照、CLAUDE.md 该写"坑"不该写"显而易见的事"）：https://claude.com/blog/the-new-rules-of-context-engineering-for-claude-5-generation-models [^4^]: Anthropic 官方工程博客 — Effective harnesses for long-running agents（"每位接班工程师都不记得上一班"、compaction 不够、特性清单 + 进度文件 + git + init.sh、固定三步开局）：https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
框架与研究
[^5^]: Andrej Karpathy, Software Is Changing (Again)（2025 年 6 月 YC AI Startup School；LLM 类比 CPU、上下文窗口类比 RAM、Build for Agents、顺行性遗忘）。官方转写：https://www.ycombinator.com/library/MW-andrej-karpathy-software-is-changing-again ；完整转写与幻灯片：https://www.latent.space/p/s3 [^6^]: ETH Zurich 研究报道 — 自动生成的 agent 上下文文件降低成功率并增加约 20% 推理成本：https://www.marktechpost.com/2026/02/25/new-eth-zurich-study-proves-your-ai-coding-agents-are-failing-because-your-agents-md-files-are-too-detailed/ [^7^]: LangChain 官方博客 — Improving Deep Agents with Harness Engineering（模型固定，仅改模型外部环境：52.8% → 66.5%）：https://blog.langchain.com/improving-deep-agents-with-harness-engineering/ [^8^]: Martin Fowler — Harness engineering for coding agent users（上下文供给、确定性架构约束、熵管理）：https://martinfowler.com/articles/exploring-gen-ai/harness-engineering.html [^9^]: Atlassian 官方博客 — Remote Model Context Protocol (MCP) Server（2025 年 5 月）：https://www.atlassian.com/blog/announcements/remote-mcp-server [^10^]: GitHub — atlassian/atlassian-mcp-server（最小权限 + 高危操作人工确认的安全基线）：https://github.com/atlassian/atlassian-mcp-server
业界现状数据
[^11^]: Configuring Agentic AI Coding Tools（arXiv，2026 年 2 月快照，2853 个工程化开源仓库：90.6% 含 agent 上下文文件，CLAUDE.md 45.9%）：https://arxiv.org/html/2602.14690v4 [^12^]: AGENTS.md Complete Guide 2026（6 万+ 仓库采用、Linux 基金会托管、OpenAI Codex 仓库 88 个嵌套文件）：https://codersera.com/blog/agents-md-complete-guide-2026/ ；官方站点：https://agents.md/ [^13^]: AIDev: Studying AI Coding Agents on GitHub（arXiv；2025 年 5–7 月 93 万 agent 提交 PR、11.6 万仓库）：https://arxiv.org/html/2602.09185v1 [^14^]: AI Coding Assistant Statistics 2026（Google 25%、Stack Overflow 84%、JetBrains 85%、DORA 90%）：https://uvik.net/blog/ai-coding-assistant-statistics/ [^15^]: AI Coding Adoption 2026: 50 Statistics（信任 AI 准确性的比例降至 29%）：https://www.digitalapplied.com/blog/ai-coding-adoption-statistics-2026-50-data-points [^16^]: Mintlify — What is llms.txt?（2024 年 11 月为全部托管文档站开启 /llms.txt，含 Anthropic、Cursor）：https://www.mintlify.com/blog/what-is-llms-txt ；llms.txt 官方规范：https://llmstxt.org/ [^17^]: Google Lighthouse 新增 Agentic Browsing 检测（llms.txt 纳入评分）：https://github.com/johnericforte/claude-skill-llms-txt [^18^]: Redwood Research — Is 90% of code at Anthropic being written by AIs?（70–90% 原话、"部分团队"限定与第三方考证）：https://blog.redwoodresearch.org/p/is-90-of-code-at-anthropic-being [^19^]: Fortune — Inside Anthropic（132 名工程师内部调查：Claude 承担约 60% 任务、过半工程师完全放权不足 20%）：https://fortune.com/2025/12/02/how-anthropics-safety-first-approach-won-over-big-business-and-how-its-own-engineers-are-using-its-claude-ai/
