guog

Markdown：从文档语言到 AI 时代的工程基础

Written by guog

Published: / 12 min read

技术

从基本语法到工程协作，理解 Markdown 如何连接项目知识、研发流程与 AI Agent。

View more blogs with the tag #Markdown, View more blogs with the tag #软件工程, View more blogs with the tag #AI

用自己的 Agent 对话阅读

不必逐行读完。复制提示词，发给你自己的 Agent，通过对话理解文章；也可以继续向下阅读。

Markdown
查看提示词

如果你的 Agent 无法访问网页，请保存 Markdown 文件提供给它，或粘贴正文；长文可按章节分次提供。

Table of Contents

理解为什么一种极简的纯文本格式，能够连接项目知识、协作流程和 AI Agent

Markdown 从纯文本成为工程协作载体

打开一个现代开源项目，常能看见 README.md、设计提案、Pull Request 描述、贡献指南以及 AGENTS.md 等文件。它们的用途不同，却经常使用同一种表达形式：Markdown。这不是因为 Markdown 能完成复杂排版，而是因为工程协作长期需要一种既方便人阅读、又容易由工具处理和版本管理的文本格式。

在人工智能（Artificial Intelligence，AI）编程时代，这个特点被进一步放大：项目约定、需求背景、设计判断和任务说明可以长期留在仓库中，不必只存在于一次对话。由此也出现了更前沿的观点：部分 Markdown 不再只是解释代码的文档，而可能成为持续驱动实现和测试的上游工程输入。理解这种变化，需要先分清三个层次：表达信息、组织协作、约束软件行为。

一、Markdown 为什么诞生：让纯文本本身也值得阅读

Markdown 由 John Gruber 在 2004 年发布，Aaron Swartz 参与了早期设计与反馈。它的出发点不是开发一个复杂的文档软件，而是让人以易读、易写的纯文本进行创作，并能够将其转换为 HTML（HyperText Markup Language，超文本标记语言）。Markdown 原始发布页至今仍能帮助我们理解这一设计动机。

这带来了三个特别适合软件工程的特性：

  1. 不依赖特定编辑器：普通文本工具就能打开和修改，长期保存与迁移成本低。
  2. 天然适合 Git：修改标题、增加约束、调整验收标准都能逐行比较，也能通过 Pull Request（PR，拉取请求）评审。
  3. 方便工具处理：检索、转换、抽取章节、生成网页或自动读取都比较容易，人与程序看到的是同一份基本内容。

Markdown 并非单一、完全一致的渲染实现。CommonMark 尝试统一基础语法的解析行为；**GFM（GitHub Flavored Markdown，GitHub 风格 Markdown）**在此基础上支持任务清单等协作场景。使用时应了解平台扩展，不能假设所有 Markdown 阅读器都有同样能力。参见 CommonMark 规范 和 GFM 规范。

二、只掌握少量语法，就能阅读大多数工程文档

Markdown 的优势在于“够用而简单”。下面先展示源码，再展示人阅读时看到的结果。标题是例外：为避免混淆本文的章节层级，仅展示其源码。

标题：通过井号表达层级

# 一级标题
## 二级标题
### 三级标题

强调、列表与链接

源码：

请先完成 **权限检查**，再允许导出。


- 澄清需求边界
- 记录验收条件
  - 包括异常情况


