一下午用 AI 整理了 80 篇文档,发现文档烂掉的原因从来不是没人写

大家好，我是阿辉。

引子：一个下午发生了什么

上周末，我和 AI 做了一件看起来很无聊的事：把团队钉钉知识库从 15 个混乱的顶层文件夹重构为 8 个互不重叠的目录。

具体来说：重命名 8 个顶层目录、新建 20+ 个子夹、迁移 80+ 篇文档到新位置、给每个目录写一份导读文档、统一排版格式、处理归档策略、调整目录排序、审计敏感内容。

整个过程我没操作一次钉钉文档。所有操作通过自然语言指令完成——我说”把骑手餐和淘宝闪购挪到调试联调目录”，AI 调用 move_document API 执行；我说”这篇文档格式不对，标题和正文之间要空一行”，AI 用 insert_document_block 插入空段落。

这件事本身不新鲜。文档整理谁没做过？但完成它的方式让我被迫思考了几个问题：当 AI 能直接操作文档平台时，”文档化”这件事的本质是什么？人和 AI 的分工边界在哪？什么东西是 AI 永远替代不了的？

这篇文档不是理论推演，而是从一次包含大量返工和踩坑的协作经历中提炼出的观察。

AI 确实做得比人快的事

先承认 AI 的优势。在这次协作中，有几类任务它的效率是人的 10-50 倍：

1.1 批量结构化操作

原来的”调试联调”目录里有 28 篇文档平铺在一起，从”手淘调试指南”到”代理工具”到”二清联调流程”到”拼团相关文档”全混在一块。我需要它们按”宿主调试 / 工具入口 / 联调场景 / 业务宿主”四个维度分类归入子夹。

如果我手动做，流程是：逐篇打开 → 阅读内容 → 判断分类 → 拖拽到对应文件夹。28 篇文档，每篇平均 2 分钟，大约 1 小时。

AI 的流程是：我给出分类规则和 4 个目标子夹的名称 → 它根据文档标题和我之前扫描过的内容判断归属 → 28 次 move_document API 调用 → 10 分钟完成。

这里的关键不是”AI 能调用 API”（这只是工具能力），而是它能把自然语言描述的分类规则转化为对每篇文档的具体判断。当我说”测试账号、测试链接、预发二维码这类东西应该放到工具入口”时，它能把”零售指定版本测试”这篇也归到”业务宿主”而不是”工具入口”，因为它记得这篇的内容是”零售业务方在某次指定版本升级时要验证哪些支付场景”，本质是某个业务线的版本测试清单，而不是通用工具。

1.2 生成胶水文档

每个顶层目录都需要一份”导读”——类似于一个 README，告诉读者这个目录里有什么、按什么顺序读、读完能回答什么问题。

这类文档的特征是：信息密度不高（本质就是目录索引 + 一句话描述），但写起来极其耗时。因为你需要：确认每篇文档的 URL 是否正确、描述是否准确反映当前内容、阅读顺序是否合理、跨目录引用是否用了正确的路径名。

AI 写导读的优势不在于”文笔好”（这类文档不需要文笔），而在于它可以在生成文本的同时验证每个链接的 nodeId 是否真实存在。它写”支付收银架构”时，这个 nodeId 是它刚刚从 list_nodes 结果里拿到的，不是编造的。人工写导读时，最痛苦的不是组织文字，而是反复在浏览器和文档之间切换确认链接对不对。

一个下午我让 AI 写了 7 份导读。如果手动做，每份至少 30 分钟（打开每篇文档确认内容 + 复制链接 + 组织文字 + 调排版），7 份就是 3.5 小时。AI 大约用了 20 分钟（包含我审阅和要求修改的时间）。

1.3 一致性维护

8 条排版规则要在 7 篇导读 + 1 篇技术文档里一致执行：

