CoAI 开发日志 #004｜为什么最后是 Markdown 功能文档 + 双链
在 CoAI 的几条路线里，最后留下来的，是最“普通”的那条。
不是自定义文件类型。
不是更复杂的节点系统。
不是更重的结构表达。
而是：
Markdown 功能文档 + 双链 + 代码锚点。
现在回头看，这个结果其实挺有意思。
因为它看上去一点都不“新”。
Markdown 本身不新。
双链也不新。
把文档和代码连起来，这个想法也不算特别新。
但 CoAI 最后会收敛到这里，恰恰说明一个问题：
很多时候，真正能长期活下来的，不一定是最复杂、最完整、最炫的结构，
而是最能长期使用的那种结构。
我一开始也不是直接就选了 Markdown。
那时候想过一个方向：既然这是新的认知层，是不是应该有一种新的文件类型？
比如专门为 CoAI 设计一种格式，把节点、关系、映射这些东西都表达得更原生一点。
这个想法在纸面上是成立的。
因为你会觉得：
- 表达能力更强
- 格式更统一
- 更适合系统处理
- 以后也许还能做更复杂的功能
但问题很快就出来了。
第一，新的文件类型意味着新的学习成本。
不仅是人要学，agent 也要学。
而且一旦格式稍微重一点，维护成本会明显上升。
第二，它会把 CoAI 和项目本身拉得太开。
我后来一直在检查一件事：
CoAI 不能活成一个独立世界。
它要尽量贴着开发者真实工作的环境存在。
如果一个系统要想长期留在项目里，
它就不能让开发者每次进入都像切换到另一个宇宙。
第三，越是面向 agent 的系统，越要在“表达能力”和“上下文摩擦”之间做权衡。
一个格式也许更强，
但如果它让人和 agent 都更难自然进入，那它未必是更好的选择。
后来我慢慢发现，Markdown 的一个很强的优点恰恰在于：
它几乎没有进入门槛。
开发者会用。
agent 也能读。
编辑器天然支持。
diff 友好。
迁移成本低。
复制、修改、引用都很轻。
这时候，双链的意义也开始变得清楚。
一开始看，双链只是一个形式：
[[用户填写]] -> [[前端提交]] -> [[服务器校验]]
但它真正起作用的地方，不在于“长得像笔记软件”。
而在于它提供了一种非常轻的语义入口。
你不用先理解复杂结构。
不用先学额外格式。
也不用先看一张大图。
你只要看到这几个词，就已经知道这个功能的理想路径是什么了。
而一旦这些 token 还能：
- Hover 看说明
- Click 跳代码
- 通过 mapper 和 anchor 回到真实实现
那它就不再只是“一个文档格式”，
而是一个很轻的认知入口系统。
这也是为什么我后来判断，
CoAI 选择 Markdown，不是因为它“够简陋”，
而是因为它在这个问题上，刚好够用。
它的优势不是表达力最强。
它的优势是：
它足够轻，所以能真正嵌进开发过程里。
这点非常重要。
因为很多系统都死在一个地方：
设计时很漂亮，
真正进入长期开发后，却没人持续维护。
不是因为理念错了。
而是因为它太重了。
我后来确认，CoAI 能不能成立，
关键不在“理论上能表达多少”，
而在“开发者和 agent 会不会真的持续使用它”。
从这个角度看，Markdown + 双链的 tradeoff 就很合理了。
它放弃了一些更强、更原生的结构表达能力，
换来了：
- 更低的进入门槛
- 更强的编辑器兼容性
- 更自然的人机共用语境
- 更低的长期维护摩擦
这不是退而求其次。
这反而成了我后来很重视的一种判断：
在 AI coding 时代，长期能被人和 agent 一起使用的轻结构，往往比理论上更强的重结构更有价值。
所以 CoAI 最后不是落在“更特别”的格式上，
而是落在了最普通的 Markdown 上。
不是因为没能力做更复杂的。
而是因为最后真正想保住的，不是结构炫技，而是长期可用的认知入口。
如果今天要把这篇压成一句话，我会这样写：
不是最强的表达方式会活下来，而是最能被长期使用的表达方式会活下来。
这也是为什么 CoAI 最后是 Markdown 功能文档 + 双链，而不是一套新的重格式系统。
这是 CoAI 开发日志第 4 篇。
记录我在 AI coding 时代，如何理解人与 AI 应该怎样协同工作。
