CLAUDE.md 的作用

CLAUDE.md 是最重要的配置文件，它是项目的整体约束，每次启动 Claude Code 会话时，它都会自动读取并加载这个文件中的内容。

CLAUDE.md文件告诉AI，这个项目是什么、遵循什么规范、有哪些注意事项，让AI每次都能以符合项目要求的方式工作，而不是每次对话都重新解释。

CLAUDE.md文件存放位置

Claude Code 会从多个位置加载CLAUDE.md，不同位置的文件作用范围不同：

当多个位置都存在CLAUDE.md时，Claude Code 会将它们全部加载并合并，优先级从高到低依次为：

项目本地 → 项目根目录 → 子目录 → 全局用户级

快速创建

现有项目添加

最简单的方式是让 Claude Code 自动生成初始版本。在项目目录中启动 Claude Code 后，执行：

/init

Claude Code 会分析你的项目结构、代码风格、已有配置文件（如package.json、pyproject.toml、.eslintrc等），自动生成一份符合项目实际情况的CLAUDE.md，然后你可以在此基础上补充和调整。

手动创建

纯手工编辑，通过命令、或者编辑工具编写。

文件内容结构

CLAUDE.md是一个普通的 Markdown 文件，没有强制的格式要求，但良好的结构能帮助 Claude 更快找到关键信息。以下是推荐的内容结构：

# 项目名称 一句话说明这个项目是什么，方便 Claude 快速定位项目性质。 ## 技术栈 - 语言：Python 3.11 - 框架：FastAPI 0.110 - 数据库：PostgreSQL 15 + SQLAlchemy ORM - 测试：pytest ## 常用命令 ### 开发 ```bash uv run uvicorn main:app --reload # 启动开发服务器 uv run pytest # 运行所有测试 uv run pytest -k "test_auth" # 运行指定测试 ``` ### 代码检查 ```bash uv run ruff check . # 代码检查 uv run ruff format . # 代码格式化 ``` ## 项目结构 - `src/api/` — API 路由和请求处理 - `src/models/` — 数据库模型定义 - `src/services/` — 业务逻辑层 - `tests/` — 测试文件，与 src/ 目录结构镜像对应 ## 编码规范 - 使用 `uv` 管理依赖，不使用 pip 直接安装 - 所有函数必须有类型注解 - 字符串一律使用双引号 - 新增 API 路由必须同步添加测试 ## 注意事项 - 不要修改 `migrations/` 目录下的已有文件，只能新增迁移文件 - `config/secrets.py` 包含敏感配置，禁止输出其内容到日志或终端 - 数据库操作必须通过 Service 层，不要在路由层直接操作 ORM

项目结构说明

帮助 Claude 快速定位文件，减少不必要的目录扫描，尤其在大型项目中效果明显：

``` src/ ├── app/ # Next.js App Router 页面 │ ├── (auth)/ # 需要登录才能访问的页面组 │ └── api/ # API 路由 ├── components/ # 可复用 UI 组件 │ ├── ui/ # 基础 UI 组件（Button、Input 等） │ └── features/ # 业务组件（按功能模块组织） ├── lib/ # 工具函数和配置 │ ├── db/ # 数据库客户端和查询 │ └── auth/ # 认证相关逻辑 └── types/ # TypeScript 类型定义 ``` 关键文件： - `src/lib/db/client.ts` — 数据库连接配置 - `src/middleware.ts` — 认证中间件，处理路由保护 - `env.example` — 所有必要的环境变量示例

编码规范

告知 Claude 项目的代码风格和约定，确保生成的代码与现有代码库风格一致：

## 编码规范 ### 通用 - 文件名使用 kebab-case（如 `user-profile.ts`），类名使用 PascalCase - 优先使用具名导出（named export），避免默认导出（default export） - 异步函数一律使用 async/await，禁止使用 .then() 链式调用 ### 组件规范 - 组件文件与其测试文件放在同一目录（如 `Button.tsx` 和 `Button.test.tsx`） - Props 类型使用 interface 定义，命名格式为 `${组件名}Props` - 不要将业务逻辑写在组件中，提取为自定义 Hook 或 Service ### 错误处理 - API 路由使用统一的错误响应格式：`{ error: string, code: string }` - 客户端错误通过 Error Boundary 捕获，不要在每个组件里单独 try/catch

