What Makes a Good AGENTS.md

来源：Ben's Bites，2026-03-19

AGENTS.md 是什么

AGENTS.md / CLAUDE.md 是在对话开始前就预加载的指令文件。

系统提示：每个模型都有来自产品方的 system prompt
你的文件：AGENTS.md 会被追加进去
结果：模型在你对话前就已加载 system prompt + 你的指令

CLAUDE.md vs AGENTS.md

文件	适用范围
CLAUDE.md	专属于 Claude 产品
AGENTS.md	跨工具通用（Codex/Droid/Pi/大多数工具）

可以 symlink：把 AGENTS.md 链接到 CLAUDE.md，只维护一份，所有 Agent 自动识别。

什么该写进 AGENTS.md？

❌ 旧观点（已被推翻）

包含技术栈、关键文件、架构——作为 Agent 的"迷你地图"。

研究发现：这会让性能下降、成本增加 20%（多消耗 token）。

Agent 可以非常快速地自己找出技术栈、关键文件、命令和架构。

✅ 正确做法

保持相对空白，只写你的偏好和修正 Agent 行为的微调。

示例：

- 构建时，用 agent-browser skill 打开浏览器测试，然后再给我 URL（抓 bug）
- 网页搜索用 Exa 工具
- 规划文件总是写到 ~/[project-name]/plan/
- 我不会写代码，用简单语言解释
- 录制输出视频，让我看到你测试了什么

进阶技巧：条件块

Dex 的建议——用条件块包装特定场景的指令：

<important if="simple web page">
  - 不需要 spec
  - 选择前先出3个设计选项
</important>

<important if="database migration">
  - 必须提供 rollback 方案
  - 先在 staging 测试
</important>

核心原则

少即是多 — 不要试图预加载所有信息
偏好 > 信息 — Agent 自己能发现的信息不需要写
具体 > 抽象 — 给出具体的行为修正，而非泛泛的原则
场景化 — 用条件块处理不同场景的不同需求

关联

claude-code/pawelhuryn-claude-decision-engine — CLAUDE.md 作为决策引擎
claude-code/lessons-building-skills — Claude Code Skills 实践
claude-code/overview — Claude Code 概述

Sources

2026-03-19 What makes a good AGENTS