CLAUDE.md 配置指南
使用 CLAUDE.md 为 Claude Code 提供项目背景和编码规范
CLAUDE.md 配置指南¶
CLAUDE.md 是 Claude Code 的项目级配置文件。每次启动 Claude Code 时，它会自动读取项目中的 CLAUDE.md，了解项目架构、编码规范和特殊约定，从而更准确地理解你的项目。
为什么需要 CLAUDE.md¶
不使用 CLAUDE.md 时，你可能需要在每次对话中反复解释：
- 「这个项目用 pnpm，不是 npm」
- 「测试命令是
yarn test:unit，不是npm test」 - 「所有组件使用 TypeScript，不要用 any」
将这些信息写入 CLAUDE.md，Claude 每次启动后自动读取，无需重复说明。
文件层级¶
Claude Code 会读取多个层级的 CLAUDE.md 并合并：
| 位置 | 作用范围 |
|---|---|
~/.claude/CLAUDE.md |
全局配置，适用于所有项目 |
项目根目录/CLAUDE.md |
项目配置，提交到 Git 供团队共享 |
.claude/CLAUDE.md |
项目私有配置，可加入 .gitignore |
子目录中的 CLAUDE.md |
仅在 Claude 处于该目录时读取 |
快速创建¶
使用 /init 命令自动生成：
/init
Claude 会分析当前项目结构，自动生成包含项目信息的 CLAUDE.md。
基本结构¶
# 项目名称
## 概述
简要描述项目的目的和技术栈。
## 技术栈
- 运行时：Node.js 20
- 框架：Next.js 15
- 样式：Tailwind CSS
- 数据库：PostgreSQL + Prisma
## 常用命令
- 启动开发服务器：`npm run dev`
- 运行测试：`npm test`
- 构建生产版本：`npm run build`
- 代码检查：`npm run lint`
## 编码规范
- 使用 TypeScript，禁止 `any` 类型
- 组件使用函数式写法
- 样式只用 Tailwind，不写内联 style
- 提交信息格式：`feat:` / `fix:` / `docs:` 等前缀
## 项目结构
- `src/app/` — Next.js App Router 页面
- `src/components/` — 可复用组件
- `src/lib/` — 工具函数
- `prisma/` — 数据库 schema 和迁移
## 注意事项
- 不要修改 `prisma/migrations/`，只创建新迁移
- 所有 API 路由都在 `src/app/api/`
- 图片资源放在 `public/images/`
实用技巧¶
1. 指定包管理器¶
## 包管理
使用 pnpm，不要使用 npm 或 yarn。
安装依赖：`pnpm install`
添加依赖：`pnpm add <包名>`
2. 说明测试规范¶
## 测试
- 单元测试：`vitest`，文件名以 `.test.ts` 结尾
- E2E 测试：`playwright`，位于 `tests/e2e/`
- 运行单元测试：`pnpm test:unit`
- 运行 E2E：`pnpm test:e2e`
- 新功能必须包含测试
3. 告知禁忌操作¶
## 禁止操作
- 不要使用 `console.log`，使用项目的 `logger` 模块
- 不要直接修改 `package-lock.json`
- 不要在 `main` 分支直接提交，使用功能分支
4. 提供架构背景¶
## 架构说明
本项目采用六边形架构（Hexagonal Architecture）：
- `domain/` — 业务逻辑，不依赖外部框架
- `application/` — 用例，协调 domain 和 infrastructure
- `infrastructure/` — 数据库、HTTP 等外部适配器
- `interfaces/` — Web 控制器、CLI 等入口
新功能应遵循此分层，不要在 domain 层引入外部依赖。
5. 引用其他文档¶
## 更多信息
- API 文档见 `docs/api.md`
- 部署流程见 `docs/deploy.md`
- 数据库 schema 见 `prisma/schema.prisma`
CLAUDE.md 与上下文管理¶
CLAUDE.md 的内容会占用上下文空间。建议：
- 保持 CLAUDE.md 简洁，聚焦最重要的信息
- 对于详细的架构文档，在 CLAUDE.md 中给出路径引用，而不是直接复制内容
- 在长会话中，CLAUDE.md 始终保持可见（不会被
/compact删除）