【教程】CLAUDE.md 与 AGENTS.md 完全指南：让 AI 编程助手更懂你的项目
【教程】CLAUDE.md 与 AGENTS.md 完全指南：让 AI 编程助手更懂你的项目
本文详细介绍 CLAUDE.md 和 AGENTS.md 两个配置文件的作用、格式和最佳实践，包括文件位置优先级、内容规范、实践案例。适合已使用过 Claude Code、Cursor 等 AI 编程助手的进阶开发者阅读。
【教程】CLAUDE.md 与 AGENTS.md 完全指南：让 AI 编程助手更懂你的项目
- 【教程】CLAUDE.md 与 AGENTS.md 完全指南：让 AI 编程助手更懂你的项目
1. 为什么需要这两个文件
在 AI 辅助编程的时代，我们已经习惯了让 AI 帮我们写代码、调试、重构。但你有没有遇到过这样的情况：
- AI 生成的代码风格和项目规范不一致
- 每次都要重复告诉 AI 项目的构建命令
- AI 不知道项目的特殊约定，总是犯同样的错误
- 团队成员使用 AI 时，得到的结果参差不齐
说白了，这些问题的根源在于：AI 不了解你的项目上下文。
每个项目都有一个 README.md 供人类阅读，但 AI 编程助手需要的信息和人类不同。人类可以通过经验推断很多细节，而 AI 需要明确、具体的指令。
这就是 CLAUDE.md 和 AGENTS.md 存在的意义——它们是写给 AI 的项目说明书。
打个比方：README.md 像是产品说明书，而 CLAUDE.md/AGENTS.md 像是给新员工的入职培训手册——事无巨细，确保 AI 能按照你的期望工作。
1.1 两个文件的定位
| 文件 | 定位 | 适用工具 | 标准化程度 |
|---|---|---|---|
CLAUDE.md | Claude Code 专属配置文件 | Claude Code | Anthropic 官方标准 |
AGENTS.md | 通用 AI 编程代理配置文件 | Cursor、GitHub Copilot、Codex、Gemini CLI 等 | 开放标准（60,000+ 项目采用） |
简单来说：
- CLAUDE.md 是 Claude Code 的"专属记忆"，每次启动时自动加载
- AGENTS.md 是一个跨平台的开放标准，被主流 AI 编程工具广泛支持
1.2 传统 README.md vs AI 配置文件
传统的 README.md 是写给人看的，它关注的是：
- 项目是什么
- 如何安装和使用
- 功能特性介绍
而 CLAUDE.md 和 AGENTS.md 是写给 AI 看的，它们关注的是：
- 如何构建和测试这个项目
- 代码风格和命名规范是什么
- 有哪些特殊约定和注意事项
- 遇到特定问题应该怎么处理
2. CLAUDE.md 深度解析
2.1 什么是 CLAUDE.md
CLAUDE.md 是 Anthropic 为 Claude Code 设计的配置文件。当你启动 Claude Code 时，它会自动读取这个文件的内容并加入到对话上下文中。
这意味着你在 CLAUDE.md 中写的任何内容，Claude 在整个会话过程中都会"记住"。
2.2 文件位置与优先级
Claude Code 支持在多个位置放置 CLAUDE.md，并按以下优先级读取：
优先级从高到低： 1. 当前工作目录的 CLAUDE.local.md（本地配置，不提交到 git） 2. 当前工作目录的 CLAUDE.md（项目配置，提交到 git） 3. 父目录的 CLAUDE.md（适用于 Monorepo） 4. ~/.claude/CLAUDE.md（全局配置，适用于所有项目） 这什么玩意？不要着急，慢慢来。
打个比方，假设你有一个 Monorepo 项目：
my-monorepo/ ├── CLAUDE.md # 根目录配置（通用规则） ├── packages/ │ ├── frontend/ │ │ └── CLAUDE.md # 前端子项目配置 │ └── backend/ │ └── CLAUDE.md # 后端子项目配置 └── CLAUDE.local.md # 本地私有配置（.gitignore） 当你在 packages/frontend/ 目录下工作时，Claude 会同时读取：
packages/frontend/CLAUDE.mdmy-monorepo/CLAUDE.md
这种层级结构让你可以在根目录定义通用规则，在子目录定义特定规则。说白了，就是"继承"的思想。
2.3 CLAUDE.md 应该包含什么
根据 Anthropic 官方最佳实践，CLAUDE.md 应该包含以下内容：
2.3.1 常用命令
# 常用命令 ## 构建 - `npm run build` - 构建生产版本 - `npm run dev` - 启动开发服务器 ## 测试 - `npm test` - 运行所有测试 - `npm test -- --watch` - 监听模式运行测试 - `npm run test:coverage` - 生成覆盖率报告 ## 代码检查 - `npm run lint` - 运行 ESLint - `npm run typecheck` - 运行 TypeScript 类型检查 2.3.2 代码风格指南
# 代码风格 ## JavaScript/TypeScript - 使用 ES modules（import/export），不使用 CommonJS（require） - 优先使用解构导入：`import { foo } from 'bar'` - 使用 const 声明不变的变量，let 声明需要重新赋值的变量 - 函数优先使用箭头函数 - 字符串使用单引号 ## 命名规范 - 组件使用 PascalCase：`UserProfile.tsx` - 工具函数使用 camelCase：`formatDate.ts` - 常量使用 UPPER_SNAKE_CASE：`MAX_RETRY_COUNT` - CSS 类名使用 kebab-case：`user-profile` 2.3.3 项目架构说明
# 项目架构 ## 目录结构 - `src/components/` - React 组件 - `src/hooks/` - 自定义 Hooks - `src/utils/` - 工具函数 - `src/api/` - API 请求封装 - `src/types/` - TypeScript 类型定义 ## 关键文件 - `src/config/index.ts` - 全局配置 - `src/store/index.ts` - 状态管理入口 - `src/router/index.tsx` - 路由配置 2.3.4 开发规范和注意事项
# 开发规范 ## Git 提交 - 提交信息格式：`<type>(<scope>): <subject>` - type 可选值：feat, fix, docs, style, refactor, test, chore - 示例：`feat(user): add login functionality` ## 注意事项 - 不要直接修改 `node_modules` 中的代码 - 环境变量必须以 `VITE_` 开头才能在前端使用 - API 请求统一使用 `src/api/request.ts` 中的封装方法 2.4 CLAUDE.md 完整示例
下面是一个假设的全栈项目 TaskFlow（任务管理系统）的完整 CLAUDE.md 配置：
# TaskFlow 项目配置 ## 项目概述 TaskFlow 是一个基于 React + Node.js 的任务管理系统，支持团队协作、任务分配、进度追踪等功能。 ## 技术栈 - 前端：React 18 + TypeScript + Vite + TailwindCSS - 后端：Node.js + Express + TypeScript - 数据库：PostgreSQL + Prisma ORM - 测试：Jest + React Testing Library ## 常用命令 ### 开发 - `pnpm dev` - 同时启动前后端开发服务器 - `pnpm dev:client` - 仅启动前端（端口 5173） - `pnpm dev:server` - 仅启动后端（端口 3000） ### 构建 - `pnpm build` - 构建前后端 - `pnpm build:client` - 仅构建前端 - `pnpm build:server` - 仅构建后端 ### 测试 - `pnpm test` - 运行所有测试 - `pnpm test:client` - 运行前端测试 - `pnpm test:server` - 运行后端测试 - `pnpm test:e2e` - 运行端到端测试 ### 数据库 - `pnpm db:migrate` - 运行数据库迁移 - `pnpm db:seed` - 填充测试数据 - `pnpm db:studio` - 打开 Prisma Studio ### 代码质量 - `pnpm lint` - 运行 ESLint - `pnpm typecheck` - 运行类型检查 - `pnpm format` - 运行 Prettier 格式化 ## 代码风格 ### TypeScript - 严格模式开启，不允许 any 类型 - 优先使用 interface 定义对象类型 - 使用 type 定义联合类型和工具类型 - 函数返回值必须显式声明类型 ### React - 使用函数组件 + Hooks，不使用类组件 - 组件 props 使用 interface 定义 - 状态管理使用 Zustand - 表单处理使用 React Hook Form + Zod ### API 设计 - RESTful 风格 - 响应格式：`{ code: number, data: T, message: string }` - 错误码：200 成功，400 参数错误，401 未授权，500 服务器错误 ## 目录结构 taskflow/ ├── client/ # 前端代码 │ ├── src/ │ │ ├── components/ # 通用组件 │ │ ├── features/ # 功能模块（按业务划分） │ │ ├── hooks/ # 自定义 Hooks │ │ ├── lib/ # 第三方库封装 │ │ ├── stores/ # Zustand stores │ │ └── types/ # 类型定义 │ └── tests/ # 前端测试 ├── server/ # 后端代码 │ ├── src/ │ │ ├── controllers/ # 控制器 │ │ ├── services/ # 业务逻辑 │ │ ├── middlewares/ # 中间件 │ │ ├── routes/ # 路由定义 │ │ └── utils/ # 工具函数 │ └── tests/ # 后端测试 ├── prisma/ # Prisma 配置和迁移 └── e2e/ # 端到端测试 ## 开发规范 ### Git 工作流 - 主分支：main（生产）、develop（开发） - 功能分支：feature/xxx - 修复分支：fix/xxx - 提交前必须通过 lint 和 typecheck ### 提交信息格式 <type>(<scope>): <subject> <body> <footer> type 可选值： - feat: 新功能 - fix: 修复 bug - docs: 文档更新 - style: 代码格式（不影响功能） - refactor: 重构 - test: 测试相关 - chore: 构建/工具相关 ### Code Review 要求 - 每个 PR 至少需要一个 approve - PR 标题格式与提交信息一致 - 必须关联对应的 Issue ## 注意事项 ### 环境变量 - 前端环境变量以 `VITE_` 开头 - 后端环境变量在 `.env` 文件中配置 - 敏感信息不要提交到代码库 ### 数据库操作 - 所有数据库操作通过 Prisma 进行 - 复杂查询使用 Prisma 的 raw query - 迁移文件不要手动修改 ### 测试要求 - 新功能必须有对应的单元测试 - 核心业务逻辑测试覆盖率 > 80% - API 接口必须有集成测试 ## 常见问题 ### Q: 启动报错 "Cannot find module" A: 运行 `pnpm install` 重新安装依赖 ### Q: 数据库连接失败 A: 检查 `.env` 中的 `DATABASE_URL` 配置，确保 PostgreSQL 服务已启动 ### Q: TypeScript 类型错误 A: 运行 `pnpm typecheck` 查看详细错误，确保类型定义正确 2.5 创建 CLAUDE.md 的方法
有两种方式创建 CLAUDE.md：
方法一：使用 /init 命令自动生成
# 在项目目录中启动 Claude Code claude # 运行初始化命令> /init Claude 会分析你的项目结构，自动生成一个基础的 CLAUDE.md 文件。不过说实话，自动生成的内容比较基础，还需要自己补充完善。
方法二：手动创建
touch CLAUDE.md 然后根据上面的模板填充内容。
2.6 CLAUDE.md 优化技巧
- 迭代优化：不要一次性写太多内容，像调优 Prompt 一样逐步实验和调整。
- 使用强调词：对于重要规则，可以使用 “IMPORTANT”、“YOU MUST”、“NEVER” 等词汇提高遵循度。
## 重要规则 **IMPORTANT**: 所有 API 请求必须经过 `src/api/request.ts` 封装 **YOU MUST**: 提交代码前运行 `pnpm lint` 和 `pnpm typecheck` **NEVER**: 不要在前端代码中硬编码 API 地址 - 使用 # 快捷指令：在 Claude Code 对话中按
#键，可以快速将当前对话中的重要信息添加到CLAUDE.md。 - 区分本地和共享配置：
- 团队共享的规则放在
CLAUDE.md（提交到 git） - 个人偏好放在
CLAUDE.local.md（加入 .gitignore）
- 团队共享的规则放在
3. AGENTS.md 深度解析
3.1 什么是 AGENTS.md
AGENTS.md 是一个开放的标准格式，专门为 AI 编程代理设计。与 Claude Code 专属的 CLAUDE.md 不同，AGENTS.md 被广泛的 AI 编程工具支持：
- OpenAI Codex
- Google Gemini CLI / Jules
- Cursor
- GitHub Copilot
- Aider
- VS Code、Zed、Warp 等 IDE
目前已有超过 60,000 个开源项目采用了这个标准。这个数字确实让我有点惊讶，说明 AI 编程助手的配置文件标准化已经成为趋势。
3.2 AGENTS.md vs CLAUDE.md
| 特性 | CLAUDE.md | AGENTS.md |
|---|---|---|
| 适用工具 | Claude Code 专属 | 跨平台通用 |
| 标准化组织 | Anthropic | Agentic AI Foundation (Linux Foundation) |
| 文件位置 | 支持多级目录和全局配置 | 主要在项目根目录和子目录 |
| 内容格式 | 自由 Markdown | 自由 Markdown |
| 优先级机制 | 支持 local 文件覆盖 | 就近原则（最近的文件优先） |
选择建议：
- 如果团队主要使用 Claude Code，可以只用
CLAUDE.md - 如果团队使用多种 AI 工具，建议同时维护两个文件，或只用
AGENTS.md - 两个文件可以共存，内容可以相同或针对不同工具做优化
3.3 AGENTS.md 的优先级机制
AGENTS.md 采用"就近原则"：
优先级从高到低： 1. 用户在聊天中的直接提示词（最高优先级） 2. 距离当前编辑文件最近的 AGENTS.md 3. 根目录的 AGENTS.md 在 Monorepo 中的应用：
my-monorepo/ ├── AGENTS.md # 根目录（通用规则） ├── packages/ │ ├── web/ │ │ └── AGENTS.md # Web 子项目（前端规则） │ ├── api/ │ │ └── AGENTS.md # API 子项目（后端规则） │ └── shared/ │ └── AGENTS.md # 共享库（库开发规则） 当你在 packages/web/src/ 下编辑文件时，AI 会优先读取 packages/web/AGENTS.md，然后是根目录的 AGENTS.md。
3.4 AGENTS.md 应该包含什么
根据官方规范，AGENTS.md 应该包含以下内容：
3.4.1 项目概述
# AGENTS.md ## Project Overview TaskFlow is a task management system built with React and Node.js. This is a monorepo managed by pnpm workspaces. 3.4.2 构建和测试命令
## Setup Commands - Install dependencies: `pnpm install` - Start dev server: `pnpm dev` - Run tests: `pnpm test` - Build for production: `pnpm build` 3.4.3 代码风格和规范
## Code Style - Use TypeScript strict mode - Use ESLint + Prettier for formatting - Follow Airbnb style guide - Use functional components with hooks (no class components) 3.4.4 测试说明
## Testing Instructions - Find CI plans in `.github/workflows/` - Run `pnpm test` before committing - Ensure all tests pass before creating PR - Write unit tests for new features 3.4.5 PR 和提交规范
## PR Instructions - Title format: `[<scope>] <description>` - Link related issues in PR description - Request review from at least one team member - Squash commits before merging 3.5 AGENTS.md 完整示例
继续使用 TaskFlow 项目，这是对应的 AGENTS.md 配置：
# AGENTS.md ## Project Overview TaskFlow is a full-stack task management application. - Frontend: React 18 + TypeScript + Vite - Backend: Node.js + Express + TypeScript - Database: PostgreSQL + Prisma - Package Manager: pnpm (monorepo) ## Setup Commands - Install deps: `pnpm install` - Start dev: `pnpm dev` - Run tests: `pnpm test` - Build: `pnpm build` - Lint: `pnpm lint` - Type check: `pnpm typecheck` ## Database Commands - Run migrations: `pnpm db:migrate` - Seed data: `pnpm db:seed` - Open Prisma Studio: `pnpm db:studio` ## Code Style Guidelines ### TypeScript - Strict mode enabled, no `any` types - Prefer `interface` for object types - Explicit return types for functions - Use `type` for unions and utility types ### React - Functional components only - Use Zustand for state management - Use React Hook Form + Zod for forms - Component files use PascalCase ### API Design - RESTful conventions - Response format: `{ code, data, message }` - Error codes: 200 OK, 400 Bad Request, 401 Unauthorized, 500 Server Error ## Project Structure taskflow/ ├── client/ # Frontend (React) │ ├── src/ │ │ ├── components/ # Shared components │ │ ├── features/ # Feature modules │ │ ├── hooks/ # Custom hooks │ │ ├── stores/ # Zustand stores │ │ └── types/ # Type definitions ├── server/ # Backend (Express) │ ├── src/ │ │ ├── controllers/ # Route handlers │ │ ├── services/ # Business logic │ │ ├── middlewares/ # Express middlewares │ │ └── routes/ # Route definitions ├── prisma/ # Database schema & migrations └── e2e/ # End-to-end tests ## Testing Instructions - Check CI config in `.github/workflows/ci.yml` - Run `pnpm test` for unit tests - Run `pnpm test:e2e` for E2E tests - Coverage target: 80% for core business logic - All tests must pass before PR merge ## PR Instructions - Title format: `<type>(<scope>): <description>` - Types: feat, fix, docs, style, refactor, test, chore - Link related issues using `Closes #<issue_number>` - Request review from at least one maintainer - Ensure CI passes before requesting review ## Security Notes - Never commit `.env` files - Use environment variables for secrets - Sanitize all user inputs - Use parameterized queries (Prisma handles this) ## Common Issues ### "Module not found" error Run `pnpm install` to reinstall dependencies. ### Database connection failed Check `DATABASE_URL` in `.env` and ensure PostgreSQL is running. ### Type errors after pulling Run `pnpm typecheck` and fix any type mismatches. 3.6 配置特定工具识别 AGENTS.md
某些工具需要额外配置才能识别 AGENTS.md：
Aider：
# .aider.conf.ymlread: AGENTS.md Gemini CLI：
// .gemini/settings.json{"contextFileName":"AGENTS.md"}Cursor：Cursor 原生支持 AGENTS.md，无需额外配置。
3.7 从 AGENT.md 迁移到 AGENTS.md
如果你的项目之前使用的是 AGENT.md（单数形式），可以通过以下命令迁移：
# 重命名文件并创建符号链接保持兼容mv AGENT.md AGENTS.md &&ln -s AGENTS.md AGENT.md 这样既更新到了新标准，又保持了对旧工具的兼容。
4. 实践案例：从零配置新项目
假设我们要创建一个新项目 TaskFlow，这是一个任务管理系统。下面演示如何从零开始配置 CLAUDE.md 和 AGENTS.md。
4.1 项目背景
项目名称：TaskFlow
项目类型：全栈 Web 应用
技术栈：
- 前端：React 18 + TypeScript + Vite + TailwindCSS
- 后端：Node.js + Express + TypeScript
- 数据库：PostgreSQL + Prisma
- 包管理：pnpm (Monorepo)
团队情况：
- 3 名前端开发
- 2 名后端开发
- 使用 GitHub 进行代码管理
- CI/CD 使用 GitHub Actions
4.2 创建项目结构
首先，创建基础的项目结构：
# 创建项目目录mkdir taskflow &&cd taskflow # 初始化 pnpmpnpm init # 创建 Monorepo 结构mkdir -p client/src server/src prisma e2e # 创建配置文件touch CLAUDE.md AGENTS.md .gitignore 4.3 配置 CLAUDE.md
针对 Claude Code 用户，创建 CLAUDE.md：
# TaskFlow 项目配置 这是一个基于 React + Node.js 的任务管理系统，使用 pnpm monorepo 管理。 ## 快速开始 # 安装依赖 pnpm install # 启动开发环境 pnpm dev # 运行测试 pnpm test ## 技术栈 | 层级 | 技术 | |------|------| | 前端 | React 18, TypeScript, Vite, TailwindCSS, Zustand | | 后端 | Node.js, Express, TypeScript | | 数据库 | PostgreSQL, Prisma ORM | | 测试 | Jest, React Testing Library, Supertest | ## 代码规范 ### TypeScript - 严格模式，禁止 any - 使用 interface 定义对象类型 - 函数必须声明返回类型 ### React - 只使用函数组件 + Hooks - 状态管理使用 Zustand - 表单使用 React Hook Form + Zod ### 命名规范 - 组件：PascalCase（UserProfile.tsx） - 函数/变量：camelCase（getUserById） - 常量：UPPER_SNAKE_CASE（MAX_RETRY） - CSS 类：kebab-case（user-profile） ## 目录结构 taskflow/ ├── client/ # 前端 │ └── src/ │ ├── components/ # 通用组件 │ ├── features/ # 功能模块 │ ├── hooks/ # 自定义 Hooks │ ├── stores/ # Zustand stores │ └── types/ # 类型定义 ├── server/ # 后端 │ └── src/ │ ├── controllers/ # 控制器 │ ├── services/ # 业务逻辑 │ ├── middlewares/ # 中间件 │ └── routes/ # 路由 ├── prisma/ # 数据库 └── e2e/ # E2E 测试 ## Git 规范 ### 分支策略 - main：生产环境 - develop：开发环境 - feature/*：功能开发 - fix/*：Bug 修复 ### 提交格式 <type>(<scope>): <subject> type: feat | fix | docs | style | refactor | test | chore 示例：`feat(task): add task creation API` ## 重要提醒 **IMPORTANT**: - 所有 API 请求必须通过 `client/src/lib/api.ts` 封装 - 数据库操作只能通过 Prisma，不要写原生 SQL - 前端环境变量必须以 `VITE_` 开头 **NEVER**: - 不要在代码中硬编码密钥或密码 - 不要直接修改 node_modules - 不要跳过 TypeScript 类型检查 ## 常见问题 ### 依赖安装失败 rm -rf node_modules pnpm-lock.yaml pnpm install ### 数据库连接失败 检查 `.env` 中的 `DATABASE_URL`，确保 PostgreSQL 已启动。 ### 类型错误 运行 `pnpm typecheck` 查看详细错误信息。 4.4 配置 AGENTS.md
为了支持其他 AI 工具（Cursor、Copilot 等），创建 AGENTS.md：
# AGENTS.md ## Project: TaskFlow A full-stack task management application using React + Node.js monorepo. ## Quick Start - Install: `pnpm install` - Dev: `pnpm dev` - Test: `pnpm test` - Build: `pnpm build` - Lint: `pnpm lint` ## Tech Stack - Frontend: React 18, TypeScript, Vite, TailwindCSS, Zustand - Backend: Node.js, Express, TypeScript - Database: PostgreSQL, Prisma - Testing: Jest, React Testing Library ## Code Style ### TypeScript - Strict mode, no `any` - Use `interface` for objects - Explicit return types ### React - Functional components only - Zustand for state - React Hook Form + Zod for forms ### Naming - Components: PascalCase - Functions: camelCase - Constants: UPPER_SNAKE_CASE ## Structure client/src/ ├── components/ # Shared UI ├── features/ # Feature modules ├── hooks/ # Custom hooks ├── stores/ # State management └── types/ # TypeScript types server/src/ ├── controllers/ # Request handlers ├── services/ # Business logic ├── middlewares/ # Express middleware └── routes/ # API routes ## Testing - Run `pnpm test` before commit - Coverage target: 80% - E2E tests in `e2e/` directory ## PR Guidelines - Format: `<type>(<scope>): <description>` - Types: feat, fix, docs, style, refactor, test, chore - Link issues: `Closes #123` - Require 1 approval ## Security - No hardcoded secrets - Use env variables - Sanitize user input 4.5 配置子目录的 AGENTS.md
对于 Monorepo，可以在子目录创建特定的配置：
client/AGENTS.md（前端特定配置）：
# Frontend AGENTS.md ## Overview React frontend for TaskFlow application. ## Commands - Dev: `pnpm dev:client` - Test: `pnpm test:client` - Build: `pnpm build:client` ## Component Guidelines - Use TailwindCSS for styling - Prefer composition over inheritance - Extract reusable logic to hooks - Keep components under 200 lines ## State Management - Local state: useState/useReducer - Global state: Zustand stores in `stores/` - Server state: React Query ## File Naming - Components: `ComponentName.tsx` - Hooks: `useHookName.ts` - Utils: `utilName.ts` - Types: `types.ts` or `ComponentName.types.ts` server/AGENTS.md（后端特定配置）：
# Backend AGENTS.md ## Overview Express.js backend API for TaskFlow. ## Commands - Dev: `pnpm dev:server` - Test: `pnpm test:server` - Build: `pnpm build:server` ## API Design - RESTful conventions - Base path: `/api/v1` - Response: `{ code, data, message }` ## Error Handling - Use custom error classes - Centralized error middleware - Log errors with context ## Database - All queries through Prisma - Use transactions for multi-step operations - Index frequently queried columns ## Authentication - JWT tokens in Authorization header - Refresh token rotation - Rate limiting on auth endpoints 4.6 配置本地私有设置
创建 CLAUDE.local.md 用于个人配置（不提交到 git）：
# 本地配置 ## 我的开发环境 - Node.js: v20.10.0 - pnpm: 8.15.0 - IDE: VS Code ## 个人偏好 - 使用 Vim 键位 - 终端使用 iTerm2 + zsh - 调试时优先使用 console.log ## 本地数据库 - Host: localhost - Port: 5432 - Database: taskflow_dev 别忘了将其加入 .gitignore：
# .gitignore CLAUDE.local.md 4.7 验证配置效果
配置完成后，可以通过以下方式验证：
Claude Code：
claude > 请帮我创建一个新的 Task 组件 Claude 应该会：
- 使用 TypeScript 和函数组件
- 遵循 PascalCase 命名
- 使用 TailwindCSS 样式
- 放置在正确的目录
Cursor / Copilot：打开项目，让 AI 生成代码时观察是否遵循了 AGENTS.md 中的规范。
5. 最佳实践与进阶技巧
5.1 内容组织原则
- 简洁明了：AI 的上下文窗口有限，不要写太多无关内容。
- 结构清晰：使用标题、列表、表格组织内容，便于 AI 解析。
- 可操作性强：提供具体的命令和示例，而不是抽象的描述。
# 不好的写法 我们的代码风格比较严格，请注意保持一致性。 # 好的写法 ## 代码风格 - 使用 2 空格缩进 - 字符串使用单引号 - 行尾不加分号 - 运行 `pnpm lint` 检查 5.2 优先级和强调
对于重要规则，使用强调词提高遵循度：
## 关键规则 **CRITICAL**: 所有数据库迁移必须经过 review **IMPORTANT**: API 响应必须包含错误码 **MUST**: 提交前必须通过所有测试 **NEVER**: 永远不要在日志中打印敏感信息 **ALWAYS**: 总是使用参数化查询防止 SQL 注入 5.3 团队协作策略
- 分层配置：
- 根目录：团队通用规则
- 子目录：项目/模块特定规则
- local 文件：个人偏好
- 版本控制：
CLAUDE.md和AGENTS.md提交到 gitCLAUDE.local.md加入 .gitignore
- 定期更新：
- 项目规范变化时同步更新配置文件
- Code Review 时检查配置文件是否需要更新
5.4 常见问题解决
问题 1：AI 不遵循配置文件中的规则
解决方案：
- 检查文件名是否正确（大小写敏感）
- 使用更强的强调词（MUST、NEVER）
- 将重要规则放在文件开头
- 减少文件总长度，突出重点
问题 2：多个配置文件冲突
解决方案：
- 理解优先级机制（就近原则）
- 在子目录配置中明确覆盖父目录规则
- 保持配置文件间的一致性
问题 3：配置文件太长，AI 可能忽略部分内容
解决方案：
- 精简内容，只保留最重要的规则
- 使用
@import语法引用其他文件（如果工具支持） - 将详细文档放在单独文件，配置文件只放摘要
5.5 与 CI/CD 集成
可以在 CI 中验证代码是否符合配置文件中的规范：
# .github/workflows/ci.ymlname: CI on:[push, pull_request]jobs:lint:runs-on: ubuntu-latest steps:-uses: actions/checkout@v4 -uses: pnpm/action-setup@v2 -run: pnpm install -run: pnpm lint -run: pnpm typecheck test:runs-on: ubuntu-latest steps:-uses: actions/checkout@v4 -uses: pnpm/action-setup@v2 -run: pnpm install -run: pnpm test 5.6 配置文件模板
为了快速启动新项目，可以创建团队通用的配置模板：
前端项目模板：
# [PROJECT_NAME] Frontend ## Tech Stack - Framework: React/Vue/Svelte - Language: TypeScript - Styling: TailwindCSS/CSS Modules - State: Zustand/Pinia/Redux ## Commands - `pnpm dev` - Start dev server - `pnpm build` - Production build - `pnpm test` - Run tests - `pnpm lint` - Lint code ## Code Style [团队前端规范] ## Testing [测试要求] 后端项目模板：
# [PROJECT_NAME] Backend ## Tech Stack - Runtime: Node.js/Go/Python - Framework: Express/Gin/FastAPI - Database: PostgreSQL/MySQL/MongoDB - ORM: Prisma/GORM/SQLAlchemy ## Commands - `pnpm dev` - Start dev server - `pnpm build` - Build for production - `pnpm test` - Run tests - `pnpm db:migrate` - Run migrations ## API Design [API 设计规范] ## Security [安全要求] 6. 总结
写这篇文章的过程中，我对 CLAUDE.md 和 AGENTS.md 的理解更加深刻了。说实话，一开始我也觉得这不就是写个配置文件嘛，有什么难的？但是深入研究后发现，这里面的门道还挺多的。
6.1 核心要点回顾
- CLAUDE.md 是 Claude Code 专属的配置文件，每次启动时自动加载到上下文。
- AGENTS.md 是一个开放标准，被 60,000+ 项目和主流 AI 工具采用。
- 两个文件的核心目的相同：为 AI 提供项目上下文，让它更好地理解和遵循你的开发规范。
- 配置文件应该包含：
- 常用命令（构建、测试、部署）
- 代码风格指南
- 项目结构说明
- 开发规范和注意事项
- 最佳实践：
- 保持简洁，突出重点
- 使用强调词提高遵循度
- 分层配置，支持团队协作
- 定期更新，与项目同步
6.2 选择建议
| 场景 | 建议 |
|---|---|
| 只用 Claude Code | 使用 CLAUDE.md |
| 只用 Cursor/Copilot | 使用 AGENTS.md |
| 团队使用多种工具 | 同时维护两个文件 |
| 开源项目 | 优先使用 AGENTS.md（更通用） |
6.3 未来展望
随着 AI 编程助手的快速发展，配置文件的标准化趋势会越来越明显。AGENTS.md 作为一个开放标准，正在被越来越多的工具和项目采用。
未来可能会出现：
- 更智能的配置文件解析
- 跨工具的配置同步
- 基于项目分析的自动配置生成
- 配置文件的版本管理和继承机制
无论工具如何演进，核心理念不会变：让 AI 更好地理解你的项目，才能更好地帮助你。
现在就开始为你的项目创建 CLAUDE.md 或 AGENTS.md 吧！
以后还需要继续努力。加油！
