Markdown 规范如何指导 AI Agent 改代码

新兴 Markdown 格式如何塑造编码 Agent 行为

一份实用地图，展示了规则、流程、计划、领域知识和内存，指导了 Agent 辅助的软件变更。

多年以来，改变软件所需的知识分散在许多地方。非功能性需求（NFRs）、架构约束和设计决策被记录在解决方案架构文档、ADR、安全审查和维基中。产品意图存在于设计文档和原型中。工作被分解为工单。操作经验记录在事件报告、Slack 线程、手册和资深开发人员的头脑中。

仓库包含了实现：源代码、测试、配置和依赖清单。开发人员阅读周围的各种制品，调和期望的结果与架构判断，然后将两者转化为代码。

随着 AI 辅助编码变成常态，仓库正在成为项目知识与 Agent 变更软件之间的汇聚点。单体仓库将代码库及其依赖图汇集在一起。一个支持 Agent 的仓库还需要汇集正确改变它们所需的知识。

软件始终通过不同的视角被理解：原则和 NFR、架构和设计、具体规范、实现计划、领域规则，以及在操作中学到的经验教训。一个不断增长的 Markdown 文件族现在以编码 Agent 能够发现和使用的形式捕捉这些维度。本文介绍了正在新兴的格式和工具。总体而言，它们让 Agent 能够充当意图编译器，将人类的意图和判断转化为源代码。

Agent 入职始于面向 Agent 的 README

一个人只需向项目入职一次。一个 Agent 实际上每次启动任务时都要入职。它需要在仓库中定位自己，发现相关的命令和惯例，并在改变任何东西之前理解适用的规则。

AGENTS.md 是最接近这个目的的中立标准。项目将其描述为面向 Agent 的 README。一个根文件可以解释仓库结构、构建命令、测试、编码惯例和拉取请求期望。嵌套文件可以为包或子系统添加说明。该格式故意没有必需字段。

生态系统还有厂商原生的替代方案服务于同样的目的：

AGENTS.md 为 Codex、Cursor、Cline、Copilot、OpenCode 和其他兼容的 Agent 提供跨工具项目指导。

CLAUDE.md 和 .claude/rules/ 为 Claude Code 提供项目范围和路径范围的指导。

GEMINI.md 为 Gemini CLI 提供分层上下文。

.github/copilot-instructions.md 和特定路径的指令文件指导 GitHub Copilot。

.clinerules/ 为 Cline 携带持久性和条件性规则。

使用 pnpm 而非 npm。不要编辑生成的客户端。在改变发票流程后运行计费集成测试。在移动服务边界之前阅读相关 ADR。这些是应该在许多任务中保持不变的常设指导。

一旦 Agent 理解了仓库，下一个问题是如何执行特定类型的工作。

技能包装可重复的流程

一个技能是为特定类型的工作定制的手册。

考虑一个数据库迁移。AGENTS.md 可能声明每个模式变更都需要一个回滚路径。一个迁移技能可以描述完整的流程：检查当前模式、创建迁移、更新生成的类型、运行兼容性检查、验证回滚，以及准备审查摘要。

开放 Agent 技能规范给了这个手册一个可移植的包。每个技能都有一个必需的 SKILL.md，包含元数据和说明。它还可能包括脚本、参考资料、模板和其他资产。Agent 最初看到元数据，当技能相关时加载完整说明，然后按需访问支持材料。

Agent 技能起源于 Anthropic，并作为开放标准发布。它们独立于 MCP，Anthropic 贡献给了智能 AI 基金会。该技能格式现已由 Codex、Gemini CLI、GitHub Copilot 和其他兼容客户端记录。

边界是具体的：

AGENTS.md 和原生规则文件描述常设上下文和约束。

SKILL.md 描述为特定任务调用的可重复流程。

一个流程解释了如何工作。它仍然需要一个经过审查的应该构建什么的描述。

计划文件使软件设计可审查

软件设计、计划和任务分解也在迁移到版本控制的 Markdown。当它们只存在于聊天中时，它们消失在会话历史中。当它们成为仓库制品时，架构师和开发人员可以在 Agent 将其转化为实现之前进行审查。

GitHub Spec Kit 是最清晰的主流例子。其文档报告超过 121,000 个 GitHub 星星和 35 个编码 Agent 集成。其默认工作流使用一系列文件：