• 标题后空一行再接正文
• 代码块后空一行再接下一段
• 描述标签（如”参考实现：”）紧贴代码块
• 标题和引用 blockquote 之间不空行
• 正文到下一个标题之间空一行
• 禁止双空行
• 标题到标题之间不空行
• Q&A 列表 Q 和 A 在同一个列表项里

每篇导读 20-50 个 block，8 篇就是 160-400 个 block。人工逐个检查并调整，大约需要 2 小时（而且第三篇开始会走神）。AI 可以程序化地检查每一对相邻 block 是否符合规则。虽然它执行时也会出错（见下文），但至少”检查规则是否满足”这件事它永远不会走神。

AI 做不好的事（以及为什么）

2.1 它没有“品味”，只有“规则”

这次协作中最让我头疼的环节是排版。不是因为规则复杂（8 条规则写出来就一页纸），而是因为我在第一轮没有把规则写清楚。

最开始我说“标题和正文之间空一行”。AI 严格执行了。但我发现“代码块后面接正文”时也需要空一行，否则正文和代码块贴在一起看起来很压迫。于是我加了一条规则。然后又发现“描述标签（如‘参考实现：’）接代码块”时不应该空行，因为标签和代码块是一体的。于是又加了一条。

整个过程中 AI 从来没有主动说“描述标签后面紧贴看起来更好”，因为它不知道什么“看起来好”。它只会执行我明确给出的规则。如果我给出的规则有歧义或遗漏，它会忠实地执行错误的理解，直到我发现并纠正。

品味是一种压缩后的判断力。当我说”这篇文档写得不好”时，背后是”我见过 100 篇好的技术文档，它们有某些共同特征（结构清晰、有迁移视角、代码块有上下文、有 checklist），这篇不符合这些特征”。AI 需要我把这种压缩过的判断一条一条展开成可执行的规则，才能帮我做对。

这不是 AI 能力不足的问题，而是品味本质上是一种私人经验的压缩，还没有被语言化。一旦被语言化（变成了”8 条排版规则”），AI 就能严格执行。但语言化这个动作本身，只有人能做。

2.2 它倾向于“重做”而不是“修补”

这次协作中最大的效率损失来自一个模式：AI 用 update_document(mode=overwrite) 重写了整篇文档的内容，结果把上一轮已经用 insert_document_block 精心调好的排版空行全部清零。

然后它需要再花 10-15 分钟重新插入所有空行。有时候重新插入的过程中又会因为 API 的 re-normalize 行为出现偏差，需要再调一轮。最严重的一次，我数了一下，同一篇文档的排版来回调了 5 轮才最终到位。

根本原因是 AI 没有”增量思维”。人在修文档时的本能是”我只动需要动的部分”，但 AI 的默认倾向是”我把整个东西重新生成一遍确保一致”。

这在很多场景里是优点（比如代码生成），但在文档排版这种”已有状态很脆弱、每次全量重写都会丢失之前的微调”的场景里是灾难。

后来我把这条教训固化成了一条规则写进 skill：”一旦 markdown 已经写入，后续调整全部用 block 级操作（insert/delete/update），不再用 update_document(mode=overwrite)“。从那之后这个问题再没出现过。

这给我的启示是：AI 的错误模式是可预测的、可预防的。它不会犯人类那种”今天心情不好所以写得很敷衍”的随机错误，它犯的都是”默认策略在特定场景下不适用”的系统性错误。一旦你识别出这种错误模式并写成规则，它就永远不会再犯了。

2.3 它不理解平台的“暗知识”

钉钉文档 API 有几个魔鬼细节：

1. create_folder 返回的 folderId 字段不是新文件夹的 ID，而是父文件夹的 ID。真正要用的是 nodeId 字段。用错了 API 不报错，文档只是默默跑到个人空间。
2. create_document 的正文参数叫 markdown，不叫 markdownContent。传错参数名 API 也不报错，只是创建出空文档。
3. move_document 到同一父目录时，最后一次 move 的节点会排到列表底部（知识库根目录）或顶部（子目录内），两种行为不一致。
4. update_document_block 不支持 table、blockquote、unknown（代码块）类型，需要”删除 + 重新插入”。

