夜雨聆风封面摘要：在AI 智能体使用或者开发的时候，要注意大模型不是不会写文档，而是很容易只改它刚看到的那一段。一个 600 行文档，状态改了，底部清单没改，看起来只是粗心，根因其实是文档结构错了。
我最近踩了一个很典型的坑。
一个智能体工程任务已经推进完几轮，文档里的 Phase 状态也更新了，但底部“后续任务清单”还停留在旧状态。局部看是对的，全局看是错的。
这不是大模型“笨”，也不只是“下次仔细点”能解决。
更真实的原因是：我们把不该放在一起的东西，塞进了同一个长文档。
1｜大模型更新文档，为什么特别容易漏？
人更新文档时，会下意识做全局扫读。
但大模型执行任务时，常常是“局部定位 + 局部修改”。它会先找到相关段落，然后围绕这个上下文改。这个模式写代码很高效，但更新长文档就容易出问题。
尤其是这种结构：
docs/artifacts/topic-design.md 1. 背景 2. 目标 3. 架构设计 4. Phase 状态 5. 验收结果 6. 后续任务清单 7. 历史记录 8. 过程笔记看起来很完整。
问题也在这里：它太完整了。
稳定设计、阶段状态、后续任务、历史复盘，全都混在一个文件里。大模型更新 Phase 状态时，很可能只改第 4 节，漏掉第 6 节。
💡 文档越长，越不能指望 AI 每次都自动做全局一致性检查。要靠结构，让它不需要记住那么多。
2｜真正的问题不是长度，而是职责混杂
很多人以为文档漏更新，是因为文件太长。
长当然是问题，但更大的问题是：一个文件承担了太多职责。
我后来把文档先按职责拆开：
requirements.md -> 为什么做、范围、目标、非目标design.md -> 稳定架构、目录、契约、核心设计delivery-plan.md -> Phase 状态、验收、证据、风险、下一步这三个文件不是为了显得规范。
它们解决的是更新频率不同的问题：
requirements.md: 低频更新。目标不变就别动。design.md: 中频更新。架构变了才动。delivery-plan.md: 高频更新。每完成一步都动。这样一来，大模型接到“更新进度”的任务时，就不需要在一个 600 行文档里找所有相关位置。
它只需要更新 delivery-plan.md。
好文档结构的价值，是减少 AI 需要猜的范围。
3｜按“读者”拆，比按“内容类型”更稳
智能体项目里的文档，至少有三类读者：
人: 想知道现在做到哪了、风险是什么、下一步干什么。AI: 想知道执行任务时必须遵守什么规则。未来的你: 想知道当时为什么这么设计，哪里踩过坑。如果这三类读者都挤在一个文件里，文档迟早会变成杂物间。
所以我会继续拆：
notes/ 过程观察、设计取舍、以后可能有用的经验postmortems/ 已经造成失败的问题、根因、修复、防复发动作articles/ 对外分享草稿，需要脱敏和重组叙事这不是为了“文档洁癖”。
而是因为不同读者需要的东西不一样。AI 执行任务时，不应该每次都被迫读一堆过程闲聊；人看进度时，也不应该在一堆规则和错误栈里翻状态。
💡 给 AI 看的文档，要短、稳定、可执行。给人看的文档，要能判断状态。给未来复盘看的文档，要保留真实原因。
4｜每个文档都要有更新触发条件
我现在最怕一种文档：看起来什么都能写进去。
因为“什么都能写”，最后就会变成“谁也不知道该改哪里”。
更稳的做法是给每个文档写触发条件：
requirements.md: 只有范围、目标、非目标、成功标准变化时更新。design.md: 只有架构、目录、契约、核心流程变化时更新。delivery-plan.md: 每完成一个 phase、验收一次、发现新风险时更新。postmortems/*.md: 已经造成失败、漏更新、错误报告、线上异常时新增。notes/*.md: 只是过程观察、设计取舍、以后可能有用的经验时新增。这个规则对人有用，对 AI 更有用。
因为大模型执行时最怕边界模糊。你说“更新一下文档”，它就会自己判断改哪里。你说“只更新 delivery-plan 的 Current Summary、当前 Phase、Backlog”，它犯错概率会低很多。
文档结构设计，本质上是在给 AI 降低自由度。
5｜给 AI 一个 Anti-Miss Checklist
即使拆了文档，也不能完全相信“它会记得检查”。
我会在交付类任务里加一个 Anti-Miss Checklist：
[ ] Current Summary 是否更新？[ ] 当前 Phase 的 Status 是否更新？[ ] Validation / Evidence 是否更新？[ ] Next 是否更新？[ ] Backlog 是否还残留已完成任务？[ ] changelog 是否更新？[ ] staged diff 是否只包含本轮文件？这个清单的意义不是形式主义。
它是在强迫大模型做“横向一致性检查”。否则它很容易只把眼前段落改漂亮，却漏掉远处的状态字段。
我踩过的那次坑就是这样：Phase 状态改了，但后续任务清单没改。不是模型不会写，是没有被结构化地要求检查。
6｜文档要变成智能体的工作台
传统文档更多是“写给人看的说明书”。
智能体项目里的文档，还要承担另一个角色：它是 AI 执行任务时的工作台。
所以文档不能只写“我们打算怎么做”，还要写：
输入在哪里？输出在哪里？什么时候算完成？失败时写到哪里？哪些内容不能公开？哪些文件是唯一状态源？比如一个自动化任务，文档里最好能直接看到：
status_source: delivery-plan.mdsnapshot_path: logs/task/snapshots/report_path: skills/task/report/validator: scripts/validate_task.py --latestpostmortem_path: docs/artifacts/task/postmortems/public_article_path: docs/artifacts/task/articles/这对人类读者可能有点“工程味”。
但对智能体来说，这就是导航地图。你不给地图，它就会靠猜。
7｜我的最终原则
现在我设计智能体项目文档，会先问 4 个问题：
1. 这个文档的读者是谁？2. 它的更新频率高不高？3. 它是不是唯一状态源？4. AI 执行任务时，能不能根据它少猜一点？如果一个文档同时回答太多问题，我就会拆。
如果一个目录里什么都能放，我就会补规则。
如果一个任务经常漏更新，我不会只说“下次仔细点”，而是加 checklist、拆状态源、补复盘。
💡 总结：智能体项目文档结构
问题 做法 本质 长文档漏更新 按职责拆文件 减少全局一致性负担 状态经常不一致 设置唯一状态源 让 AI 知道改哪里 过程材料太乱 notes / postmortems 分流 不把经验塞回主流程 AI 更新不完整 加 Anti-Miss Checklist 强迫横向检查 对外内容混杂 articles 单独存放 方便脱敏和重组
文档不是越全越好。
对智能体项目来说，真正好的文档结构，是让 AI 少猜、让人少翻、让错误少重复。
你有没有遇到过 AI 更新文档时“改了这一段，漏了另一段”的情况？评论区聊聊。
码字不易，如果对你有用，请关注/点赞/转发。