阅读 [GitHub 官方 Markdown 指南](https://docs.github.com/zh/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)。

渲染效果：

请先完成 权限检查，再允许导出。

  • 澄清需求边界
  • 记录验收条件
    • 包括异常情况

阅读 GitHub 官方 Markdown 指南。

引用与行内代码

源码：

> 设计被接受，不等于功能已经交付。


使用 `git worktree` 可以并行管理本地工作目录。

渲染效果：

设计被接受，不等于功能已经交付。

使用 git worktree 可以并行管理本地工作目录。

任务清单

源码：

- [x] 需求已澄清
- [x] 方案已评审
- [ ] 集成测试已通过

渲染效果（在支持任务清单的阅读器中显示为复选框）：

  • 需求已澄清
  • 方案已评审
  • 集成测试已通过

代码块

源码（下面特意用 text 标记外层，展示三个反引号）：

```json
{"status":"ready","version":"1.2.0"}
```

渲染效果：

{"status":"ready","version":"1.2.0"}

看懂标题、段落、列表、链接、强调、引用、代码和任务清单，通常就足以阅读绝大多数工程 Markdown。更复杂的格式不必全部记忆，可以随用随查。图片也可以用 ![流程示意](images/markdown-workflow.jpg) 引用本地资源，这使图文资料能够和代码一起管理。

三、在 AI 之前：Markdown 已经贯穿一次软件变更

只把 Markdown 理解为“写 README 的格式”，会低估它在工程协作中的作用。以“为报表增加异步导出”为例，一次变更可能在不同时间产生多个 Markdown 对象。它们并非五套独立文档，而是同一项工作留下的连续记录。

从 README 到 Issue：先让目标有共同语境

README.md 帮助后来者理解项目的作用、环境和最基本的工作入口，例如：

# 报表服务


提供报表查询与导出能力。


- 开发环境：参见 `docs/development.md`
- 验证方法：参见 `CONTRIBUTING.md`

当出现“导出大数据量报表超时”的需求时，可以用 GitHub **Issue（议题或工作事项）**记录可验证的目标：

## 背景
大数据量报表导出可能超时。


## 验收条件
- [ ] 按用户权限导出
- [ ] 支持异步任务与状态查询
- [ ] 失败时可获取明确错误原因

Issue 的重要性不在于标题是否漂亮，而在于它能被讨论、关联代码变更和追踪处理状态。GitHub 提供 .md Issue 模板及 YAML Issue 表单的配置说明；后者更适合需要校验必填字段的场景。

从 RFC 到 ADR：让方案和决策可以被评审

对于简单功能，Issue 澄清后可以直接实现；但如果报表异步导出会影响任务队列、数据库结构和错误处理，就值得先评审设计。

  • **RFC（Request for Comments，征求意见提案）**帮助讨论尚未确定的方案。一个 RFC 应解释问题、目标、可选实现、主要权衡以及需要社区反馈的部分。
  • **ADR（Architecture Decision Record，架构决策记录）**则更重视保留已经作出的重要决定，包括背景、备选方案、决策和后果。

例如，ADR 可以记录一项明确选择：

# 采用异步导出任务队列


## 背景
同步导出容易占用请求处理资源。


## 决策
引入任务队列与状态查询接口。


## 后果
需要处理重试、超时、权限与任务清理。

当文档与代码都在 Git 仓库中，这类方案可以像代码一样经过 PR 审查。可以阅读真实的 Rust RFC 仓库 与 ADR 社区指南，但不必要求所有小修改都采用正式提案流程。

从 PR 到版本记录：让实现与原始目标相连

实现完成后，PR 的 Markdown 描述应当帮助评审者把代码变更与前面的目标对应起来：

## 关联工作
Closes #128


## 变更摘要
- 增加异步导出任务
- 增加权限验证与失败状态


## 验证证据
- [x] 单元测试
- [ ] 集成环境验收


## 风险与恢复
旧接口保持兼容；发布时可关闭新入口。

仓库可以通过 Pull Request 模板（GitHub 官方中文） 提示作者填写这些信息。合并后，Release Notes 或 Changelog 又可以沿着 PR 与 Issue 说明版本变化。

**Commit Message（提交信息）要单独看待。**Git 存储的是纯文本提交消息，不要求它是 Markdown 文件。提交正文可以使用列表等人类可读格式，但各终端与平台的渲染并不一致。常见的约定式提交示例是：

feat(report): 支持异步导出


- 增加任务状态查询
- 补充权限验证


Refs: #128

相关约定可参考约定式提交（Conventional Commits）中文规范。至此，README 提供项目背景，Issue 定义问题，RFC/ADR 记录设计，PR 组织评审，提交和发布记录保留实现历史；Markdown 将它们连接在同一个可以版本化的工程环境中。

四、进入 AI 时代：Markdown 成为可持久化的工作上下文

AI 编程助手需要的不只是当前一句提示，还包括仓库结构、可修改范围、验证方式和团队约定。把这些信息保存在 Markdown 中，具备两个直接收益：人和 Agent 可以读取同一份约定；约定的变更可以接受 Git 审查，而不必依赖个人聊天记录。

所谓“Markdown 是 AI 的母语”，是一种强调普及程度与工具兼容性的比喻，而不是说大模型只能理解 Markdown 或这种格式天然最准确。它的优势来自纯文本、清楚的层级、广泛的工具支持以及低成本的版本化。

在现代 Agent 工具生态里，三个名字值得区分：

  • AGENTS.md：面向兼容编码 Agent 的项目级说明，通常包括项目结构、验证命令、不得修改的区域等。参见 AGENTS.md 开放约定。
  • CLAUDE.md：Claude Code 使用的项目上下文说明文件；与 AGENTS.md 目标相似，但发现规则和支持范围以具体产品为准。参见 Claude Code 官方说明。
  • SKILL.md：Agent Skills 规范中一项可复用技能的入口，通常包含 YAML frontmatter 和 Markdown 正文，可附带脚本与参考资料；它是“怎样处理某类任务”的说明，不是仓库的通用说明书。参见 Agent Skills 规范。

项目级说明可以很简短：

# 项目约定


- 修改导出接口时同步更新测试。
- 先复用已有服务和依赖。
- 不在仓库中保存密钥。
- PR 必须说明验证结果与风险。

而一个专门审查 PR 的 Skill 可能采用如下结构：

---
name: review-export-pr
description: 检查报表导出相关变更和验证证据
---


# 检查要点
1. 阅读关联 Issue 和设计说明。
2. 检查权限、异常路径和自动化测试。
3. 输出需要开发者确认的风险。

两者区别在于：项目约定提供持续生效的背景，Skill 提供按需触发的专业工作方法。真实目录结构可参考 Anthropic Skills 和 OpenAI Skills。使用第三方 Skill 仍要审查其中的脚本、权限和外部连接，不能仅因为采用 Markdown 就认为它安全。

五、从文档走向源码：哪些变化是真正新的

过去，Markdown 往往被看作代码旁边的说明材料；在 AI Agent 参与开发时，出现了一种更进一步的实践：把描述业务意图、边界和验收条件的 Markdown 当作持续维护的工程输入，让实现和测试受它约束。

2026 年 9 月，htmx 创建者 Carson Gross 在 《Markdown in /src》 中提出：描述软件意图的 Markdown 可以和产生的代码一起存放在 src/，代码与测试应尽可能由持久保存的 Markdown 派生，而不是只依据短暂的提示词对话。这是值得研究的探索性观点，并非软件行业已经普遍采用的成熟标准。

对于上面的异步导出，可以想象仓库内存在：

src/
  export/
    requirements.md   # 权限、任务状态、失败与重试规则
    service.ts        # 实现
    service.test.ts   # 可执行的验证

当需求变化时，团队先评审 requirements.md，再由开发者或 Agent 修改实现与测试；而 CI 用自动化检查和必要的人类评审判断这些改动是否符合接受标准。这样 Markdown 从“事后解释代码”变成了“影响代码演进的上游依据”。

需要注意三个不能省略的条件：

  1. 约束必须能够验证：一句“性能要好”不能代替量化验收条件、测试或真实的运行数据。
  2. 文件与实现必须保持一致：修改了文档却未更新代码，或绕过文档直接修改行为，都会导致偏离；需要相应检查与审查制度。
  3. 格式选择仍应服从需求：类型严格的接口契约、配置和数据交换可能需要 OpenAPI、JSON Schema、JSON 或 YAML，而不只是自由文本。

因此，讨论“Markdown 正在成为源码”时，更准确的理解是：一些 Markdown 文件正被提升为有版本、有审查、有验证责任的规范性工程输入。它并不意味着所有 .md 文件都能直接执行，更不意味着可以取消代码和测试。

六、边界与结论：一套通用表达，不是万能规范

Markdown 最适合的是需要人理解、讨论和持续修订的内容：项目入口、需求说明、设计决定、PR 描述、知识沉淀、Agent 指令。对于严格结构、类型验证或程序间通信，JSON（JavaScript Object Notation）、YAML、OpenAPI 等格式通常更合适；对于系统行为本身，仍需要可执行代码、自动化测试与运行证据。

它在现代软件工程中的作用经历了一条清晰的发展路径：先让文档成为可读纯文本，再让文档进入 Git 和协作流程，进而让部分文档成为人与 AI Agent 共同维护的工程约束。 这种路径比“Markdown 能取代所有格式”的说法更接近实际，也更能指导团队建立可长期维护的知识和研发工作方式。

参考规范与真实项目

以下资料优先选择原始规范与官方文档。正文示例均为本文编写的精简模板，不冒充项目原始内容。

  1. Markdown — 原始发布说明：设计动机与基本语法。
  2. CommonMark：基础 Markdown 的规范化语法及测试。
  3. GitHub Flavored Markdown：GitHub 的 Markdown 扩展规范。
  4. GitHub 官方中文：基础写作和格式语法：常见语法与显示行为。
  5. GitHub 官方中文：README 介绍：项目入口文件的用途。
  6. GitHub 官方中文：配置 Issue 模板：Markdown 模板与 YAML 表单。
  7. GitHub 官方中文：创建 PR 模板：规范变更说明。
  8. Rust RFC 仓库：真实的设计提案与讨论机制。
  9. ADR 社区指南：架构决策记录的结构与资源。
  10. Conventional Commits（中文）：结构化提交约定。
  11. AGENTS.md：项目级 Agent 说明约定。
  12. Claude Code 项目记忆：CLAUDE.md 的官方说明。
  13. Agent Skills Specification：SKILL.md 的格式与入口定义。
  14. Anthropic Skills 与 OpenAI Skills：真实技能目录范例。
  15. htmx：《Markdown in /src》：讨论持久化 Markdown 驱动代码与测试的探索性观点。

Comments