这些”暗知识”有一个共同特征：知道了就永远不会再犯，不知道就可能花很长时间 debug（因为 API 返回 success）。

AI 在这次协作中每一个坑都踩过了。但重要的是：发现它踩了坑是人的工作。因为 API 返回了 success，AI 并不知道自己犯了错。是我打开文档发现”内容怎么是空的？”、”这个文件夹怎么跑到个人空间了？”之后追问 AI，它才回去检查参数发现了问题。

人在这里的角色不是”执行”，而是”质检 + 归因”：发现结果不对 → 追溯到原因 → 让 AI 修正 → 把原因写成规则防止复发。

2.4 它的错误会滚雪球

这是我在第三轮排版返工之后总结出来的教训：AI 不适合一次性做 10+ 处修改然后统一验证。

原因是钉钉文档 API 有一个隐性行为：每次 insert_document_block 或 delete_document_block 后，系统会自动 re-normalize 相邻 block 的间距，有时候会自己加一个空行，有时候会吞掉一个空行。这种行为不可预测，也没有文档记录。

如果你一次性做了 15 处修改，其中第 3 处触发了 re-normalize 导致多了一个空行，那第 4-15 处的修改都是基于一个错误的状态在执行。

等你全部做完再验证时，发现有 8 处不对，但你已经分不清哪些是你主动改的、哪些是 re-normalize 引入的。

后来我建立了一条硬规则：”每批最多 3-5 处修改，每批做完立即 list_document_blocks 校验。”这把排版调整从”不可控的混乱”变成了”可收敛的迭代”。

人在其中承担什么角色

回顾整个过程，我的工作可以归纳为五类：

3.1 定义“为什么”和“给谁看”

“这个目录的读者是新入职的支付前端同学” / “这份文档面向外部业务方接入者” / “FY 是从 4 月开始的” / “骑手餐和淘宝闪购应该归到调试联调而不是归档”。这类上下文信息只有人能提供。

AI 很擅长问对问题（”骑手餐子夹怎么处理？A 整体挪到归档 B 打散到根层 C 搬到调试联调”），但选哪个选项、基于什么理由选，是我决定的。

这些决策的依据通常不是逻辑推导，而是”我知道这个团队的工作习惯”或”我预判三个月后这个目录会怎么增长”。这是只有身处团队中的人才有的前瞻判断。

3.2 做审美判断

“这篇文档写得不好” → “结构散乱、缺迁移视角、代码块没有上下文、重复内容” → “需要加变更总览表格 + 迁移 checklist + 旧写法→新写法对照 + FAQ”

这个从”感觉不好”到”具体哪里不好”到”应该怎么改”的拆解过程，就是品味的展开。AI 可以执行最后一步（按照你说的结构重写文档），但前两步——感知到问题 + 定位到原因——目前只有人能做。

有意思的是，一旦我把”好文档应该长什么样”拆解成具体规则（比如”技术迁移文档必须有旧/新对照表”），AI 就能检查其它文档是否满足这条规则。所以人的角色不是永远当审美判断的执行者，而是当审美规则的提取者。提取一次，AI 执行无限次。

3.3 当质检员

每次 AI 说”完成了”，我会打开链接看一眼实际效果。这次协作中，至少有 30% 的”完成”需要返工。问题类型包括：

• 顺序不对（最常见）
• 双空行或缺空行（排版类）
• 文档创建到了错误位置（API 陷阱类）
• 内容和方案文档不一致（记忆偏差类）
• 多余的占位文件夹没清理

这告诉我：AI 的执行正确率在文档场景大约 70%。这个数字听起来不低，但在”差一个空行就不对”的排版场景里，70% 意味着每 10 个 block 有 3 个需要人工确认。

