Markdown在/src中

# </> htmx ~ Markdown 位于 /src 中 来源：https://htmx.org/essays/markdown-in-src/ Carson Gross 2026年9月21日 ## 简要总结 (TLDR) (https://htmx.org/essays/markdown-in-src/#tldr) - Markdown 正在成为源代码，而非文档 - 这种 Markdown 应当与它产生的代码一起，被提交到 `/src` 目录中 - 代码和测试应从该 Markdown 派生而来，而非来自临时性的提示词（或者至少，提示词会话最终应转化为持久化的 Markdown 文件） ## 引言 (Intro) (https://htmx.org/essays/markdown-in-src/#intro) 为了补充我在蒙大拿州立大学担任教授的收入，我兼职从事咨询工作（https://bigsky.software/）。我享受咨询工作以及编写代码与帮助构建系统的实践，既因为其本身的价值，也因为它能让我保持技能与时俱进，并向学生传授软件开发领域的最新理念。 显然，过去几年开发领域最重大的进展是智能体编码（agentic coding）：使用大语言模型（LLMs）生成代码，取代手工编码。我围绕这个主题写了几篇随笔： - 是的，然后… (https://htmx.org/essays/yes-and/) - 代码更便宜了 (https://htmx.org/essays/code-is-cheap/) - AI 时代的大学 (https://htmx.org/essays/universities-and-ai/) - 与 AI 共事：一个具体例子 (https://htmx.org/essays/working-with-ai/) 在这篇随笔中，我想讨论一个在我为那些优先考虑智能体编码的公司工作时，变得越来越清晰的想法： Markdown 现在就是源代码，而*不是*文档。 当然，这并非一个新颖或特别聪明的想法。 在《Markdown 是新的源代码》 (https://blog.hartleybrody.com/markdown-research-planning/) 一文中，Hartley Brody 写道： > 开始让人感觉，软件的应用逻辑正在以 Markdown 的形式被定义和编辑，而由智能体生成的实际代码有点变成了一种底层的实现细节。 正如以上随笔所示，我对 AI 生成的代码持矛盾态度。然而，我的咨询工作表明，组织正朝着这个方向前进，而且速度常常非常快。 在本随笔的剩余部分，我想探讨的是，当 Markdown 越来越多地成为软件系统的事实来源（source of truth）时，会带来哪些影响。 ## 缺失的源代码 (The Missing Source Code) (https://htmx.org/essays/markdown-in-src/#the-missing-source-code) 有一种观点认为，大语言模型类似于编译器，接受高层级的规范并将其转化为底层的实现。这种观点体现在上述引文中。在这种看法下，我们不需要查看大语言模型生成的代码，就像我们不需要查看编译器生成的机器码一样。 正如我在《代码更便宜了》(https://htmx.org/essays/code-is-cheap/) 中提到的，我并不完全同意这个类比，原因有几个，但与本随笔相关的一个是：编译器工作流保留了其原始源代码，而大语言模型工作流通常不会。 今天，大语言模型生成的代码通常是在开发者构建某个功能时，通过向智能体输入一系列提示词来创建的。在实践中，这意味着生成的代码是我们拥有的最接近该功能“基本事实”（ground truth）的东西。可能在其他地方存有该功能的文档（例如 Linear、Slack 讨论串、Wiki 等），但就代码库而言，生成的代码才是事实来源。 我的观点是，在专业的智能体编码环境中，我们需要承认，从临时提示词会话中产生的大语言模型生成的代码并不理想，并应开始转向在源目录中捕获并与生成的代码一起提交 Markdown 文件。 ## Markdown 作为源 (Markdown As Source) (https://htmx.org/essays/markdown-in-src/#markdown-as-source) Markdown 具有许多优良特性，使其类似于传统的源代码： - 它是纯文本，因此可进行差异比较、内容搜索和在拉取请求中审查 - 大语言模型可以原生读写它 - 人类无需工具即可阅读和编辑它 事实上，它已经在某种程度上充当了源代码的角色，例如 `AGENTS.md`、规范、计划、`TASK.md` 等文件。我们只是还没有标准化对这些源内容的*捕获*。 在《Markdown 是新的源代码》(https://blog.hartleybrody.com/markdown-research-planning/) 一文中，Brody 说他在工作时将 Markdown 文件保存在 `.scratch/research/` 和 `.scratch/plan/` 目录中。我也采用了类似的约定，为临时性需求创建一个 `/tmp` 目录。 我的提议是，我们将这些文件中的一部分提升到一个新目录中，与我们现有的源代码并列：`/src/md` 这个拟议目录中捕获的 Markdown 内容将比传统设计文档*更底层*： - 它包含架构决策 - 它包含源码级别的决策 - 它包含底层的数据设计决策 它更接近于一个*规范*（specification）（尽管它并非传统意义上的规范），而不是项目经理或设计师传统上管理的设计文档。 ### 局部性 (Locality) (https://htmx.org/essays/markdown-in-src/#locality) 我是一个局部性（locality）原则的拥护者（https://htmx.org/essays/locality-of-behaviour/），我认为将 Markdown 移入 `/src` 具有强大的局部性优势： - 代码模块现在将包含解释其意图的 Markdown - 不存在“远距离规范”的诡异现象，其中关于*为什么*这么做的逻辑位于 Wiki/Notion/Confluence/Jira 的其他地方 - `/src` 中的 Markdown 可以被人类*和*智能体共同使用 - 智能体不再需要去其他地方查找给定代码库的上下文 ## 那么 Linear/Wiki 等呢？ (What About Linear/Wikis/etc.) (https://htmx.org/essays/markdown-in-src/#what-about-linear-wikis-etc) 其他关于系统行为的事实来源仍然可以存在。这些来源将提供更高级别和/或“面向流程”的文档：高层级设计文档、需要解决流程的问题等等。 但系统核心的、当前和静态的预期行为，将越来越多地直接以 Markdown 形式捕获在源目录中。 ## 测试怎么办？ (What About Tests?) (https://htmx.org/essays/markdown-in-src/#what-about-tests) 我在网上看到很多人说测试就是新的规范（或者一直都是）。我认为有一定道理。 然而，测试*不是*人/智能体交互的良好机制： - 它们涉及很多仪式感，常常掩盖了它们在测试什么 - 它们通常比大多数人（尤其在理解系统时）想要处理的层级更低 - 更高层次的解释，如 Mermaid 图表 (https://mermaid.ai/open-source/intro/)，无法自然地融入其中 我认为以下分工是合理的： - Markdown 位于 `/src`，充当规范（近似） - 测试位于 `/test`（或其他地方），基于该 Markdown，提供自动化的正确性确认 再次强调，这里的核心理念是，开发者将不再是基于提示词生成代码和测试，而是在 `/src` 目录中处理 Markdown，代码和测试从这些 Markdown 中派生出来。 ## `/src/md` 中的 Markdown 长什么样 (What `/src/md` Markdown Looks Like) (https://htmx.org/essays/markdown-in-src/#what-src-md-markdown-looks-like) `/src/md` 中的 Markdown 介于系统的正式规范和高层级设计文档之间。 如同源代码一样，这些 Markdown 也关联着一个复杂性预算（Complexity Budget）(https://htmx.org/essays/complexity-budget/)。需要谨慎管理，以保持这些文档的整洁、良好的分解和适当的抽象层级。 开发者应当被期望与 Markdown *和*派生的代码进行交互，因此在适当的时候同步两者将成为一项重要的技能。 例如，开发者经常会对生成的代码进行减法、约束性（subtractive, constraining） (https://htmx.org/essays/code-is-cheap/#the-subtractive-constraining-engineer) 工作，而这些改动可能需要被移回 Markdown 中。 我相信智能体*不*应被用于生成 `/src/md` 中的大部分内容。这个目录应主要由人类编写和维护。 ## 一个拟议的 `/src/md` 约定 (A Proposed `/src/md` Convention) (https://htmx.org/essays/markdown-in-src/#a-proposed-src-md-convention) 这必然是本随笔最薄弱的部分，因为这是一个新想法，我还没有广泛使用过。这是我边思考边提出，并邀请讨论。 话虽如此，以下是一个可能的 `/src/md` 标准： ``` src/ md/ README.md # 所有 md 文件的索引，智能体的入口点 TODO.md # 本模块开放的通用 TODO 列表 OVERVIEW.md # 本模块的技术概览 features/FEATURE_1.md # 特定功能的相关文档集 data/DATAMODEL_1.md # 模块中数据模型的描述 api/API_1.md # 模块提供的 API 描述 infrastructure/INFRASTRUCTURE_1.md # 模块使用的基础设施描述 ``` 这里的 `features`、`data`、`api` 和 `infrastructure` 目录都是可选的；其理念是按照不同维度进行划分，以便在 `/src/md` 文件夹中直接捕获模块行为的可靠工作描述。 ## 结论 (Conclusion) (https://htmx.org/essays/markdown-in-src/#conclusion) 随着代码生成成本降低，仍然有价值的是代码背后的*意图*：它做什么，为什么这样做，以及它必须不做什么。 如今，这种意图常常在临时提示词会话中丢失，或者分散在 Wiki、工单和 Slack 讨论串中。 我认为，本着局部性的原则，我们应该考虑将这种意图以 Markdown 形式捕获，并将其与生成的代码一起提交到 `/src` 中，让人类和智能体都能找到它。 我尚不清楚类似 `/src/md` 的正确结构到底是什么，我预计随着我（和其他人）对此有更多经验，我的想法会改变。 但我相当确信，Markdown 正在成为源代码，我们应该越来越多地将其视为源代码。 （即使，不，大语言模型不是编译器 :)）