🚀 拒绝“人工智障”：如何写出一份高质量的 agent.md？

🚀 拒绝"人工智障"：如何写出一份高质量的 agent.md？

在 AI 辅助编程日益普及的今天，你是否遇到过这样的情况：

• 每次新开一个对话，都要费尽口舌向 AI 解释项目是用什么框架写的。
• AI 写的代码总是很难看，完全不符合团队规范。
• AI 甚至经常"幻觉"，引用不存在的文件或库。

其实，这些问题很大程度上是因为你没有给 AI 一个好的"入职指南"。对于 Claude 来说是 CLAUDE.md，对于开源 Agent 体系（如 OpenCode, Zed, Cursor 等），这个文件通常被称为 AGENTS.md 或我们这里统称的 agent.md。

今天我们就来聊聊，如何写出一份高质量的 agent.md，让你的 AI 队友瞬间变身资深工程师！😎

核心原理：LLM 是"失忆"的

首先我们要明白一个残酷的事实：LLM 是无状态的。 每次你开启一个新的 Session，AI 对你的代码库一无所知。它就像一个刚刚入职、甚至还没来得及看文档的实习生。

agent.md 就是你发给它的第一份入职手册。它是唯一一个默认会被注入到每一次对话上下文中的文件。

这意味着：

1. 从零开始：AI 每次都是白纸一张。
2. 必须显式告知：重要的信息必须每次都告诉它。
3. agent.md 是最佳载体：这是目前最标准的上下文传递方式。

什么是好的 agent.md？

一份优秀的 agent.md 应该包含三个维度的信息，帮助 AI 快速建立对项目的认知：

• WHAT (是啥) ：技术栈是什么？项目结构是怎样的？（特别是 Monorepo！）
• WHY (为啥) ：项目的核心目标是什么？各个模块的职责是什么？
• HOW (咋整) ：如何构建？如何测试？有哪些特殊的工具链（比如用 bun 不用 npm）？

❌ 错误示范：大杂烩

很多人的 agent.md 恨不得把整个开发文档都塞进去：

# 项目文档
... (此处省略 500 行代码规范) ...
... (此处省略 200 行数据库 Schema) ...
... (此处省略 100 行部署脚本) ...

千万别这么干！ 🙅‍♂️

黄金法则：Less is More (少即是多)

1. 别把 AI 当 Linter 用

这是最常见的误区。不要在 agent.md 里写详细的代码风格指南！

• 成本高：LLM 的推理成本比 Linter 高出几个数量级。
• 效果差：LLM 是基于概率的，它很难 100% 严格遵守每一条缩进规则。
• 占用上下文：大量的 Style Guide 会挤占宝贵的 Context Window，导致 AI 忽略真正重要的业务逻辑。

✅ 正确做法： 配置好 ESLint, Prettier 或 Biome。如果代码格式不对，让 Linter 报错，甚至配置 Git Hook 自动修复。把专业的事交给专业的工具。

2. 保持精简 (< 300 行)

研究表明，随着指令数量的增加，LLM 遵循指令的能力会呈指数级（小模型）或线性（大模型）下降。 Claude Code 的 System Prompt 已经包含了约 50 条指令。如果你再塞进去几百条，AI 就会开始"顾此失彼"。

建议：

• 核心 agent.md 最好控制在 300 行以内 ，甚至 60 行以内。
• 只放全局通用的指令。

3. 渐进式披露 (Progressive Disclosure) 🧠

如果项目真的很复杂，怎么办？ 借鉴 UI 设计中的"渐进式披露"原则：只在需要的时候，提供需要的信息。

不要把所有文档都堆在 agent.md 里，而是建立一个文档目录：

agent_docs/
├── building.md       # 构建指南
├── testing.md        # 测试指南
├── architecture.md   # 架构设计
└── database.md       # 数据库 Schema

然后在 agent.md 里做一个索引：

# Agent Docs
详细文档请参考以下文件（按需读取）：
- `agent_docs/building.md`: 构建和运行项目的详细步骤
- `agent_docs/testing.md`: 运行测试套件的方法
- `agent_docs/database.md`: 核心数据库表结构设计

这样，AI 在接到任务时（比如"帮我写个新的 API"），它会自己判断："哦，我需要看看 database.md"，然后主动去读取那个文件。这比一股脑塞给它高效得多！

避坑指南

1. 不要自动生成 ：虽然有很多工具可以自动生成 agent.md，但建议你亲手写。因为这是你和 AI 协作的基石，每一行都值得你深思熟虑。
2. 避免无关信息：不要放"如何设计新数据库 Schema"这种只有在特定任务下才用到的信息。
3. 使用文件引用 ：在文档中尽量引用代码文件的路径（file:line），而不是直接复制粘贴大段代码，防止文档过时。

总结

写好 agent.md 是一门"上下文工程" (Context Engineering) 的艺术。

• 核心：它是 AI 的入职手册。
• 原则：少即是多，不要做 Linter 的工作。
• 技巧：使用"渐进式披露"，把细节拆分到子文档中。

花 10 分钟优化一下你的 agent.md，你会发现你的 AI 队友突然变得"聪明"了！🚀

---

参考资料：Writing a good CLAUDE.md