AI 生成代码越来越普及以后，一套围绕 Markdown 组织源码的新做法正在 htmx 社区里形成共识，它要求开发者把描述系统意图的 Markdown 文件直接签入 src 目录，让代码和测试都从这份文档派生。这个思路和传统前端把文档放在 wiki 或独立目录的习惯明显不同，值得正在引入 AI 编程工具的开发团队认真评估。正在用 htmx 做服务端渲染、同时尝试 AI 辅助编码的开发者，以及需要管理多人协作代码库的技术负责人，是这篇文章最对口的读者。
src 里的 Markdown 到底长什么样
传统的 Markdown 文档通常远离代码，放在 docs 目录或者项目外的知识库里。src 目录内的 Markdown 做法改变了这个位置关系。它要求每一组核心模块旁边都放一份 Markdown 文件，描述这个模块做什么、为什么这样做、绝对不能做什么。位置紧邻代码，阅读代码的人不需要跳转到另一个系统就能理解设计决策。这个做法的参考结构包括一个 README 作为索引入口，一个 OVERVIEW 描述整体行为，再加上按功能、数据模型、API 和基础设施分目录的专项文档。这个结构尚在演化。
为什么放在 src 比放在 wiki 里强
放在 src 里的 Markdown 能被 grep，能进 code review，能和代码一起被版本控制。人和 AI 都直接读写它。放在 wiki 或 Notion 里的文档，阅读时需要切换上下文，AI 工具需要额外的集成才能拿到内容。src 内的 Markdown 天然解决了这个问题。AI 读代码的时候顺手就能读到紧邻的意图描述。代码审查的时候，文档变更和代码变更出现在同一个 pull request 里，审查者能同时看到两方面的改动。
代码和测试为什么要从 Markdown 派生
传统开发里，需求文档写完以后就开始写代码，文档很快过期。AI 生成代码的场景里，这个脱节被进一步放大，代码生成速度更快，文档落后得更严重。从 Markdown 派生代码的做法把这个顺序倒了过来。先写清楚意图，再让 AI 依据这份意图生成代码。测试也是同一个来源。这种做法让 Markdown 成为代码库事实上的源头，生成代码只是它的一个产物。测试文件放在 test 目录，和 Markdown 描述一一对应。
具体的目录结构怎样组织
src/md 结构大致分为五类文件。第一类是 README，作为索引和入口。第二类是 TODO，记录尚未完成的改动。第三类是 OVERVIEW，描述模块的整体预期行为。第四类是按主题拆分的文档，放在 features、data、api、infrastructure 等子目录里。第五类是模块特有的补充文档，按需添加。这些文件全部由开发者手写和整理，不让 AI 代写，AI 生成的文档容易和代码的真实状态脱节。
这个做法有哪些风险和反对意见
最大的风险是文档和代码仍然会脱节，只是脱节的位置从 wiki 换到了 src。团队没有养成先改文档再改代码的习惯，src 里的 Markdown 会快速过期。第二个风险是文档变成新的维护负担，每个功能改动都要同时更新两份内容。第三个风险来自经验不足，这个约定目前最不成熟。适合尝试的场景是团队已经开始用 AI 生成代码，同时有稳定的 code review 流程。不适合的场景是单人项目或者文档传统已经很弱的团队，额外维护一份源头文档的成本可能超过收益。
常见问题
已经有测试了，为什么还需要 Markdown？
测试验证行为正确性，但不解释为什么这样做。架构决策的理由、边界条件的说明、数据流向的意图，放在 Markdown 里比放在测试代码里自然得多。测试负责机器检查，Markdown 负责人和 AI 阅读。
Markdown 和 JSDoc 注释有什么区别？
JSDoc 描述函数级别签名，Markdown 描述模块级别意图，两者尺度不同。这套 Markdown 更接近一份规格说明，位置在正式规格文档和代码注释之间，粒度比 JSDoc 粗，比设计文档细。
小团队值不值得引入这个做法？
两名以下开发者的项目可以先从 OVERVIEW 一个文件开始试，维护成本最低，收益也最直接。等团队规模上来再逐步拆分。