AI 比价
AI 比价
AI 博客

AGENTS.md 是什么？一文搞懂 AI 编程代理配置文件

最全 AGENTS.md 教程｜手把手教你写 AGENTS.md，让 Claude Code、Copilot、Cursor、Devin 等工具真正理解你的项目。含模板、示例和实战建议。

发布时间
阅读时长
8 分钟
来源
DevTk.AI 博客
AGENTS.mdAI 编程Claude Code

2026 年，AI 编程代理已经成为开发者的标配。Claude Code、GitHub Copilot、Cursor、Devin、Windsurf、Gemini CLI——工具越来越多，但一个问题始终没变： 每个 AI 进入你的项目时，对你的代码规范一无所知。

它不知道你用 pnpm 还是 npm，不知道你的测试用 Vitest 还是 Jest，不知道你的组件该用 PascalCase 还是 kebab-case。结果就是生成的代码风格跟项目格格不入，review 的时间比自己写还长。

AGENTS.md 就是为解决这个问题而生的。

什么是 AGENTS.md？

AGENTS.md 是一个 面向 AI 编程代理的开放标准 。简单来说，它就是一个放在项目根目录的 Markdown 文件，告诉所有 AI 工具：“在这个项目里，我们是这样写代码的。”

你可以把它理解为 “给 AI 看的 README” 。

关键信息

  • 格式 ：标准 Markdown，无特殊语法
  • 位置 ：项目根目录 ( /AGENTS.md )
  • 采用规模 ：60,000+ 开源项目
  • 标准组织 ：Agentic AI Foundation (AAIF)，隶属 Linux Foundation，与 MCP（Anthropic）和 Goose（Block）并列
  • 兼容工具 ：Claude Code、GitHub Copilot、Cursor、Windsurf、Devin、Gemini CLI、Aider、VS Code AI 等

为什么你需要 AGENTS.md？

没有 AGENTS.md 的时候，AI 代理只能猜：

AI 猜测你的实际情况后果
用 npm install你用 pnpmlock 文件冲突
写 Jest 测试你用 Vitest导入报错，需要全部改
用 export default你要求 named export不符合项目规范
用 class 组件你只用函数组件Code review 打回
直接拼 SQL你用 Prisma ORM安全隐患

这些”小问题”日积月累，就变成了： 用 AI 写代码比自己写还慢 。

一个写得好的 AGENTS.md 可以让 AI 代理 第一次就写对 。

怎么写 AGENTS.md？

AGENTS.md 没有严格的必填字段，但最有效的文件通常包含以下几个部分：

1. 项目概述

告诉 AI 这个项目是做什么的。

## Project Overview




**我的应用**
 — 基于 Next.js 15 + TypeScript + Prisma + PostgreSQL 的实时协作平台。

2. 开发环境（最重要的部分！）

构建命令、开发命令、测试命令是 AI 代理最频繁使用的信息。 这个部分写好，效果立竿见影。

## Development Environment




-
 Package manager: 
`pnpm`


-
 Start dev server: 
`pnpm dev`


-
 Build: 
`pnpm build`


-
 Test: 
`pnpm test`


-
 Lint: 
`pnpm lint`

3. 代码结构

帮 AI 快速了解项目布局。

## Codebase Structure




src/


 app/ — Next.js App Router 页面


 components/ — React 组件（PascalCase 命名）


 lib/ — 公共工具和 helpers


 server/ — 服务端逻辑和 API


 db/ — Prisma schema 和 migrations

4. 代码风格与规范

定义你的团队最在乎的规则。

## Code Style & Conventions




-
 默认使用 Server Components，只在必要时添加 "use client"


-
 优先使用 named export


-
 TypeScript strict 模式——禁止 
`any`


-
 使用 Tailwind CSS，不写自定义 CSS


-
 组件超过 200 行就拆分




### Naming Conventions




-
 组件：PascalCase（例 UserProfile.tsx）


-
 Hooks：camelCase + use 前缀（例 useAuth.ts）


-
 工具函数：camelCase（例 formatDate.ts）


-
 常量：UPPER_SNAKE_CASE

5. 测试规范

## Testing




-
 Run tests: 
`pnpm test`


-
 使用 Vitest 写单元测试


-
 使用 React Testing Library 做组件测试


-
 测试用户行为，不测实现细节


-
 提 PR 前确保所有测试通过

6. 提交与 PR 规范

## PR & Commit Guidelines




-
 使用 Conventional Commits：feat:、fix:、docs:、refactor:


-
 Commit message 不超过 72 字符


-
 PR 必须包含描述和测试计划


-
 引用 Issue 编号（例 "fix: 修复登录 bug #123"）

7. 安全注意事项

## Security Considerations




-
 绝不提交密钥、API Key 或 .env 文件


-
 所有用户输入必须做清理和验证


-
 数据库查询使用参数化查询


-
 认证校验放在 middleware 层，不放在路由处理函数中

最佳实践

写可执行的指令

不要写”我们重视代码质量”这种空话。要写”函数不超过 30 行，重复逻辑提取为 helper”。

保持更新

AGENTS.md 是活文档。以下情况要更新：

  • 新增了依赖或框架
  • 改变了测试策略
  • 采用了新的代码模式
  • 发现 AI 反复犯同样的错

Monorepo 多层级放置

my-monorepo/


 AGENTS.md ← 全局规范


 packages/


 frontend/


 AGENTS.md ← 前端特定规则


 backend/


 AGENTS.md ← 后端特定规则

AI 代理会读取目录树中 最近的 AGENTS.md。子目录的规则优先于根目录，实现灵活覆盖。

AGENTS.md 和其他配置文件的关系

文件适用工具定位
AGENTS.md所有 AI 代理通用标准
CLAUDE.mdClaude CodeAnthropic 专用
.cursorrulesCursorCursor 专用
.windsurfrulesWindsurfCodeium 专用
copilot-instructions.mdGitHub CopilotGitHub 专用

如果你只想维护一个文件，选 AGENTS.md ——它在所有工具上都能用。如果你的团队同时用多个工具，AGENTS.md 负责通用规范，其他文件补充工具特有功能。

先写一个最小可用版本

你不需要生成器，也完全可以写出一份高质量的 AGENTS.md。第一版通常一屏就够：

  • 项目简介和整体架构
  • 安装、构建、测试、部署命令
  • 编码规范和 review 要求
  • 风险点、限制条件，以及 AI 需要谨慎处理的文件

如果你的团队还在使用 Cursor 的专用规则，可以继续阅读我们的 Cursor Rules 完整指南 。如果你的 Agent 还需要访问外部工具，再配合 MCP 指南 和 MCP 服务器教程 一起看，会更完整。

总结

AGENTS.md 是少有的”简单又立刻有用”的标准。一个 20 行的文件就能省下几小时的 AI 代码 review 时间。写得好的 AGENTS.md 能让 AI 编程代理从”有用但乱来”变成”真正靠谱的队友”。

从最基本的开始——项目简介、构建命令、几条编码规范。之后随时可以按需补充。

下一步： 继续看 Cursor Rules 指南 → 或 动手搭建第一个 MCP 服务器 →