Markdown in /src

Markdown in /src Carson Gross, September 21, 2026

TLDR

Markdown is becoming source code, not documentation.
Markdown should be checked into /src, alongside the code it produces.
Code and tests should be derived from that Markdown, rather than from ephemeral prompts (or at least prompt sessions should eventually turn into persisted Markdown).

TLDR

Markdown 正在成为源代码，而非文档。
Markdown 应该被提交到 /src 目录中，与它所生成的代码放在一起。
代码和测试应该从这些 Markdown 中衍生出来，而不是仅仅依赖瞬时的提示词（或者至少提示词会话最终应该转化为持久化的 Markdown）。

Intro

In order to supplement my income as a professor at Montana State University, I do consulting on the side. I enjoy consulting and the act of writing code & helping build systems, both for their own sake and also because it keeps my skills relevant and allows me to teach students about the latest ideas in software development. Obviously the biggest thing to happen in development in the last few years is agentic coding: using LLMs to generate code in lieu of hand coding.

引言

为了增加我在蒙大拿州立大学担任教授的收入，我会在业余时间做咨询工作。我享受咨询以及编写代码和构建系统的过程，不仅是因为这些工作本身的乐趣，还因为这能让我的技能保持前沿，并使我能够向学生传授软件开发领域的最新理念。显然，过去几年开发领域发生的最重大事件是“智能体编程”（agentic coding）：使用大语言模型（LLM）来生成代码，以取代手工编码。

I have written a few essays on this topic:

Yes, and…
Code is Cheap(er)
The University In The AI Era
Working With AI: A Concrete Example

我曾就此主题写过几篇文章：

《Yes, and…》
《代码很廉价（更廉价）》
《AI 时代的大学》
《与 AI 协作：一个具体的例子》

In this essay I want to discuss an idea that is becoming increasingly clear to me as I work in companies that are prioritizing agentic coding: Markdown is now source code, not documentation. This is not a novel or particularly clever idea, of course. In Markdown is the new source code, Hartley Brody writes: “It is starting to feel as if the application logic of the software is being defined and edited as markdown, and the actual code that is generated by the agent is sort of becoming a low-level implementation detail.”

在这篇文章中，我想讨论一个随着我在那些优先采用智能体编程的公司工作而变得越来越清晰的观点：Markdown 现在是源代码，而不是文档。当然，这并不是一个新颖或特别聪明的想法。在《Markdown 是新的源代码》一文中，Hartley Brody 写道：“感觉软件的应用逻辑正被定义和编辑为 Markdown，而智能体生成的实际代码，某种程度上正在变成一种底层的实现细节。”

Now, as the essays above show, I am ambivalent about AI-generated code. However, my consulting work shows that organizations are headed in this direction, often at terrific speed. What I want to do in the remainder of this essay is think about the ramifications of Markdown becoming, more and more, the source of truth for software systems.

正如上述文章所示，我对 AI 生成的代码持矛盾态度。然而，我的咨询工作表明，各组织正以惊人的速度朝着这个方向发展。在本文的剩余部分，我想探讨 Markdown 逐渐成为软件系统“事实来源”（source of truth）所带来的影响。

The Missing Source Code

There is a line of thinking, captured in the quote above, that LLMs are akin to compilers, taking high-level specifications and turning them into low-level implementations. In this view, we don’t need to look at the code an LLM generates, just as we don’t look at the machine code a compiler generates. As I mention in Code is Cheap(er), I do not totally agree with this analogy for a few reasons, but the one relevant to this essay is: compiler workflows retain their original source code while LLM workflows typically do not.

缺失的源代码

有一种观点（如上文引用所述）认为，LLM 类似于编译器，将高级规范转化为底层实现。按照这种观点，我们不需要查看 LLM 生成的代码，就像我们不需要查看编译器生成的机器码一样。正如我在《代码很廉价（更廉价）》中所述，我并不完全认同这个类比，原因有几点，但与本文相关的一点是：编译器工作流会保留原始源代码，而 LLM 工作流通常不会。

Today, LLM-generated code is often created via a string of prompts fed into an agent as a developer builds out a feature. In practice, this means that the generated code is the closest thing we have to “ground truth” for that feature. There may be documentation for the feature stored elsewhere (e.g. Linear, Slack threads, wikis, etc.) but, so far as the codebase is concerned, the generated code is the source of truth. My opinion is that, in professional agentic coding environments, we need to accept that LLM-generated code that emerges from ephemeral prompting sessions is not ideal, and begin moving towards capturing and checking in Markdown alongside generated code in the source directory.

如今，LLM 生成的代码通常是在开发者构建功能时，通过一系列输入给智能体的提示词创建的。在实践中，这意味着生成的代码是我们所拥有的最接近该功能“事实来源”的东西。虽然该功能的文档可能存储在其他地方（例如 Linear、Slack 讨论串、维基等），但就代码库而言，生成的代码就是事实来源。我的观点是，在专业的智能体编程环境中，我们需要承认，从瞬时提示会话中产生的 LLM 生成代码并不理想，我们应该开始转向将 Markdown 捕获并提交到源代码目录中，与生成的代码并存。

