文档渐进式披露：给agent读的四条纪律

宝玉（dotey）的文档管理四条，回答的是"功能复杂了文档怎么管"这个老问题：一，文档统一放 docs 目录；二，全部遵循渐进式披露原则——每篇文档都不大，主文档只做概要与目录，具体内容链到章节对应的小文件；三，根目录一个 README，方便索引到相关文档；四，在 AGENTS.md 里强制"改功能必须改相关文档"，而且人也要定期抽查——他补的那半句是重点："即使加了规则也可能遗漏"。

站内早有同方向的实践可以对照：开发大项目前先用 grill-with-docs 这类 skill 拷问文档、让 agent 按文档干活——方向一致，一个管"改"，一个管"用"。

我的看法：渐进式披露本质是给 agent 时代的文档纪律——人和模型的注意力都是稀缺资源，把"概要 + 链接"设为默认结构，谁进来都不用先吞一整本书；AGENTS.md 强制改档则把文档更新从"自觉"变成"规则"，而那句"规则也会漏、人要抽查"补上了最关键的一环：自动化管下限，人管上限。

四条合起来其实是一套可被 agent 消费的文档系统：有入口（README）、有分层（披露）、有钩子（AGENTS.md）、有兜底（人查）——下次有人问"复杂项目的文档怎么办"，这四条可以直接甩过去。

四条按作者原述整理，实践效果因项目而异。