AI 时代的开发文档还在往飞书文档里写?

最近和同事沟通项目，发现开发文档还躺在飞书文档里。

我问他：“为什么不在项目里用 MD 写？扔仓库里不行吗？”

他回答得理直气壮，甚至带着一丝“你不懂技术前沿”的怜悯：“没事，AI 用 Skills 也能读到飞书文档。”

我愣住了。

不是被技术震惊，而是被这套逻辑里的认知错位给噎住了。

他的逻辑闭环是这样的：既然 AI 能通过爬虫、API 或者插件读到飞书，那文档放在哪儿都一样。反正最后都是机器读、机器吐答案，人只是中转站。

但恰恰是这个“能读到”，让我觉得我们正在用一种极其拧巴的姿势，假装自己拥抱了新时代。

AI 读飞书，不等于 AI 懂文档

当 AI 面对一个飞书链接时，它经历的不是“阅读”，而是一场惨烈的信号衰减：

1. 鉴权与模拟：依赖第三方 Skills 模拟浏览器登录，祈祷飞书的反爬机制今天心情好。
2. 富文本的降维打击：飞书文档里那些精心排版的折叠块、五彩斑斓的高亮、内嵌的 Figma 文件、@人的消息流……在 AI 的解析器里，通通被压扁成一串逻辑断裂的纯文本，或者一团根本无法理解嵌套关系的 JSON。
3. 版本的幽灵：AI 读到的是此刻的缓存快照，还是你三天前误删前的版本？Git 能告诉你真相，飞书只能告诉你“该文档已被更新”。

而当文档是项目根目录下的 docs/architecture.md 时，对 AI 意味着：

· 原子级的真相：代码即文档，文档即代码。README.md 和 main.go 在 AI 眼里是同一种东西——可信的 Ground Truth。
· 极致的低噪环境：没有花花绿绿的 CSS，没有隐藏的排版符，只有 AI 最爱的结构化纯文本。
· 原生的上下文追溯：AI 读到的不仅仅是文本，还能顺着 Git History 理解“这段逻辑为什么从 A 改成了 B”。

同事说 AI 能读飞书，就像说一个人能趴在地上舔饭吃。
能吃吗？能，饿不死。但人是坐在餐桌前用筷子吃饭的生物。
MD 是餐桌，飞书在这里就是布满灰尘的地面。

真正的困惑：我们为什么还在“转这道手”？

我不理解，所以我有一连串的反问，不吐不快。

第一问：AI 时代为什么还在写飞书文档？
是因为 AI 读不懂纯文本吗？显然不是。是因为人离不开那个“已读”小红点带来的虚假控制感吗？是因为不把文档扔进飞书，老板在手机上刷不到那 99+ 的未读数字，就觉得项目进度死了吗？

第二问：为什么开发文档不是 MD 格式？
是因为 Markdown 不支持花里胡哨的流程图吗？是因为 MD 没法在段落中间 @ 老板显摆工作量吗？还是因为一旦写成 MD 放进 Git，git blame 那一栏会无情地出卖你——“这家伙入职三年，一行文档都没写过”？

第三问：为什么不在项目里直接给 AI 看，还要转一道手？
是 AI 的 Skills 插件写得不够辛苦吗？是我们觉得折腾爬虫比敲两下 Ctrl+S 更有技术含量吗？还是现有的协作流程已经腐烂到连代码库的 /docs 文件夹都容不下一行干净的纯文本？

老板们一边在全体大会上声嘶力竭地喊“全面拥抱 AI，不换思想就换人”，一边死死攥着飞书文档的编辑权限，要求所有技术细节必须沉淀在那个富文本的豪华坟墓里。

这叫拥抱吗？
这叫把 AI 当成导盲犬，让它趴在地上，伸长舌头，去舔你昨天开会时踩过的那一串湿漉漉的脚印。

结论：那不是文档，那是坟场

真是荒谬到家了。

如果连项目最核心的开发文档，都要靠 AI 爬虫去费劲地扒开云端协作平台的 DOM 树才能勉强嗅到一点味道，那我们跟二十年前那些把 Word 文档打印出来、用红笔圈改、再扫描成 PDF 邮件发给全组的人，有什么区别？唯一的区别是：以前浪费的是纸和硒鼓，现在浪费的是 AI 宝贵的上下文窗口和算力。

文档写给 AI 看，就该让它堂堂正正地住在代码库里。
住在飞书里的那些玩意儿，那不叫文档，那叫会议纪要的坟场，是打工人在周报里证明自己“有产出”的电子墓碑。
这就像是
“把代码截图发微信群里让同事 Review，微信也能打开图片，这事儿对吗？”

建议所有开发文档，产品文档，设计文档都应该在项目下的docs 目录里面，而且必须是Markdown格式的，我就不相信你的文档现在还是一个一个字在敲，如果是，你还是用飞书文档吧！