AI Coding Agent 的 prompt 格式正在标准化：规则/流程/记忆如何引导代码修改

多年以来，更改软件所需的知识散落在各个地方。非功能性需求（NFRs）、架构约束和设计决策被记录在解决方案架构文档、ADR、安全评审和 wiki 中。产品意图存在于设计文档和原型中。工作被分解为工单。运维经验存活在事故报告、Slack 帖子、操作手册和资深开发者的脑海中。

代码仓库只包含实现部分：源代码、测试、配置和依赖清单。开发者横跨周围的各种产物阅读，将预期结果与架构判断进行对齐，然后将两者翻译成代码。

随着 AI 辅助编程逐渐成为常态，代码仓库正在成为项目知识与修改软件的 Agent 之间的交汇点。monorepo 将代码库及其依赖图汇聚在一起。一个对 Agent 友好的仓库还会带入正确修改它们所需的知识。

软件一直通过不同的视角来理解：原则与 NFRs、架构与设计、具体规格说明、实现计划、领域规则以及运营过程中学到的经验。一类日益壮大的 Markdown 文件家族正在以编码 Agent 可以发现和使用的方式捕捉这些维度。本文审视了正在兴起的格式和工具。它们共同使得 Agent 能够作为意图编译器运作，将人类意图和判断翻译成源代码。

Agent 入职从面向 Agent 的 README 开始

人类入职一个项目只需要一次。Agent 每次开始任务时实际上都要经历一次入职过程。它需要自我定位仓库、发现相关的命令和约定，并在修改任何内容之前了解适用的规则。

AGENTS.md 是实现这一目的最接近中立标准的东西。项目方将其描述为面向 Agent 的 README。根文件可以解释仓库结构、构建命令、测试、编码约定和 Pull Request 期望。嵌套文件可以为某个包或子系统添加说明。该格式刻意没有必填字段。

生态系统中也有实现相同目的的厂商原生替代方案：

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 理解了仓库，下一个问题就是如何执行某类特定的工作。

Skills 将可重复的流程打包

Skill 是针对特定类型工作量身定制的操作手册。

以数据库迁移为例。AGENTS.md 可能会说明每个 schema 变更都需要回滚路径。迁移 Skill 可以描述完整流程：检查当前 schema、创建迁移、更新生成的类型、运行兼容性检查、验证回滚，并准备评审摘要。

开放的 Agent Skills 规范为这种操作手册提供了可移植的包。每个 Skill 有一个必需的 SKILL.md，包含元数据和指令。它还可以包含脚本、参考资料、模板和其他资产。Agent 最初看到元数据，在 Skill 相关时加载完整指令，然后按需访问支持材料。

Agent Skills 起源于 Anthropic，并以开放标准的形式发布。它们独立于 MCP——Anthropic 向 Agentic AI Foundation 贡献了 MCP。Skill 格式现在由 Codex、Gemini CLI、GitHub Copilot 及其他兼容客户端所记录。

边界是明确的：

AGENTS.md 和原生规则文件描述持续性的上下文和约束。

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

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

规划文件使软件设计可评审

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

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

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

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

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

Agent 实现并验证变更。

项目宪章可以携带应该跨多个变更适用的原则。

Spec Kit 不是唯一的方法。OpenSpec、Kiro Specs 和项目特定的 PLANS.md 使用不同的文件和工作流。但它们正在向一个可识别的序列收敛：需求、设计、计划、任务、实现和验证成为独立的产物，人类可以评审，Agent 可以遵循。

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

领域文件赋予 Agent 专业化上下文

前端、身份平台和数据管道不需要相同的上下文。领域文件为 Agent 提供针对系统特定部分的专门指令，而这些是通用入职、Skill 和计划无法完全描述的。

ARCHITECTURE.md 可以描述系统边界、组件、依赖、NFRs 和长期存在的架构决策。这是一种成熟的人类文档约定，当项目指令告诉 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 使 authorship distinction 异常清晰：

人类编写 CLAUDE.md 来提供共享指令、约定和项目上下文。

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

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

因此，记忆不会取代工单、提交历史或运维文档。它减少了重复发现。当一个习得的事实对整个团队重要时，它需要一个晋升路径：

Agent 将试探性观察记录在本地记忆中。

当观察反复出现或影响共享工作时，人类对其进行评审。

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

试探性知识保持在本地。经过评审的知识成为共享知识。Kilo 正在为评审试验一个类似的循环：它可以分析团队如何响应评审评论，并建议对仓库的评审指南进行修改。

将 Markdown 文件组合在一起

共享项目文件将经过评审的知识携带到源代码旁边。Agent 编写的记忆在持久性经验晋升到仓库之前保持在机器本地。

实际区别在于每个文件所扮演的角色、谁编写它以及它被多广泛地支持。

这些格式从跨工具标准和成熟的厂商约定，到新兴的领域特定实验不等。

一个项目不需要每个文件。使用最小的、Agent 可以可靠发现的文件集，将经过评审的知识保留在源代码旁边，并将厂商特定的文件作为兼容性桥，当另一个文件是规范的时候。AUTH.md 保持服务托管，而 Claude 的自动记忆在人类将持久性经验晋升到仓库之前保持在机器本地。

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

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

工程任务是保持那个元代码有作用域限制、经过评审且保持最新。它不能取代测试或评审。它只是给下一次代码变更一个更好的来源。

原文发表于 The Generative Programmer。