htmx 作者 Carson Gross 最近的一篇随笔提了个主张：把 Markdown 当源代码，提交进仓库。这不是文档工程的老话题翻新。它指向一个正在成形的变化：agentic coding 时代，应用逻辑的事实真相开始住在 Markdown 里，agent 生成的代码反倒成了实现细节。
问题：意图没被版本管理
论据来自 Hartley Brody 那篇《Markdown is the new source code》：应用逻辑开始用 Markdown 定义和编辑，agent 生成的代码变成低层实现细节。Gross 补了一个关键观察：编译器工作流会保留原始源码，LLM 工作流不会。prompt 散落在临时会话、Linear、Slack 和 wiki 里，最终代码库中唯一可信的，只剩那段生成代码本身——而它恰恰不携带意图。
/src/md 约定
他的提议很具体：把从临时会话里沉淀出的 Markdown 提交进源码目录，放 /src/md 下，内容比传统设计文档更底层，涵盖架构决策、源码级决策、低层数据设计，接近规格说明但不是规格说明。目录约定长这样：README.md 当索引和 agent 入口，再加 TODO.md、OVERVIEW.md，下面按 features / data / api / infrastructure 分轴。作者自己承认这是全文最弱的部分——新想法，自己也没怎么用过。有一句建议值得单独划出来：这些文档应该主要由人写、人整理，别让 agent 生成。
业界已经在这么做
这个主张并不孤立。Claude Code 会读仓库根目录的 CLAUDE.md，Cursor 把项目约定放在 .cursor/rules，多家工具开始认 AGENTS.md 这份跨工具的说明文件。方向一致：把项目意图、约束、规范写进仓库文件，让 agent 在工作目录里直接读到上下文。/src/md 相当于把这个实践往前再推一步——从给 AI 的说明书，升级为被版本管理的规格源。
支撑它的是 locality（局部性）：代码模块旁边就是解释其意图的 Markdown，没有规格在别处的隔空魔法；Markdown 人和 agent 都能读。测试则承担另一层分工——测试即新规格有道理，但测试仪式感重、层级低，装不下 Mermaid 图这类高层解释，不适合做人机交互的介质。
适用边界与风险
适不适合你，先对号入座。适合的：agent 深度参与、代码生成频繁、设计决策容易随会话丢失的团队。不适合的：需求稳定、以人工编码为主的仓库，多一层文档只会增加同步成本。两个风险提前想清楚：一是文档漂移，md 和代码脱节后，agent 会拿着过期意图继续写码，错得比没有文档更彻底；二是别把密钥、内网地址写进这些文件，它们会被完整送进模型上下文。
两条落地校验
想落地，可以先加两条机械约束：CI 里检查 /src/md 的变更必须和代码变更出现在同一次提交，防止意图单独漂移；定期用 git log 抽查三个月没动过的 OVERVIEW.md，人工确认是否过期。这类笨规则，比指望大家自觉更新文档有效得多。
结尾那段价值判断值得原文照读：随着代码越来越便宜，真正有价值的，是代码背后的意图——它做什么、为什么做、绝不能做什么。这些意图今天大多丢在临时 prompt 里。写进 Markdown，check in 进仓库，人和 agent 都找得到。
