◆ ClaudeCodeLab
Advanced

CLAUDE.md 编写完全指南：项目配置最佳实践

深入讲解如何编写高效的 CLAUDE.md 文件。学会向 Claude Code 传达你的技术栈、规范和项目结构，最大化输出质量。

什么是 CLAUDE.md？

CLAUDE.md 是一个帮助 Claude Code 理解你项目的上下文文件。将它放在项目根目录，Claude Code 会在每次会话开始时自动读取。一份写得好的 CLAUDE.md 可以显著提升 Claude Code 的响应质量。

文件位置与优先级

你可以在多个位置放置 CLAUDE.md 文件，所有文件都会被加载：

~/.claude/CLAUDE.md          # 全局设置（所有项目共享）
./CLAUDE.md                   # 项目根目录（团队共享）
./CLAUDE.local.md             # 本地设置（添加到 .gitignore）
./src/CLAUDE.md               # 子目录级别设置
  • 全局：你的个人编码风格偏好
  • 项目根目录：团队共享的规则和技术栈
  • 本地：不提交到 Git 的个人设置
  • 子目录：特定模块的补充上下文

入门模板

以下是一个实用的 CLAUDE.md 模板：

# 项目概述

电商后端 API。负责订单管理、库存管理和用户认证。

## 技术栈

- 语言：TypeScript 5.x
- 运行时：Node.js 22
- 框架：Fastify
- 数据库：PostgreSQL 16 + Prisma ORM
- 测试：Vitest
- CI：GitHub Actions

## 目录结构

src/
  routes/       # API 路由定义
  services/     # 业务逻辑
  repositories/ # 数据访问层
  middleware/   # 认证、日志、错误处理
  utils/        # 工具函数
  types/        # 类型定义

## 编码规范

- 使用箭头函数
- 错误处理必须使用 try-catch + 自定义错误类
- 命名：camelCase（变量/函数），PascalCase（类型/类）
- 文件名：kebab-case
- 使用路径别名 `@/` 替代相对路径导入

## 常用命令

- 运行测试：`npm test`
- 类型检查：`npx tsc --noEmit`
- Lint 检查：`npm run lint`
- 数据库迁移：`npx prisma migrate dev`
- 启动开发服务器：`npm run dev`

## 重要规则

- 修改 prisma/schema.prisma 后必须创建迁移
- 每个 API 端点都必须有 Zod 验证 Schema
- 新路由必须在 routes/index.ts 中注册

编写高效 CLAUDE.md 的技巧

1. 保持简洁

CLAUDE.md 会消耗上下文窗口的 Token。避免冗长的解释，用条目列表表达。

# 反面示例
这个项目使用 TypeScript。TypeScript 是微软开发的
一种在 JavaScript 基础上添加类型系统的语言...

# 正面示例
- 语言：TypeScript 5.x（严格模式）

2. 记录你不想要的东西

明确列出反模式出奇地有效。

## 禁止事项

- 不允许使用 `any` 类型
- 不允许默认导出（仅使用命名导出）
- 不允许使用 console.log 调试（使用 logger）
- 不允许删除或跳过现有测试

3. 定义工作流

引导 Claude Code 以正确的方式处理任务。

## 添加新功能的流程

1. 在 `src/types/` 中创建类型定义
2. 在 `src/repositories/` 中实现数据访问层
3. 在 `src/services/` 中实现业务逻辑
4. 在 `src/routes/` 中定义路由端点
5. 为每一层编写单元测试
6. 使用 `npm test` 验证所有测试通过

4. 记录团队”潜规则”

记录那些没有写在其他地方的重要信息。

## 项目特有注意事项

- `user_id` 使用 UUID v7（便于按时间排序）
- 所有价格计算必须使用 `Decimal.js`（避免浮点数精度问题）
- 环境变量统一在 `src/config.ts` 中管理——禁止直接访问 process.env

团队使用

.gitignore 配置

将个人设置排除在版本控制之外：

# .gitignore
CLAUDE.local.md

纳入代码审查

将 CLAUDE.md 视为重要的项目文档。在 PR 审查中关注它的变更，作为团队共同维护。

何时更新 CLAUDE.md

  • 引入新的库时
  • 更改编码规范时
  • 调整目录结构时
  • 发现 Claude Code 反复犯同样的错误时

总结

CLAUDE.md 能让 Claude Code 成为你项目的专家。先用 /init 生成基础框架，然后在使用过程中不断完善。与团队共享，让每个人都能享受优化后的 Claude Code 交互体验。

#Claude Code #CLAUDE.md #configuration #best practices #project management