塑造编码代理行为的新兴 Markdown 格式

项目知识正在迁移到源代码旁边，编码代理可以在那里发现它们，并将意图转化为实现。

多年来，修改软件所需的知识分散在架构文档、ADR（架构决策记录）、安全审查、Wiki、工单、事故报告以及经验丰富的开发者的头脑中。

仓库保存的是实现。开发者收集周边上下文，运用判断力，将两者转化为代码。

这个边界正在改变。一个为代理准备好的仓库，越来越多地不仅包含源代码、测试、配置和依赖，还包含正确修改它们所需的知识。

越来越多的 Markdown 文件以编码代理可以发现和使用的方式捕获这些知识。这些文件共同构成一个元代码层：让人类意图和判断对代理清晰可读。

1. 入门与常驻规则

人类只需加入项目一次。编码代理则在每次开始任务时，实际上都要重新上手一次。

AGENTS.md 最接近为代理准备的中立 README。它可以描述仓库结构、构建和测试命令、编码约定以及 pull request 预期。嵌套文件可以为特定包或子系统添加规则。

厂商原生的替代方案扮演相同角色：CLAUDE.md 和 .claude/rules/、GEMINI.md、GitHub Copilot 指令文件，以及 .clinerules/。

这些文件回答的是：在众多任务中，什么应当始终成立？

2. 技能封装可重复流程

常驻规则不同于流程。

代理技能描述的是如何执行某一类特定工作。例如，数据库迁移技能可能会检查 schema、创建迁移、更新生成的类型、运行兼容性检查、验证回滚，并准备审查摘要。

开放的 Agent Skills 规范将这一工作流打包到必需的 SKILL.md 中，并附带可选的脚本、参考资料、模板和资源。

这个边界很有用：

• AGENTS.md 承载常驻上下文和约束。
• SKILL.md 承载为特定任务调用的可重复流程。

3. 规格说明、计划和任务让变更意图可审查

当设计和规划只存在于聊天中时，它们会随之消失。版本化的 Markdown 将它们转化为工件，人们可以在代理实施之前进行审查。

GitHub Spec Kit 使用一条清晰的链路：

• spec.md 记录需求和预期结果。
• plan.md 说明技术设计和实现方法。
• tasks.md 将计划拆分为可执行的单元。
• 代理实施并验证变更。

OpenSpec、Kiro Specs 以及项目特定的 PLANS.md 文件使用不同的约定，但最终都收敛于相同的拆分方式：需求、设计、计划、任务、实现和验证。

4. 领域文件承载专业上下文

通用入门信息无法完整描述每个系统。

ARCHITECTURE.md 可以捕获系统边界、依赖、NFR（非功能需求）和长期决策。DESIGN.md 可以承载视觉和设计系统意图。AUTH.md 可以描述一套认证实现方法。REVIEW.md 可以定义代码审查的优先事项和验证预期。

它们的成熟度各不相同。ARCHITECTURE.md 已经是一种成熟的文档约定，而几种领域特定格式仍属于厂商特定或实验性质。尽管如此，方向是明确的：专业工程知识正在变得对代理直接可读。

read image descriptionALT

5. 记忆让学到的上下文持久化

有些知识是预先设计好的。另一些知识则只在软件构建和运行过程中才会出现。

代理记忆会保存经验教训，例如意外的构建前置条件，或跨会话反复出现的调试模式。Claude Code 做了一个重要区分：人类编写共享项目指导，而代理将自动记忆写入仓库之外的 MEMORY.md 和主题文件中。

机器本地的记忆不应悄无声息地成为团队共识。一种实用的提升路径是：

• 代理在本地记录一条临时观察结果。
• 当它反复出现或影响共享工作时，由人类进行审查。
• 持久性知识被移入项目规则、技能、ADR 或领域文档。

临时性知识留在本地。经过审查的知识成为共享知识。

read image descriptionALT

整合元代码层

一个项目不需要包含所有文件。使用代理能够可靠发现的最小集合即可。将经过审查的知识放在源代码旁边；当其他文件已经是权威来源时，厂商特定文件只需充当轻量兼容桥。

仓库正在成为源代码与元代码的交汇点：需求、NFR、架构、设计、规则、流程、计划和持久性知识。

当代理能够同时读取两者时，它们扮演着意图编译器的角色。源代码成为人类意图和判断在对代理清晰可读之后所产生的可执行副产品。

工程任务在于让元代码保持范围明确、经过审查且与时俱进。它不会取代测试或审查。它为下一次代码变更提供更好的来源。

完整文章包含详细的格式全景、成熟度说明、示例和主要来源：

https://generativeprogrammer.com/p/emerging-markdown-formats-that-shape