最近逛 GitHub，感觉开源项目的文档越来越难看懂了。

才一年功夫，AI 已经接管了大半个生态：写代码、维护项目、出文档。

我说的不是 AI 味，而是整份文档从结构上就不是写给人看的。

为什么这么说？我让 AI 帮我维护过一份知识库，主要给 AI 看、由 AI 维护。整体内容结构很概括，逻辑关联也挺好，可换我自己去看，就是太难懂了，费神。现在看 GitHub 上的说明文档，也是这种感觉。

可以看看对比，第一张是几年前的一个项目，文档一眼就能知道是什么，干什么的。后一张是我最近打开的一个项目，一开头就不怎么想往下看，这里只是举个例子，没有抹黑项目的意思哈，项目还是很优秀的。

几年前的项目文档

最近的项目文档

AI 维护的项目，和人维护的项目，差距到底在哪里？

我试着分析了下，可能有以下的一些原因。文末还附了一个基于这些思考做的 skill 分享，目前用着不能说多牛逼吧，起码写出来的文档，我能看下去。

1. AI 永远处于“全知”视角

我们自己维护项目，自己踩过坑，也当过“第一次来的人”，知道新用户可能卡在哪。

但 AI 维护项目时，上下文就是整个项目本身。它永远处在“全都知道”的状态，很难意识到 Plugin、Runtime、bootstrap 这类内部词汇，对新用户来说其实是一堵墙。毕竟谁也不可能什么技术都懂，更不知道这个项目有哪些坑。

2. AI 不会“偷懒”，不懂信息筛选

人脑有负载，记不住那么多，所以写文档只能挑最重要的写。

动笔前，人会把讨论和踩过的坑在脑子里过一遍，写出来的是结论加一句为什么（比如“为进一步简化用户操作，我们做了某某调整”）。

但 AI 不会累。它倾向于把当前状态完整、精确地记下来，比如提交的 Hash、边界等过程产物。

结果就是，文档成了项目状态的“快照”：极其准确，但毫无重点。它记下了过程，却没有转化成读者需要的东西。

3. AI 是“增量维护”，缺乏整体产品观

AI 维护项目通常一次只做一个任务，修 bug或者加功能，所以很多文档顶部变成了“本次更新了什么”，整个 README 被最近一次发布占满。

人会时不时退一步想：“现在来一个新人，应该先看到什么？”然后把旧内容挪走或删掉。从人的角度出发，很多时候要做的是“删”和“不做”。

AI 的默认倾向是加和补。时间一长，项目就成了一层层局部正确的改动叠起来，整体却没有主线。

AI 可以很好地执行任务，但产品这个角色，必须由人来承担。

怎么解决这个问题？

针对这些问题，我写了一个 Skill，核心目的是强制 AI 切换到用户的视角写文档。

核心规则：

  • 前三句话：说清楚这是什么、给谁用、怎么开始。

  • 给结论：重要变化写成用户能直接用的结论（比如“现在装了用不了”，而不是“Runtime >= 0.5.9”）。

  • 不预设误解：少写“不是什么”这种没用的否定句，Hash、版本表这类追溯信息放进 CHANGELOG。

至于“缺乏整体产品观”的问题，我的做法是：

  • 写一份短的产品意图（PRODUCT.md）：几百字左右吧，写清给谁用、主路径、刻意不做什么。让 AI 每次维护前先读它：方向由我定，AI 在方向内执行。

  • 文档分层：README 给人看，AGENTS.md 给 AI 看，CHANGELOG 给维护者看，别搅在一起。

最后，还有一个低成本的自查方法：用一个“干净的 AI”当新用户。

AI 的毛病是全知，但一个新开的、没有项目上下文的对话，本身就是个新人。让它只读 README，然后说说看完知不知道这东西是干嘛的、该怎么开始。能说清楚这些，这份文档就过关了。

这是我的一个完全由 AI 维护的项目 README，可以看看效果。

用 skill 维护的项目文档

skill 自取地址：https://github.com/Canace22/my-skills/blob/main/human-readable-docs/SKILL.md