agent.md

这两年大家开始越来越频繁地和 Codex、Claude Code、Cursor、Copilot 这类智能 IDE / Coding Agent 打交道。

一个很快就会遇到的问题是：

为什么同样一个问题，这次它写得很懂项目，下次又像完全不认识这个仓库？

很多时候，问题不在模型，而在于项目规则没有被稳定、结构化地交给 AI。

这就是 agent.md 这类文件存在的意义。

一句话理解：agent.md 的核心价值，不是“多写一点提示词”，而是把团队对项目的共识，沉淀成 AI 每次开工前都能读到的说明书。

一、先说结论：agent.md 是什么

严格来说，agent.md 不是一个全行业统一的唯一标准文件名。

更准确地说，它代表的是一类文件：

• 给 AI 编程助手看的项目说明文件
• 用来告诉 AI 这个仓库怎么工作
• 让 AI 少猜、多按规则执行

不同工具对它的叫法和位置不完全一样，比如：

• Codex 主要看 AGENTS.md
• Claude Code 主要看 CLAUDE.md
• GitHub Copilot / VS Code 常见是 .github/copilot-instructions.md
• 一些工具会使用 rules 目录，而不是单一文件

所以你可以把“agent.md”理解成一个泛称：

凡是用来给 AI 讲清楚“这个项目应该怎么协作”的说明文件，都可以归到这个范畴里。

二、为什么现在特别需要这种文件

因为 AI 写代码最大的风险，不是“不会写”，而是“写得很像对的，但不符合你的项目”。

比如它可能会：

• 用错包管理器，明明项目用 pnpm，它却执行 npm install
• 写出不符合团队规范的目录结构
• 不知道哪些命令能跑，哪些命令会污染数据
• 在 monorepo 里改错包
• 不理解你们的接口约定、错误处理格式、测试流程

这些问题靠聊天当然也能临时补充，但代价很高：

• 每次都要重新说一遍
• 不同人说法不一致
• 上下文一长，AI 容易忘
• 换一个工具后又要从头再来

而把这些规则写进 agent.md，就相当于给 AI 配了一份“项目入职手册”。

三、agent.md 不是给人看的 README 吗？

不是一回事。

README.md 主要面向人，通常更偏：

• 项目介绍
• 安装方式
• 功能说明
• 对外使用文档

而 agent.md / AGENTS.md / CLAUDE.md 更偏向：

• AI 进入项目后应该遵守什么规则
• 哪些命令能执行
• 哪些路径不能乱动
• 哪些规范是必须遵守的
• 遇到什么情况要先问，不要直接改

你可以把它们理解成：

• README.md：给新同事看的
• agent.md：给 AI 同事看的

四、一个好的 agent.md 应该解决什么问题

如果这份文件写得好，它至少应该帮 AI 回答下面这些问题：

1. 这个项目怎么启动

例如：

• 开发命令是什么
• 构建命令是什么
• 测试命令是什么
• 代码格式化怎么跑

2. 这个项目怎么组织

例如：

• 核心业务代码在哪
• 公共组件在哪
• API 层在哪
• 配置文件在哪

3. 这个项目有哪些硬规则

例如：

• 必须用 pnpm
• 不允许直接修改生成文件
• 修改接口要同步更新文档
• 提交前必须跑某些检查

4. 这个项目有哪些隐性习惯

例如：

• 优先用已有工具函数，不要重复造轮子
• 页面状态统一放在某个 store
• 样式统一用某种方案
• 新增文档要更新导航

5. AI 在什么情况下不要自作主张

例如：

• 涉及数据库迁移时先确认
• 涉及依赖升级时先确认
• 涉及安全配置时先确认
• 涉及大范围重构时先先提方案

这部分其实特别重要，因为它决定了 AI 是“有边界地帮忙”，还是“看起来很积极但容易乱改”。

五、怎么写，AI 才更容易遵守

这是全文最核心的一部分。

很多人写这类文件时，容易犯一个毛病：

写得很长，但不够具体。

比如下面这种话，对人看起来像有道理，但对 AI 其实帮助不大：

• 保持代码整洁
• 尽量不要影响现有逻辑
• 注意风格一致
• 谨慎修改配置

问题在于：太抽象，不可验证。

更好的写法应该是：

