【教程】CLAUDE.md 与 AGENTS.md 完全指南：让 AI 编程助手更懂你的项目

本文详细介绍 CLAUDE.md 和 AGENTS.md 两个配置文件的作用、格式和最佳实践，包括文件位置优先级、内容规范、实践案例。适合已使用过 Claude Code、Cursor 等 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 会同时读取：

1. packages/frontend/CLAUDE.md
2. my-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 优化技巧

1. 迭代优化：不要一次性写太多内容，像调优 Prompt 一样逐步实验和调整。

2. 使用强调词：对于重要规则，可以使用 “IMPORTANT”、“YOU MUST”、“NEVER” 等词汇提高遵循度。

## 重要规则

**IMPORTANT**: 所有 API 请求必须经过 `src/api/request.ts` 封装

**YOU MUST**: 提交代码前运行 `pnpm lint` 和 `pnpm typecheck`

**NEVER**: 不要在前端代码中硬编码 API 地址

3. 使用 # 快捷指令：在 Claude Code 对话中按 # 键，可以快速将当前对话中的重要信息添加到 CLAUDE.md。

4. 区分本地和共享配置：

   • 团队共享的规则放在 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.yml
read: 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

# 初始化 pnpm
pnpm 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 内容组织原则

1. 简洁明了：AI 的上下文窗口有限，不要写太多无关内容。

2. 结构清晰：使用标题、列表、表格组织内容，便于 AI 解析。

3. 可操作性强：提供具体的命令和示例，而不是抽象的描述。

# 不好的写法
我们的代码风格比较严格，请注意保持一致性。

# 好的写法
## 代码风格
- 使用 2 空格缩进
- 字符串使用单引号
- 行尾不加分号
- 运行 `pnpm lint` 检查

5.2 优先级和强调

对于重要规则，使用强调词提高遵循度：

## 关键规则

**CRITICAL**: 所有数据库迁移必须经过 review

**IMPORTANT**: API 响应必须包含错误码

**MUST**: 提交前必须通过所有测试

**NEVER**: 永远不要在日志中打印敏感信息

**ALWAYS**: 总是使用参数化查询防止 SQL 注入

5.3 团队协作策略

1. 分层配置：

   • 根目录：团队通用规则
   • 子目录：项目/模块特定规则
   • local 文件：个人偏好

2. 版本控制：

   • CLAUDE.md 和 AGENTS.md 提交到 git
   • CLAUDE.local.md 加入 .gitignore

3. 定期更新：

   • 项目规范变化时同步更新配置文件
   • Code Review 时检查配置文件是否需要更新

5.4 常见问题解决

问题 1：AI 不遵循配置文件中的规则

解决方案：

• 检查文件名是否正确（大小写敏感）
• 使用更强的强调词（MUST、NEVER）
• 将重要规则放在文件开头
• 减少文件总长度，突出重点

问题 2：多个配置文件冲突

解决方案：

• 理解优先级机制（就近原则）
• 在子目录配置中明确覆盖父目录规则
• 保持配置文件间的一致性

问题 3：配置文件太长，AI 可能忽略部分内容

解决方案：

• 精简内容，只保留最重要的规则
• 使用 @import 语法引用其他文件（如果工具支持）
• 将详细文档放在单独文件，配置文件只放摘要

5.5 与 CI/CD 集成

可以在 CI 中验证代码是否符合配置文件中的规范：

# .github/workflows/ci.yml
name: 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 核心要点回顾

1. CLAUDE.md 是 Claude Code 专属的配置文件，每次启动时自动加载到上下文。

2. AGENTS.md 是一个开放标准，被 60,000+ 项目和主流 AI 工具采用。

3. 两个文件的核心目的相同：为 AI 提供项目上下文，让它更好地理解和遵循你的开发规范。

4. 配置文件应该包含：

   • 常用命令（构建、测试、部署）
   • 代码风格指南
   • 项目结构说明
   • 开发规范和注意事项

5. 最佳实践：

   • 保持简洁，突出重点
   • 使用强调词提高遵循度
   • 分层配置，支持团队协作
   • 定期更新，与项目同步

6.2 选择建议

场景	建议
只用 Claude Code	使用 CLAUDE.md
只用 Cursor/Copilot	使用 AGENTS.md
团队使用多种工具	同时维护两个文件
开源项目	优先使用 AGENTS.md（更通用）

6.3 未来展望

随着 AI 编程助手的快速发展，配置文件的标准化趋势会越来越明显。AGENTS.md 作为一个开放标准，正在被越来越多的工具和项目采用。

未来可能会出现：

• 更智能的配置文件解析
• 跨工具的配置同步
• 基于项目分析的自动配置生成
• 配置文件的版本管理和继承机制

无论工具如何演进，核心理念不会变：让 AI 更好地理解你的项目，才能更好地帮助你。

现在就开始为你的项目创建 CLAUDE.md 或 AGENTS.md 吧！

以后还需要继续努力。加油！

参考资料

• Claude Code Best Practices - Anthropic
• AGENTS.md Official Website
• Agentic AI Foundation