CLAUDE.md 的作用CLAUDE.md 是最重要的配置文件它是项目的整体约束每次启动 Claude Code 会话时它都会自动读取并加载这个文件中的内容。CLAUDE.md文件告诉AI这个项目是什么、遵循什么规范、有哪些注意事项让AI每次都能以符合项目要求的方式工作而不是每次对话都重新解释。CLAUDE.md文件存放位置Claude Code 会从多个位置加载CLAUDE.md不同位置的文件作用范围不同位置路径作用范围是否提交 git项目根目录{项目根目录}/CLAUDE.md当前项目所有会话✅ 推荐提交团队共享项目本地{项目根目录}/.claude/CLAUDE.md当前项目所有会话❌ 加入 .gitignore仅个人使用子目录{任意子目录}/CLAUDE.mdClaude 打开该目录下的文件时自动加载✅ 适合多模块仓库全局用户级~/.claude/CLAUDE.md当前用户的所有项目❌ 个人配置不提交当多个位置都存在CLAUDE.md时Claude Code 会将它们全部加载并合并优先级从高到低依次为项目本地 → 项目根目录 → 子目录 → 全局用户级快速创建现有项目添加最简单的方式是让 Claude Code 自动生成初始版本。在项目目录中启动 Claude Code 后执行/initClaude 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 - 端口前端 3000API 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避免引入不必要的依赖 ## 安全习惯 - 修改认证相关代码前主动提示我注意安全影响 - 不要在代码注释或日志中输出任何密钥或 tokenCLAUDE.md 的维护建议保持精要CLAUDE.md的内容会在每次会话中占用上下文窗口。内容过多会压缩 Claude 实际可用的上下文空间反而降低效率。建议遵循以下原则每条规则只写一次不要重复表达相同意思与代码无关的背景信息如公司介绍、产品规划不要写进来能通过代码本身传达的信息如 eslint 配置已经定义了代码风格不需要在CLAUDE.md中重复声明建议总字数控制在 500 字以内超过 1000 字时需要考虑精简持续更新随着项目的演进CLAUDE.md也需要同步更新。以下时机应该触发更新更换了包管理器或构建工具添加或移除了重要的依赖库制定了新的编码约定发现 Claude 反复犯同一类错误说明需要在CLAUDE.md中补充说明某个文件或模块变得不能随意修改增加到注意事项中用命令式语言指令越明确Claude 遵守的概率越高。避免模糊的描述使用直接的命令❌ 模糊描述✅ 明确指令代码应该比较整洁函数不超过 50 行超过时必须拆分尽量写测试每个新增函数都必须有对应的单元测试注意安全用户输入必须通过sanitize()函数处理后才能传入数据库查询legacy 目录不太重要禁止修改legacy/目录下的任何文件用 pnpm 比较好依赖管理只使用 pnpm禁止使用 npm 或 yarn