什么是 CLAUDE.md

CLAUDE.md 是 Claude Code 的项目指令文件，类似于 .editorconfig 或 .eslintrc 的角色。Claude 在启动时会自动加载这些文件，作为与代码库交互的上下文。

文件层级

Claude Code 会按以下顺序加载 CLAUDE.md，优先级从低到高：

位置	作用域	说明
~/.claude/CLAUDE.md	全局	所有项目通用的指令
项目根目录/CLAUDE.md	项目级	项目特定的指令，会提交到 Git
项目根目录/CLAUDE.local.md	项目级（本地）	不提交到 Git 的个人指令
子目录/CLAUDE.md	目录级	当 Claude 访问该目录下的文件时加载

编写建议

基本结构

# CLAUDE.md

## Project Overview
简要描述项目的技术栈和用途。

## Commands
常用的开发、构建、测试命令。

## Architecture
项目的目录结构和关键文件说明。

## Coding Conventions
代码风格、命名规范、提交规范等。

好的实践

• 简洁明了：避免冗长描述，Claude 会阅读整个文件
• 可操作：写具体的命令和规则，而非模糊的建议
• 保持更新：随项目演进及时更新
• 分层组织：通用指令放全局，项目指令放项目级

示例

# CLAUDE.md

## Project Overview
基于 Next.js 14 + TypeScript 的电商平台，使用 Prisma ORM + PostgreSQL。

## Commands
- `pnpm dev` — 启动开发服务器
- `pnpm test` — 运行测试（vitest）
- `pnpm test:e2e` — 运行 E2E 测试（Playwright）
- `pnpm lint` — ESLint 检查
- `pnpm db:migrate` — 执行数据库迁移

## Architecture
- `src/app/` — Next.js App Router 页面
- `src/components/` — 可复用组件
- `src/lib/` — 工具函数和配置
- `prisma/schema.prisma` — 数据库模型

## Conventions
- 组件使用 PascalCase 命名
- API 路由返回统一的 `{ data, error }` 格式
- 所有数据库操作通过 service 层，不在组件中直接调用 Prisma
- 提交信息遵循 Conventional Commits

使用 /init 快速生成

在项目根目录执行 /init，Claude 会分析代码库并自动生成 CLAUDE.md：

/init

生成后建议人工审查和调整。