spec.md 记录需求和期望的结果。

plan.md 解释技术设计和实现方法。

tasks.md 将计划分解为可执行的单位。

Agent 实现和验证变更。

项目宪章可以承载应该在许多变更中应用的原则。

Spec Kit 不是唯一的方法。OpenSpec、Kiro Specs 和项目特定的 PLANS.md 使用不同的文件和工作流。尽管如此，它们正在汇聚到一个可识别的序列：需求、设计、计划、任务、实现和验证成为人类可以审查、Agent 可以遵循的独立制品。

这些文件描述了一个通用的软件开发生命周期。应用程序还需要针对其特定领域的说明。

领域文件为 Agent 提供专业上下文

前端、身份平台和数据管道不需要相同的上下文。领域文件为 Agent 提供了针对通用入职、技能和计划无法充分描述的系统部分的专业说明。

ARCHITECTURE.md 可以描述系统边界、组件、依赖、NFR 和长期的架构决策。这是一个既定的人类文档惯例，当项目说明告诉它们何时读取时，它对 Agent 变成可操作的。

Google Labs 的 DESIGN.md 描述了视觉身份、设计令牌、组件和设计原理。该项目目前将该格式标记为 alpha。

WorkOS 的 AUTH.md 是一个实验性的、服务托管的方案，教导 Agent 如何代表用户注册和认证。

Kilo 的 REVIEW.md 让仓库定义审查优先级、严重性、跳过的文件、验证期望，以及审查 Agent 应该如何分配工作。

这些格式有不同的成熟度和范围。ARCHITECTURE.md 是一个长期存在的文档惯例。DESIGN.md、AUTH.md 和 REVIEW.md 是新兴的、特定领域的实验。它们的共同方向很清楚：更多的专业工程知识正变成直接对 Agent 可读的形式。

其中一些知识是提前设计的。其他知识仅在软件被构建和操作时才显现。

内存让学到的上下文持久化

一个意外的构建先决条件、一个调试模式，或者部署失败的原因之前可能最终出现在工单评论、提交消息、Slack 线程、事件报告或 SRE 手册中。这些记录的范围从短暂到持久，但编码 Agent 在开始下一个任务时可能找不到相关的经验教训。

Agent 内存将学到的上下文与仓库关联起来，并在会话中可用。Claude Code 使作者身份区分变得异常清晰：

人类将 CLAUDE.md 写入以提供共享的说明、惯例和项目上下文。

Claude 将自动内存写入 MEMORY.md 索引和可选的主题文件，如 debugging.md 和 api-conventions.md。

自动内存是特定于仓库的但机器本地的。Claude 通常将其存储在 Git 仓库之外，不会自动与团队共享。Anthropic 将这两种机制分别记录。

内存因此不会取代工单、提交历史或操作文档。它减少了重复的发现。当学到的事实对整个团队变得重要时，它需要一个提升路径：

Agent 在本地内存中记录一个初步观察。

当观察重复或影响共享工作时，人类审查它。

持久知识移动到项目规则、技能、ADR 或领域文档旁边的源代码。

初步知识保持本地。经审查的知识变成共享。Kilo 正在为审查进行类似的循环实验：它可以分析团队对审查评论的响应，并提议更改仓库的审查指导。

把 Markdown 文件汇集在一起

项目知识从分散的系统移动到支持 Agent 的仓库，其中版本控制的意图可以指导实现。

实际的区别是每个文件的角色、谁写它，以及它得到多广泛的支持。

这些格式的范围从跨工具标准和既定的厂商惯例到新兴的特定领域实验。

一个项目不需要每个文件。使用 Agent 能够可靠发现的最小文件集，让审查过的知识与源代码并肩，并将厂商特定的文件视为当另一个文件是规范时的薄兼容桥接。AUTH.md 保持服务托管，而 Claude 的自动内存保持机器本地直到人类将持久经验教训提升到仓库中。

仓库正在成为源代码和元代码之间的汇聚点：承载需求、NFR、架构、设计、规则、流程、计划和持久学习的 Markdown。

当 Agent 可以读取两者时，它们充当意图编译器。源代码变成了副产品：人类意图和判断的可执行结果，对 Agent 变成可读的。

工程任务是保持元代码范围化、经过审查和最新。它不会取代测试或审查。它为下一个代码变更提供了一个更好的源头。

最初发表在《生成编程程序员》上。