• 使用 pnpm，不要使用 npm 或 yarn
• 前端开发命令是 pnpm dev
• 修改 docs/article/** 后，需要同步检查 docs/.vuepress/configs/sidebar/zh.ts
• 不要手动修改 dist/、.cache/、自动生成文件
• 变更 API 返回结构时，必须同步更新 types/ 和调用方

你会发现，好指令通常有三个特点：

1. 具体

不要写：

• 注意测试

要写：

• 修改业务逻辑后，优先运行相关测试；如果没有局部测试，再运行项目测试命令 pnpm test

2. 可执行

不要写：

• 代码风格要统一

要写：

• TypeScript 使用 2 空格缩进；已有文件若使用 4 空格，则保持原风格，不做无关格式化

3. 有边界

不要只写：

• 可以优化代码

要写：

• 允许做与当前需求直接相关的小范围重构；不要顺手修改无关模块或大面积重命名

六、最推荐的内容结构

如果你准备自己写一份，我最推荐这种结构：

# Project Instructions

## Project Overview
- 这个项目是做什么的
- 主要技术栈是什么

## Commands
- 开发命令
- 构建命令
- 测试命令
- 格式化命令

## Directory Guide
- 关键目录分别放什么
- 不应该改哪些目录

## Coding Rules
- 命名规则
- 组件/模块组织规则
- 类型、样式、测试规则

## Working Agreement
- 改动前先看哪些文件
- 哪些改动必须同步更新文档/测试
- 哪些操作必须先确认

## Do Not
- 不要升级依赖
- 不要改生成文件
- 不要随意重构无关代码

这个结构的好处是：

• 人也容易读
• AI 也容易扫描
• 后期容易维护
• 出错时也好排查到底是哪条规则在起作用

七、哪些内容适合写进去，哪些不适合

适合写进去的

• 稳定的项目规则
• 高频重复说明
• 团队共识
• 目录结构说明
• 命令和工作流
• 风险边界

不适合写进去的

• 一次性的临时任务说明
• 过长的背景故事
• 大段不可执行的理念描述
• 很快会过期的细节
• 敏感账号密码

一个简单判断标准是：

如果这件事你在未来 10 次协作里，有 7 次以上都希望 AI 知道，那就值得写进去。

八、最常见的坏写法

1. 写成公司文化宣言

例如：

• 我们是追求极致体验的团队
• 我们重视代码质量和协作精神

这种内容不是完全没价值，但放在 AI 指令文件里优先级很低。

AI 更需要知道的是：

• 怎么跑命令
• 哪些目录重要
• 哪些文件不能改
• 哪些规范必须遵守

2. 写得太长，什么都往里塞

文件过长会带来两个问题：

• AI 读取成本更高
• 真正重要的规则被淹没

通常这类文件更适合“短而硬”，而不是“长而全”。

3. 互相冲突

例如一处写：

• 优先用 npm

另一处又写：

• 本项目统一使用 pnpm

对人来说你可能知道该信后者，但对 AI 来说，这就是冲突指令。

4. 没有优先级

如果你既希望 AI 能小范围重构，又希望它绝不改动无关代码，那最好明确边界：

• 允许与当前需求直接相关的小范围重构
• 不要为“顺手更优雅”去改无关模块

这样比单独写“可以重构”或者“不要乱改”都清楚。

九、一份更像样的示例

下面是一份更实用的示例：

# AGENTS.md

## Project Overview
- This repository is a VuePress documentation site.
- Primary content lives under `docs/`.
- Navigation config is under `docs/.vuepress/configs/`.

## Commands
- Use `yarn dev` for local preview.
- Use `yarn build` for production build.
- Use `yarn md-lint` to lint markdown.

## Content Rules
- New articles under `docs/article/**` should be added to navbar or sidebar when relevant.
- Prefer concise Chinese writing with clear headings.
- If adding images, use local assets when possible.

## Do Not
- Do not edit generated files under `docs/.vuepress/.cache/` or `docs/.vuepress/dist/`.
- Do not reorder unrelated navigation items.
- Do not rewrite existing articles unless the task asks for it.

## Working Style
- Keep changes minimal and focused.
- When updating docs, preserve the existing tone of the repo.
- If a new file needs a visible entry, update the corresponding navigation config.

你会发现这份示例有几个特点：

• 没有废话
• 有命令
• 有目录
• 有边界
• 有执行风格

这就是 AI 最喜欢的指令文件类型。

十、各个主流智能 IDE / Agent 常见位置

这里是最实用的一部分。

需要先提醒一句：不同工具并不一定认 agent.md 这个文件名。

很多时候，你真正要找的是“该工具支持的等效指令文件”。

1. Codex

Codex 官方主推的是 AGENTS.md 体系。

常见位置：

• 全局：~/.codex/AGENTS.md
• 全局临时覆盖：~/.codex/AGENTS.override.md
• 项目根：<repo>/AGENTS.md
• 子目录覆盖：<repo>/some/path/AGENTS.md
• 子目录强覆盖：<repo>/some/path/AGENTS.override.md

补充要点：

• Codex 会从项目根一路找到你当前工作目录
• 越靠近当前目录的规则，优先级越高
• 也支持通过配置自定义 fallback 文件名

如果你的核心目标是“让 Codex 启动就理解项目规则”，那首选就是 AGENTS.md。

2. Claude Code

Claude Code 官方主推的是 CLAUDE.md，不是 AGENTS.md。

常见位置：

• 项目共享：<repo>/CLAUDE.md
• 项目共享另一种放法：<repo>/.claude/CLAUDE.md
• 个人项目本地偏好：<repo>/CLAUDE.local.md
• 用户级：~/.claude/CLAUDE.md
• 规则目录：<repo>/.claude/rules/*.md
• 用户规则目录：~/.claude/rules/*.md

补充要点：

• Claude Code 会沿当前目录向上查找 CLAUDE.md
• 子目录下的 CLAUDE.md 可以按需加载
• 如果仓库里已经有 AGENTS.md，官方建议在 CLAUDE.md 里直接 @AGENTS.md 导入，避免重复维护

所以对于 Claude Code，最稳妥的做法通常是：

• 项目层写 CLAUDE.md
• 如果你已经维护了 AGENTS.md，就在 CLAUDE.md 里引用它

3. GitHub Copilot / VS Code

在 VS Code 的官方 AI 自定义体系里，最常见的是：

• .github/copilot-instructions.md

此外，官方文档也提到在父仓库发现自定义文件时，可以识别：

• copilot-instructions.md
• AGENTS.md
• CLAUDE.md

以及更细粒度的：

• .github/instructions/*.instructions.md
• .github/prompts/*.prompt.md
• .github/agents/*.agent.md

如果你的目标是让 Copilot 在 VS Code 里稳定理解项目规范，推荐优先维护：

• .github/copilot-instructions.md

如果团队同时还在用 Codex 或 Claude Code，可以额外保留：

• AGENTS.md
• CLAUDE.md

4. Cursor

Cursor 的主流做法更偏向 Rules，而不是统一使用一个 agent.md 文件。

常见团队实践通常会放在：

• .cursor/rules/

也就是说，对 Cursor 来说，更常见的是“规则文件体系”，而不是单个 AGENTS.md。

如果你的团队已经有一份成熟的 AGENTS.md，常见做法有两种：

• 保留 AGENTS.md 作为跨工具通用版本
• 再把核心规则拆进 Cursor 的 rules 体系里

这样做的好处是：

• 对 Codex、Claude Code 友好
• 对 Cursor 也友好
• 团队不需要维护完全不同的两套内容

5. 一个更现实的建议

如果你的团队会同时使用多个工具，最省心的方式通常不是只押一个文件名，而是采用下面这套结构：

repo/
├── AGENTS.md
├── CLAUDE.md
├── .github/
│   └── copilot-instructions.md
└── .cursor/
    └── rules/
        └── project-rules.md

然后遵循一个原则：

• AGENTS.md 放跨工具共通规则
• CLAUDE.md 放 Claude 特有补充，必要时直接引用 AGENTS.md
• copilot-instructions.md 放 VS Code / Copilot 最相关的内容
• Cursor rules 放 Cursor 更适配的拆分规则

十一、我最推荐的写法策略

如果你问我“怎么写才最实用”，我会建议这样做：

第一步：先写一份跨工具基础版

内容只放最稳定的东西：

• 项目是干嘛的
• 命令怎么跑
• 哪些目录关键
• 哪些目录不要改
• 哪些规则必须遵守

这份可以作为：

• AGENTS.md

第二步：再做工具适配层

例如：

• CLAUDE.md 可以 @AGENTS.md
• Cursor 把基础规则拆成 .cursor/rules/*.md
• Copilot 再补一份 .github/copilot-instructions.md

第三步：把高频踩坑补进去

最好不是一上来就写很多，而是在你真实使用中，遇到 AI 重复犯错时再补：

• 它总用错命令
• 它总改错目录
• 它总忽略测试
• 它总给出不符合团队习惯的写法

这时候再加规则，效果最好。

十二、怎么判断这份文件写得好不好

你可以用下面 5 个问题自测：

1. 新开一个会话，AI 能不能立刻知道怎么跑项目？

2. 它能不能知道哪些文件能改，哪些最好别动？

3. 它能不能少问很多重复问题？

4. 它给出的改动，是否更贴近你的项目风格？

5. 这份文件是不是短、硬、具体，而不是大而空？

如果这 5 个问题大多都能答“是”，那基本就写对了。

十三、给你的一个实用模板

如果你今天就想写一份，可以直接从这个模板开始：

# Project Instructions

## Overview
- This project is a documentation site built with VuePress.
- Main content is under `docs/`.

## Commands
- Use `yarn dev` for local development.
- Use `yarn build` for production build.
- Use `yarn md-lint` to lint markdown files.

## Key Paths
- `docs/.vuepress/configs/navbar/` contains navbar config.
- `docs/.vuepress/configs/sidebar/` contains sidebar config.
- `docs/article/` contains long-form articles.

## Working Rules
- Keep changes focused on the requested task.
- Preserve existing writing style unless asked to rewrite.
- When adding a new article, update navigation if needed.

## Do Not
- Do not edit generated files under `.vuepress/.cache/` or `.vuepress/dist/`.
- Do not reorder unrelated navigation items.
- Do not add new dependencies unless necessary.

## Ask First
- Ask before large-scale refactors.
- Ask before changing build tooling.
- Ask before deleting existing content.

总结

关于 agent.md，最重要的不是名字，而是思路。

真正的核心只有一句话：

把你希望 AI 每次都知道、而你又不想每次都重复解释的项目规则，写成一份短、清晰、具体、可执行的说明文件。

如果再压缩成 4 个关键词，就是：

• 具体：不要写空话
• 稳定：写长期有效的规则
• 分层：通用规则和工具特定规则分开
• 可验证：让 AI 知道什么叫“做对了”

这样写出来的 agent.md / AGENTS.md / CLAUDE.md，才是真的有用。