DevTk.AI
English
AGENTS.mdAI 编程Claude CodeCursor开发工具编码规范

AGENTS.md 是什么？一文搞懂 AI 编程代理配置文件（附在线生成器）

最全 AGENTS.md 教程｜60000+ 项目在用的 AI 编程规范标准。手把手教你写 AGENTS.md，让 Claude Code、Copilot、Cursor、Devin 完美理解你的项目。含 6 套模板一键生成。

DevTk.AI 2026-02-22

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 生成器 可视化构建：

  • 6 套快速预设（React、Next.js、Python、Node、Go、Rust）
  • 表单式编辑器，覆盖所有推荐章节
  • 实时 Markdown 预览
  • 一键复制或下载

30 秒生成一个生产级的 AGENTS.md 文件。

总结

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

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

开始使用：立即生成你的 AGENTS.md →