架构约束与禁止事项

这是防止 Claude 犯"聪明但错误"决策的关键部分。对于你了解但 Claude 不知道的特殊情况，必须明确写出来：

## 架构约束 - 所有数据库查询必须通过 `src/lib/db/queries/` 中的函数执行，不要在路由或组件中直接写 SQL - 状态管理使用 Zustand，不要引入 Redux 或其他状态管理库 - 样式使用 Tailwind CSS utility class，不要新增 CSS 文件或使用 CSS Modules ## 注意事项（重要） - `legacy/` 目录下的代码是遗留代码，**禁止修改**，只能读取 - `.env.local` 和 `.env.production` 包含真实密钥，**禁止输出文件内容** - `prisma/migrations/` 中已有的迁移文件**禁止修改**，数据库变更只能新增迁移 - 修改 `src/middleware.ts` 前必须先告知我，该文件影响所有路由的认证逻辑

开发环境说明

帮助 Claude 理解项目的运行环境，避免因环境差异导致命令执行失败：

## 开发环境 - Node.js：需要 v20 或以上版本（通过 `.nvmrc` 指定） - 包管理器：pnpm（禁止使用 npm 或 yarn 安装依赖） - 本地数据库：Docker Compose 启动（`docker compose up -d`） - 端口：前端 3000，API 3001，数据库 5432 ### 环境变量 参考 `.env.example` 文件配置本地环境变量，复制为 `.env.local` 后填入实际值。 必填项：`DATABASE_URL`、`NEXTAUTH_SECRET`、`NEXTAUTH_URL`

用 @ 语法引用外部文件

当项目已经有了规范文档（如 API 设计规范、数据库设计文档等），不需要将内容复制到CLAUDE.md中，直接用@文件路径引用即可。

Claude 读取CLAUDE.md时会自动加载引用的文件内容：

## 规范文档 详细的 API 设计规范请参考： @docs/api-design-guide.md 数据库设计约定： @docs/database-conventions.md 组件库使用说明： @docs/component-guidelines.md

全局 CLAUDE.md 的使用建议

用户级别的~/.claude/CLAUDE.md适合存放跨项目通用的个人偏好和习惯，这些内容对所有项目生效：

<!-- 文件路径：~/.claude/CLAUDE.md --> # 个人全局配置 ## 回答偏好 - 回复使用中文 - 代码修改前先简要说明修改思路，不要直接给出代码 - 遇到有多种实现方案时，列出选项让我选择，而不是直接选一种 ## 通用约定 - 提交信息使用英文，格式：`type(scope): description` - 新文件开头不加版权注释 - 优先使用原生 API，避免引入不必要的依赖 ## 安全习惯 - 修改认证相关代码前主动提示我注意安全影响 - 不要在代码注释或日志中输出任何密钥或 token

CLAUDE.md 的维护建议

保持精要

CLAUDE.md的内容会在每次会话中占用上下文窗口。内容过多会压缩 Claude 实际可用的上下文空间，反而降低效率。建议遵循以下原则：

• 每条规则只写一次，不要重复表达相同意思
• 与代码无关的背景信息（如公司介绍、产品规划）不要写进来
• 能通过代码本身传达的信息（如 eslint 配置已经定义了代码风格），不需要在CLAUDE.md中重复声明
• 建议总字数控制在 500 字以内，超过 1000 字时需要考虑精简

持续更新

随着项目的演进，CLAUDE.md也需要同步更新。以下时机应该触发更新：

• 更换了包管理器或构建工具
• 添加或移除了重要的依赖库
• 制定了新的编码约定
• 发现 Claude 反复犯同一类错误（说明需要在CLAUDE.md中补充说明）
• 某个文件或模块变得不能随意修改（增加到注意事项中）

用命令式语言

指令越明确，Claude 遵守的概率越高。避免模糊的描述，使用直接的命令：