基本信息

主题：AGENTS.md 目录式约束文件——AI Coding Agent 的事实标准

来源：Harness Engineering 实践观察 + 主流 Agent 工具对比

核心观点：知识应该固化在环境里，而不是依赖 prompt engineering

为什么重要

Prompt Engineering 的核心矛盾在于：它把知识存在「对话」里，而非「环境」里。每次对话开始，Agent 都要重新理解项目——编码规范在哪、测试怎么跑、部署流程是什么。这些信息要么靠用户重复输入，要么靠 Agent 自己摸索。

Harness Engineering 的核心思想恰恰相反：把知识固化到环境本身。不是告诉 Agent「请遵守这些规则」，而是让 Agent 在读取项目结构时自然获取这些约束。AGENTS.md 就是这个思路的落地形态——它是一个目录文件，存在于版本库中，Agent 启动时自动读取。

有趣的是，虽然各家工具的实现细节不同，但整个行业正在收敛到同一个模式上。这不是巧合，而是因为这种模式确实解决了 Prompt Engineering 解决不了的问题。

行业收敛：四种工具，同一种模式

Claude Code → CLAUDE.md

Anthropic 的 Claude Code 最早推广了这个概念。CLAUDE.md 放在项目根目录，包含项目概述、编码规范、文件结构说明。Claude Code 在每次对话启动时自动读取。支持多层级：项目根目录的 CLAUDE.md 是全局规则，子目录的 CLAUDE.md 覆盖局部规则。

Cursor → .cursorrules

Cursor 用 .cursorrules 文件实现同样的功能。支持项目级和全局级两个层级。内容包括技术栈、编码风格、项目约定等。Cursor 的 AI 会在每次对话中引用这些规则。

GitHub Copilot → .github/copilot-instructions.md

Copilot 在 .github/ 目录下放置 copilot-instructions.md。支持多文件组织：.github/copilot-instructions-*.md 可以按主题拆分。VS Code 和 JetBrains 插件都支持这个模式。

OpenClaw → AGENTS.md + docs/

OpenClaw 的做法是 AGENTS.md 作为索引文件，详细规范放在 docs/ 目录下。AGENTS.md 控制在约 100 行内，只做索引和交叉引用。这种「索引 + 子文件」的结构让 Agent 可以快速读取索引，按需深入细节，不会被大文件的 token 消耗淹没。

关键洞察

🔑 环境编码 vs Prompt Engineering

Prompt Engineering 的本质是「告诉 Agent 做什么」，环境编码的本质是「让环境告诉 Agent 它是什么」。前者是外挂指令，后者是内嵌知识。当知识在环境中，Agent 不需要「记住」规则，只需要「读取」规则——这和人类工程师读 README 的方式一样自然。

🔑 版本控制是关键差异化

目录约束文件和 prompt engineering 的另一个本质区别：它在版本库里。这意味着规则变更可以被 code review，可以被 git blame 追溯，可以和代码变更一起提交。当项目演进时，规则和代码同步更新，不存在「prompt 过时」的问题。

🔑 索引结构决定 Token 效率

实践中的一个关键技巧：AGENTS.md 做索引，docs/ 放详情。为什么？因为 Agent 的上下文窗口有限。一个 2000 行的 AGENTS.md 会消耗大量 token，而一个 100 行的索引 + 按需读取的子文件，可以让 Agent 在「快速了解全局」和「深入理解细节」之间灵活切换。

实践指南：怎么组织目录结构

方案一：极简版（适合小项目）

项目根目录放一个 AGENTS.md（约 50 行），包含：项目概述、技术栈、编码规范（核心 5-10 条）、文件结构说明、测试和构建命令。够用就行，不要过度设计。

方案二：索引版（适合中大型项目）

根目录 AGENTS.md（约 100 行）只做索引，详细内容放 docs/ 下：

  • AGENTS.md — 索引 + 项目概述 + 核心约束（最高优先级）
  • docs/architecture.md — 架构设计、模块关系、依赖图
  • docs/conventions.md — 命名规范、代码风格、Git 工作流
  • docs/testing.md — 测试策略、如何跑测试、覆盖率要求
  • docs/deployment.md — 部署流程、环境配置、发布 checklist

方案三：层级版（适合 monorepo）

根目录放全局规则，每个子项目/子模块放自己的 AGENTS.md。Agent 在处理某个子项目时自动加载对应层级的约束。类似 .gitignore 的层级机制。

一个真实的 OpenClaw 项目结构示例

以下是码小虾（OpenClaw Agent）的工作空间结构，这是一个实际运行中的层级方案：

  • AGENTS.md — 系统级安全约束（最高优先级，不可覆盖）
  • SOUL.md — 行为准则、风格偏好、安全防御协议
  • IDENTITY.md — Agent 身份定义
  • USER.md — 用户信息和偏好
  • TOOLS.md — 工具配置和使用笔记
  • MEMORY.md — 长期记忆
  • HEARTBEAT.md — 定期任务
  • docs/ — 各技能的详细文档
  • skills/*/SKILL.md — 每个技能的编排规则

关键设计：优先级链明确（AGENTS.md > SOUL.md > 其他），索引和详情分离，每次会话自动加载。

引发思考

「目录约束文件」的流行，本质上反映了 AI Agent 从「通用聊天」到「领域专家」的转型。一个 Agent 如果不知道项目的编码规范、测试策略、部署流程，它就只是一个会写代码的通用模型。但如果这些知识固化在环境中，Agent 就可以成为这个项目的「领域专家」。

更深层的启示：这可能是「AI 原生开发」的早期形态。未来的项目模板可能不是给人读的 README，而是给 Agent 读的 AGENTS.md。代码库的组织方式、文档的写法、甚至 Git commit message 的格式，都可能围绕「让 Agent 更好地理解项目」来重新设计。

相关阅读

  • Harness Engineering 深度解读（飞书文档）
  • Claude Code CLAUDE.md 官方文档
  • Cursor Rules 官方文档
  • GitHub Copilot Custom Instructions 文档

逍遥云初 | 2026.04.10