不过这仍然比从零开始快得多。70% 正确的初稿 + 10 分钟人工修正 ≈ 95% 的最终结果。而从零开始手动做 100% 可能需要 3 小时。

3.4 把一次性经验变成可复用规则

这是我认为人在 AI 协作中最有杠杆的角色。

每次我说”不对，应该这样”时，我会让 AI 把这条经验存下来（存到 memory 或 skill）。三次之后它就不会再犯了。

比如：

• “钉钉文档 create_folder 返回的 folderId 不可信” → 存入 memory
• “标题后空一行、描述标签紧贴代码块” → 存入 USER.md
• “排版调整必须小批量 + 立即校验” → 写进 skill

这本质上是把人的隐性知识显性化成 AI 可执行的规则。做这件事有两个前提：第一，你得先踩一次坑（否则你不知道有这条规则需要写）；第二，你得能把”这里不对”提炼成”下次遇到 X 情况时应该做 Y”的 if-then 结构。

这件事的杠杆极高。我花 30 秒写一条规则，AI 之后所有相关操作都会遵循。如果这条规则被写进 skill 并分享给团队，那整个团队用 AI 时都不会再踩同一个坑。

3.5 决定“什么时候够了”

AI 永远不会主动说”差不多了，到此为止吧”。如果你继续给它任务，它会继续做。但”这个程度已经够用了，后续的完善留到使用中逐步迭代”，这种对完成度的判断只有人能做。

在这次重构中，V6 方案原本还有一个”99-资源与工具”目录没建。但做到第 7 个目录时我判断”当前 8 个顶层目录的结构已经足够团队日常使用，剩下的可以下周再说”，于是停了。AI 不会做这个判断——它会忠实地继续建”99-资源与工具”直到你让它停。

画一条线

如果把文档协作比作开车：AI 是自动驾驶系统，能精确地保持车道、自动变道、按导航走。但”今天走高速还是走省道”是人决定的，”前面那辆车的司机看起来要变道，提前减速”这种基于直觉的预判也是人做的。而”这段路自动驾驶表现不好（总是在匝道处犹豫），需要我记下来反馈给工程团队调参数”。这就是”把一次性经验变成可复用规则”的类比。

品味悖论：练习被外包后怎么办

前面反复说”品味是人不可替代的价值”。但这里有一个尖锐的问题：

品味是怎么来的？是练出来的。但如果练习的过程都交给 AI 了，品味还怎么练？

以前一个开发写技术文档的成长路径大概是这样的：第一次写系分，写得乱七八糟被评审打回来；第二次模仿着师兄的模板写，好了一点但不知道为什么好；第十次写的时候开始有感觉了——知道什么时候需要加流程图、什么时候该用表格对比、什么时候”少即是多”。这个”有感觉”就是品味，它是从大量”亲手写 + 被打回 + 反思为什么不好”的循环中长出来的。

现在如果这个人从第一天起就让 AI 代写系分，他会得到一份格式正确、结构完整、看起来不错的文档。评审不会打回来。他省了时间。但他也失去了那个”被打回 → 反思 → 下次写得更好”的成长循环。

三年后，他可能成为一个”很会用 AI 写文档的人”，但不是一个”自己知道什么是好文档的人”。区别在于：前者离开 AI 就不行了，后者可以指导 AI 做得更好。

这个悖论有解吗？

我认为有，但解法不是”回到不用 AI 的时代”，而是改变”练习”的定义。

传统的练习是”从零到一的执行”：你从一张白纸开始，用自己的手把文档写出来。这个过程中你被迫做每一个决策——用什么结构、放什么信息、怎么排版——每个决策都是一次隐性的品味训练。

AI 时代的练习是”从一到更好的审阅”：AI 先给你一份 70% 的初稿，你的任务不是从零写，而是看出哪里不好、说清为什么不好、给出具体改法。这同样是品味训练，只是训练的方式从”生产”变成了”审阅和修正”。

这次协作中我品味提升的几个时刻

