Markdown 正在取代代码成为真正的源码
Markdown in /src
随着 LLM 生成的代码越来越廉价，代码背后的意图反而成了最宝贵的资产。然而，这些意图往往散落在瞬时的 Prompt 会话、Slack 线程或 Wiki 文档中，导致真正的'源码'缺失。在 agentic coding 时代，我们应当将 Markdown 视为真正的源码，直接存入 /src 目录，与生成的代码并列。这样不仅保留了架构决策和数据设计等核心逻辑，还能让人类和 Agent 都能通过本地化（Locality）原则高效获取上下文。与其依赖易逝的提示词，不如让 Markdown 成为系统行为的单一事实来源，让测试和代码都从这份持久的规范中衍生出来。
随着代码生成的成本不断降低，真正有价值的部分是代码背后的意图：它做什么、为什么这么做，以及它绝不能做什么。
HN 评论区
93- aDyslecticCrow
你们见过测试腐烂（test-rot）、规范腐烂（specification rot）和文档腐烂（documentation rot）；现在我们要引入：提示词腐烂（prompt rot）！
用过时、啰嗦且迅速老化的提示词填满仓库，只会让未来任何需要查看该仓库的智能体感到困惑。保持上下文窗口精简是高质量 LLM 输出的真实限制，而这种工作流程可能会完全适得其反。
- 一个描述项目、核心抽象思想、最终用户等的 plan.md 非常好；但它应保持精简，并与仓库保持同步更新。
- 源代码文件和函数顶部的块注释非常好，对编程智能体已经非常有用。我认为除了现有的最佳实践之外，再增加其他东西并没有价值。
- je42
同意 Markdown 很重要。但我仍然将其视为意图，处理它会产生一个新的提交，而不是源码的一部分，因此我不会把它放在 src 目录里。
我的结论是，我想要整洁的 Markdown。因此它需要经过 linting 和格式化。
我开发了一个专门用于此目的的 linter/formatter：https://mdsmith.dev。
它包含了渐进式披露等工具。
- ktpsns
我通常把 Markdown 放在 /docs 目录。我不大写文件名。相反，我会让文档生成器读取这些文件，以便在 HTML/PDF 构建中获得不错的导航。
我们确实把非代码内容放在 /src 里很长一段时间：那是 heredocs、多行文档等。实际上，我的偏好是把文本放在代码附近，只在概念层面上回退到 /docs/something.md。这大概就是作者所提议的，鉴于他将 Markdown 视为代码的主要接口。
- xg15
如果我们走那条路，我们能否也为 Markdown 文档提供丰富的语法高亮、“跳转到定义”/“显示使用位置”、调试器等功能？:)
但我真的不太喜欢