Markdown As Source

Markdown has many nice properties that make it similar to traditional source code:

It is plain text and therefore diffable, greppable and reviewable in pull requests
LLMs read and write it natively
Humans can read and edit it without tools

And, in fact, it is already acting as source, to an extent, in AGENTS.md, specs, plans, TASK.md and so forth. We just haven’t standardized capturing that source yet.

作为源代码的 Markdown

Markdown 具有许多优良特性，使其类似于传统的源代码：

它是纯文本，因此在 Pull Request 中可以进行差异对比（diff）、搜索（grep）和审查。
LLM 可以原生读写它。
人类无需工具即可阅读和编辑它。

事实上，在某种程度上，它已经在 AGENTS.md、规范、计划、TASK.md 等文件中充当了源代码的角色。我们只是还没有将这种源代码的捕获过程标准化。

In Markdown is the new source code, Brody says he keeps his Markdown files in .scratch/research/ and .scratch/plan/ as he works. I have adopted the convention of creating a /tmp directory for similar ephemeral needs. My proposal is that we promote some of these files to a new directory, alongside our existing source code: /src/md.

在《Markdown 是新的源代码》中，Brody 说他在工作时将 Markdown 文件保存在 .scratch/research/ 和 .scratch/plan/ 中。我则采用了创建一个 /tmp 目录来处理类似临时需求的惯例。我的建议是，我们将其中一些文件提升到一个新的目录，与我们现有的源代码并列：/src/md。

The Markdown captured in this proposed directory would be lower level than traditional design documents:

It contains architectural decisions
It contains source-level decisions
It contains low-level data design decisions

It is much closer to a specification (although it is not one) than a design document as traditionally managed by a project manager or designer.

在这个建议目录中捕获的 Markdown 将比传统的设计文档更底层：

它包含架构决策。
它包含源代码层面的决策。
它包含底层数据设计决策。

它比传统由项目经理或设计师管理的设计文档更接近于“规范”（尽管它本身并非规范）。

Locality

I am a fan of locality, and I think that moving Markdown into /src has strong locality advantages:

Code modules would now include the Markdown that explains the intent of the code
There is no spooky “specification at a distance”, where the logic of why is elsewhere in a wiki/Notion/Confluence/Jira
Markdown in /src can be consumed by both humans and agents
Agents no longer need to look elsewhere to get context on a given codebase

局部性

我是“局部性”（Locality）的拥护者，我认为将 Markdown 移入 /src 具有强大的局部性优势：

代码模块现在将包含解释代码意图的 Markdown。
不再有令人困惑的“远程规范”，即解释“为什么”的逻辑分散在维基、Notion、Confluence 或 Jira 中。
/src 中的 Markdown 可以同时被人类和智能体消费。
智能体不再需要去其他地方获取特定代码库的上下文。

What About Linear/Wikis/etc.?

Other sources of truth for the behavior of the system can still exist. These sources would provide higher-level and/or “process-oriented” documentation: high-level design documents, issues that need a resolution workflow and so forth. But the core, current and static intended behavior of the system would increasingly be captured directly in Markdown in the source directory.

那么 Linear/维基等工具呢？

系统行为的其他事实来源仍然可以存在。这些来源将提供更高级别和/或“流程导向”的文档：如高层设计文档、需要解决流程的问题等。但系统的核心、当前且静态的预期行为，将越来越多地直接捕获在源代码目录的 Markdown 中。

What About Tests?

I have seen many people online saying that tests are the new specification (or always were). I think there is some truth to that. However, tests are not a good mechanism for human/agent interaction:

They involve a lot of ceremony, often obscuring what they are testing
They are typically lower level than most humans want to deal with, particularly when understanding a system
Higher-level explanations such as Mermaid diagrams don’t fit naturally into them

I think the following division of labor makes sense:

Markdown sits in /src and is the specification(ish)
Tests sit in /test (or wherever) and are based on that Markdown, providing automated confirmation of correctness

Again, the core idea here is that, rather than generating code and tests from prompts, a developer would work on Markdown in the /src directory, from which the code and tests would be derived.

那么测试呢？

我在网上看到很多人说测试就是新的规范（或者一直都是）。我认为这有一定道理。然而，测试并不是人类与智能体交互的良好机制：

它们涉及繁琐的仪式感，往往掩盖了它们正在测试的内容。
它们通常比大多数人类想要处理的层面更底层，特别是在理解系统时。
像 Mermaid 图表这样的高级解释无法自然地融入其中。

我认为以下分工是合理的：

Markdown 位于 /src 中，作为（准）规范。
测试位于 /test（或其他位置）中，基于该 Markdown，提供自动化的正确性确认。

再次强调，这里的核心思想是：开发者不应仅仅通过提示词生成代码和测试，而应该在 /src 目录中编写 Markdown，并以此为基础衍生出代码和测试。