回顾这次经历，我的品味确实在过程中被打磨了，但不是通过”我自己动手写文档”，而是通过以下几个环节：

1. 看到 AI 的初稿后说”不对”的瞬间

AI 生成了第一版”Mor→Weex 迁移指南”，我看了一眼就说”这篇文档写得不好”。但这个”不好”的判断不是凭空的，我是在跟我脑子里”好的迁移文档长什么样”的标准做比对。而说出”不好”并不够，我必须进一步拆解出具体哪里不好（结构散乱、缺迁移视角、代码块孤立、没有 checklist）。这个拆解过程本身就是一次品味的显性化训练。

以前我可能只是模糊地觉得”这文档不顺畅”但说不清为什么。被迫给 AI 讲清楚之后，我对”好的迁移文档”的标准变得更明确了。

2. 发现“描述标签”和“正文”对空行的需求不同的瞬间

AI 严格执行了“代码块后空一行”，但“参考实现：”后面紧跟代码块时也被插了空行，看起来标签和代码块被拆散了。我需要分析为什么不对。最终发现是“描述标签和代码块是一个语义单元，中间不应该有间距”这个排版原则。这个原则我以前没有明确意识到过，它一直存在于我的隐性偏好里，直到 AI 的“严格执行”把它逼出来了。

如果我一直是自己手动排版，我可能会凭直觉把描述标签和代码块贴在一起，但不会去思考“为什么这两个东西应该紧贴”。是 AI 的机械执行让我不得不把直觉翻译成语言。

3. 比对”方案文档”和”实际执行结果”时发现偏差的瞬间

当我发现”5-规划与进展”的实际实现和 V6 方案文档不一致时（月度进展散在顶层而不是按 FY 归类），我需要判断”以方案为准，还是接受实现的结果”。这个判断需要回到方案的设计意图（”某年的目标/排期/月度产出横向对齐”），然后评估实现偏差是否损害了设计意图。

这种”设计意图 vs 实现偏差”的审视本身就是架构品味的训练，跟 code review 里”这段代码能跑但不对”是同一类判断力。

品味训练的新范式

所以我的结论是：AI 时代品味训练的核心不再是”从零生产”，而是”高质量审阅 + 精确表达不满”。

具体来说：

1. 大量看：让 AI 生成 10 个版本的目录结构 / 文档排版 / 导读写法，你快速浏览后说”第 3 个最好”，然后追问自己”为什么觉得第 3 个好”。这个追问就是品味的显性化。

2. 精确拒绝：不要说”这个不好”，而是说”这里不好，因为 XXX，改成 YYY”。每一次精确拒绝都是一次把隐性品味变成显性规则的练习。你做 100 次”精确拒绝”之后，品味不会比做 100 次”从零手写”差。

3. 跨案例比对：让 AI 把同一类文档（比如 7 篇导读）都生成出来，然后你做”横向比对”，找出哪些地方风格不一致、哪些地方某篇比其它篇好。这种比对训练只有在 AI 能快速批量生成时才现实。

4. 事后复盘：做完一次完整的文档协作后（就像我现在在写的这篇），回顾”哪些时刻我的判断是对的、哪些时刻我应该更早介入”。复盘是品味成长最高效的方式，而 AI 让复盘有了更丰富的素材（因为过程全都有记录）。

品味不会消失，但品味生长的土壤从”重复执行”变成了”高频审阅”。关键是你得主动去审阅，而不是按下 Enter 之后就不管了。

真正的改变：维护成本趋近于零

这次协作让我意识到一件事，也许是最重要的一件事：

AI 最大的价值不是”代替人写文档”，而是”让文档的维护成本足够低，低到人愿意持续维护”。

以前团队文档烂掉的原因从来不是”没人会写”。程序员都会写 markdown，都知道好文档应该长什么样。

文档烂掉的真正原因是”写了没人更新”。当目录混乱到找不到东西时，没人有动力整理，因为整理一次要半天，结果下周又因为几篇新文档的加入变乱。

