在 /src 中使用 Markdown —— 将 Markdown 视为源代码

TL;DR

• Markdown 正从文档转向源代码。
• 将 Markdown 与代码一起存放在 /src/md 文件夹中。
• 从该 Markdown 生成代码和测试，而不是依赖临时的提示会话。

Why Markdown Should Be Treated as Source Code

Markdown 满足传统源文件的核心属性：它是纯文本、可对比、可搜索，并且在拉取请求中易于审查。大型语言模型（LLMs）可以原生读写 Markdown，而人类也可以无需专用工具进行编辑。因此，Markdown 可以充当驱动代码生成的 意图 层，就像编译器的高级规范驱动机器码一样。

The Problem with Ephemeral Prompting

当前的代理工作流通常通过一系列临时提示生成代码。生成的代码成为事实上的真实状态，而提示本身则散落在 Slack、Linear 或私人笔记中。这种“提示腐化”导致：

• 未来开发者和代理失去上下文。
• 无法对原始规格进行版本控制。
• 代理必须重建缺失意图时，增加 token 使用量。

Benefits of a /src/md Directory

Locality of Intent

将 Markdown 紧邻其描述的代码存放，消除了“远距离规格”的问题。开发人员无需离开源代码树即可查看模块的合理性，代理也能无需额外查找即可获取相同上下文。

Human‑Agent Symmetry

人类和 LLM 都可以消费相同的 Markdown 文件，确保意图、架构决策和数据模型的单一真相来源。

Version Control and Review

Markdown 文件参与与代码相同的 Git 工作流：它们可以被对比、lint 检查，并在拉取请求评论中讨论。这使得意图变更可审计且可审查。

How Markdown Complements Tests

测试对于自动化正确性验证仍然至关重要，但它们是低层级的，常常掩盖了功能存在的 原因。通过将意图存储在 /src/md 并从该意图生成测试，团队可以实现清晰的分工：

• Markdown – 行为、架构和数据的规格化描述。
• Tests – 生成代码是否符合规格的具体验证。

Proposed /src/md Layout

具体的文件夹结构有助于保持 Markdown 的组织性和可发现性：

src/
  md/
    README.md          # 代理和人类的入口点
    TODO.md            # 模块的待办任务
    OVERVIEW.md        # 模块的技术概览
    features/
      FEATURE_1.md     # 功能特定的描述
    data/
      DATAMODEL_1.md   # 数据模型定义
    api/
      API_1.md         # API 合同和用法
    infrastructure/
      INFRA_1.md       # 基础设施依赖

子文件夹是可选的；它们允许团队按逻辑维度（功能、数据、API、基础设施）分离关注点。

Community Feedback Highlights

• Prompt rot concerns – @aDyslecticCrow 警告称，存储过时的提示可能会使仓库杂乱并增加 token 使用量。共识是保持 Markdown 精简、及时更新，并将其视为 意图 而非每次提示的完整记录。
• Clutter vs. Value – @benrutter 认为过多的 Markdown 可能会膨胀仓库并难以维护。他建议主要在审查或回归分析时使用 Markdown，而非永久保存每次提示的副本。
• Tooling support – @xg15 询问关于 Markdown 的语法高亮和导航支持。现有的 IDE 扩展已提供丰富的 Markdown 支持，而 Varar 或 Cucumber 风格的 linter 工具可强制一致性。
• Alternative placement – @ktpsns 和 @maxk42 更倾向于将文档保留在 /docs 或单独的 README 文件中。关键区别在于 局部性：将意图紧邻代码放置（在 /src/md 中）可减少实现与理由之间的心理距离。
• Literate programming inspiration – @sroerick 将该方法类比为一种松散编译的 DSL 或文学编程，强调需要“规格匹配代码”的工作流。
• Standardization suggestions – @divbzero 建议在每个子目录中使用 README.md 而非中央索引，以符合常见的仓库惯例。

Practical Workflow

1. 创建或更新 /src/md 中的 Markdown 文件，描述新功能、数据模型或 API。
2. 运行 LLM，以 Markdown 作为提示来生成或更新代码。
3. 自动从同一 Markdown 生成测试（例如使用自定义生成器或 mdtest 等工具）。
4. 在单个拉取请求中审查 Markdown 和生成的代码。
5. 将任何手动编辑同步回 Markdown，以保持意图与实现的一致性。

Potential Pitfalls and Mitigations

• Stale Markdown – 建立 lint 步骤，标记未被最近提交引用的 Markdown 文件。
• Token cost – 保持 Markdown 精炼；将其视为高层级规格，而非每次提示的逐字记录。
• Non‑deterministic generation – 接受 LLM 输出可能变化；依靠测试捕捉回归，而非精确的生成代码。

Conclusion

随着 AI 使代码生成变得廉价，最有价值的资产变成了代码背后的 意图。将该意图以 Markdown 形式存储在 /src/md 目录中，提供了局部性、版本控制以及人类与代理共享的媒介。尽管具体布局会演进，但核心理念——将 Markdown 视为源代码而非外围文档——为代理式开发工作流提供了一条务实的前进路径。