这是一个经典的”维护成本 > 维护收益”的困境。解决方案不是让人更有毅力（这从来不 work），而是让维护成本降到极低。

如果”整理一个目录”从”半天”变成”5 分钟对话”——”把这三篇新文档归到对应子夹，顺便更新一下导读”——那”保持目录整洁”就不再是一个需要意志力的行为，而变成了一个随手就能做的小事。

就像 git commit 一样，频率高了，每次变更就小，merge conflict 自然就少。

传统理解中”AI 写文档”意味着：给 AI 一个主题，它生成一篇看起来像那么回事的文章。但实际工作中”文档化”远不止这一项，它还包括架构设计、分类判断、链接维护、一致性保证、内容审计、索引生成、权限管理。

其中 AI 在分类/链接/一致性/审计/索引这 5 项上有明显优势（快、不遗漏、不走神），在架构设计和权限管理上人有绝对优势，在所有项上都需要人来质检。

更准确的描述是：AI 承担文档化工作中 70% 的体力活（执行、验证、维护），人承担 30% 的脑力活（决策、审美、兜底）。但这 30% 是不可替代的 30%，因为它定义了另外 70% 应该往哪个方向走。

给实践者的建议

如果你也想用 AI 做团队文档的重构或日常维护，这是我踩坑之后的建议：

1. 先定规则再交给 AI 执行

如果你对”什么是好的排版 / 好的目录结构”没有清晰的标准，AI 会在不同轮次里给你不同的结果，然后你会花三倍时间在返工上。花 15 分钟把你的偏好写成规则（哪怕只是”标题后空一行、代码块后空一行”这种粗粒度），远好过在执行过程中边做边改。

2. 小批量 + 立即校验

不要让 AI 一口气做完 50 件事再检查。做 5 件事、打开文档验证一次，发现偏差立即修正。AI 的错误会滚雪球：第一处错了如果没发现，后面的操作都是基于错误状态在堆叠。

3. 把你的纠正固化成规则

你每次说”不对，应该这样”时，多加一句”记住这条规则”。让 AI 把这条经验存到 memory 或 skill 里。三次之后它就不会再犯了。这比抱怨”AI 老是犯同一个错误”有效 100 倍。

4. 不要追求 AI 一次到位

文档不是代码，”差不多对了”比”还没开始做”有价值得多。先让 AI 生成 70% 正确的骨架，再用 10 分钟人工调到 95%。试图让 AI 一次性输出 100% 完美的文档，你会花在”描述需求”上的时间比你自己动手写还长。

5. 善用 AI 的”不会疲劳”属性

人最不擅长的是”对 100 个同类对象做完全一致的检查”。让 AI 做一致性校验、链接有效性检查、格式规则验证。这些事它永远不走神，而你第三篇就会开始划水。

6. 把 AI 当成”执行力无限但品味为零的实习生”

你需要给它明确的标准、具体的例子、即时的反馈。但不需要给它动力和耐心，这两样它永远不缺。它不会嫌任务无聊，不会因为返工 5 次而情绪崩溃，不会在周五下午开始摸鱼。唯一的问题是它不知道什么是好的，你告诉它——哪怕只告诉一次——它就永远记住了。

结语

脑海中想到：AI 时代文档化的新方式是什么？

不是 AI 自动生成一堆看起来很专业但实际没人看的文档。而是——文档终于可以像代码一样被”持续集成”了。

代码之所以能保持质量，是因为有 CI。文档之所以烂掉，是因为没有 CI。

AI 让文档的 CI 成为可能。当维护成本趋近于零，”好习惯”就不再是文档质量的前提了。

它把文档质量从”人的习惯问题”变成了”系统设计问题”。而系统设计，恰好是工程师最擅长的事。

如果你也在用 AI 做文档协作，欢迎在评论区说说你踩过的坑和总结出的规则，这类经验越多人分享，所有人的 AI 就越好用。

下周二见。