使用 CLAUDE.md 文件：为你的代码库定制 Claude Code
一份实用指南，教你使用 CLAUDE.md 文件来优化 Claude Code 的使用效果。
如果你使用 AI 编程 Agent，就会遇到同一个挑战：怎样给它们足够的上下文，让它们理解你的架构、约定和工作流，同时又不用每次都重复说明？
随着代码库变大，这个问题会进一步放大。复杂的模块关系、特定业务领域的模式，以及团队约定都不容易自动显现出来。结果就是，你会在每次对话开始时，反复解释同样的架构决策、测试要求和代码风格偏好。
CLAUDE.md 文件通过给 Claude 提供关于你项目的持久上下文来解决这个问题。你可以把它理解成一个配置文件，Claude 会在每次对话中自动纳入其中的内容，确保它始终知道你的项目结构、编码标准和偏好的工作流。
在本文中，我们会介绍如何组织你的 CLAUDE.md，分享最佳实践，以及一些使用技巧，帮助你最大化发挥 Claude Code 的价值。
什么是 CLAUDE.md 文件？
CLAUDE.md 是一个特殊的配置文件，放在你的仓库中，用来向 Claude 提供项目专属上下文。你可以把它放在仓库根目录，供团队共享；也可以放在父目录，用于 monorepo 场景；还可以放在你的 home 文件夹中，让它对所有项目通用。
下面是一个你可能会放在仓库里的 CLAUDE.md 示例：
# 项目上下文 使用这个代码库时，优先考虑可读性，不要追求炫技。在进行架构变更前，先提出澄清问题。 ## 关于这个项目 用于用户认证和用户资料的 FastAPI REST API。使用 SQLAlchemy 进行数据库操作，使用 Pydantic 做校验。 ## 关键目录 - `app/models/` - 数据库模型 - `app/api/` - 路由处理器 - `app/core/` - 配置和工具函数 ## 标准 - 所有函数都必须有类型提示 - 使用 pytest 进行测试（fixtures 在 `tests/conftest.py` 中） - 遵循 PEP 8，行宽 100 个字符 ## 常用命令 ```bash uvicorn app.main:app --reload # 开发服务器 pytest tests/ -v # 运行测试 ``` ## 说明 所有路由都使用 `/api/v1` 前缀。JWT token 24 小时后过期。
配置良好的 CLAUDE.md 会改变 Claude 处理你具体项目的方式。这个文件有多个用途：提供架构上下文、建立工作流，以及把 Claude 连接到你的开发工具。每一条新增内容都应该解决你真实遇到过的问题，而不是出于“Claude 可能需要什么”的理论担忧。
这个文件可以记录常用 bash 命令、核心工具函数、代码风格指南、测试说明、仓库约定、开发环境设置，以及项目专属警告。它没有强制格式。建议保持简洁、便于人类阅读，把它当成一份人和 Claude 都需要快速理解的文档。
你的 CLAUDE.md 文件会成为 Claude 系统提示词的一部分。每次对话开始时，这些上下文都已经加载好，因此不必反复解释基础项目信息。
使用 /init 入门
从零创建 CLAUDE.md 可能会让人有压力，尤其是在不熟悉的代码库中。
/init 命令会自动完成这个过程：它会分析你的项目，并生成一个初始配置。
在任意 Claude Code 会话中运行 /init：
cd your-project claude /init
Claude 会检查你的代码库，包括读取 package 文件、现有文档、配置文件和代码结构，然后生成一个适合你项目的 CLAUDE.md。生成的文件通常会包含构建命令、测试说明、关键目录，以及它检测到的编码约定。
把 /init 看作起点，而不是成品。生成的 CLAUDE.md 能捕捉明显模式，但可能遗漏你工作流中特有的细节。检查 Claude 生成的内容，并根据你团队的实际做法进行完善。
你也可以在已经有 CLAUDE.md 的现有项目中使用 /init。Claude 会查看当前文件，并根据它探索代码库后学到的信息提出改进建议。
运行 /init 后，可以考虑这些下一步：
• 检查生成内容是否准确
• 补充 Claude 无法推断出来的工作流说明（分支命名约定、部署流程、代码评审要求）
• 删除不适用于你项目的通用指导
• 把这个文件提交到版本控制中，让整个团队受益
/init 命令很适合快速熟悉项目，但真正的价值来自后续持续迭代这个生成文件。使用 Claude Code 工作时，可以用 # 键添加你发现自己总在重复的说明，这些补充会逐渐积累成一个真正反映你团队工作方式的 CLAUDE.md。
如何组织你的 CLAUDE.md
下面几个部分会展示如何组织内容，让它产生最大效果：导航复杂架构、跟踪多步骤任务进度、集成自定义工具，以及通过一致的工作流避免返工。
给 Claude 一张地图
如果每个新任务都要解释项目架构、关键库和编码风格，会非常繁琐。你需要让 Claude 在没有人工反复提醒的情况下，持续掌握代码库结构的上下文。
在 CLAUDE.md 中添加项目摘要和高层目录结构。这样 Claude 在浏览代码库时能立即知道大致方向。
一个展示关键目录的简单 tree 输出，可以帮助 Claude 理解不同组件放在哪里：
main.py ├── logs │ ├── application.log ├── modules │ ├── cli.py │ ├── logging _utils.py │ ├── media_ handler.py │ ├── player.py
包含你的主要依赖、架构模式，以及任何非标准的组织方式。如果你使用领域驱动设计、微服务或特定框架，请记录下来。Claude 会利用这张地图，更好地判断去哪里找代码，以及应该在哪里修改。
把 Claude 连接到你的工具
Claude 会继承你的完整环境，但它需要知道应该使用哪些自定义工具和脚本。你的团队很可能有用于部署、测试或代码生成的专用工具，Claude 应该了解这些工具。
在 CLAUDE.md 中记录你的自定义工具，并附上使用示例。包括工具名称、基本使用方式，以及什么时候应该调用它们。如果你的工具通过 --help 参数提供帮助文档，也要说明这一点，这样 Claude 就知道可以去查看。对于复杂工具，加入团队经常使用的常见调用示例。
Claude 可以作为 MCP（Model Context Protocol）客户端，连接到扩展其能力的 MCP server。你可以通过项目设置、全局配置，或提交到仓库的 .mcp.json 文件来配置这些连接。当工具没有按预期出现时，--mcp-debug 参数可以帮助排查连接问题。
例如，如果你为组织配置了 Slack MCP server，并且需要 Claude 理解如何使用它，可以在 CLAUDE.md 中写入类似内容：
### Slack MCP - 只发布到 #dev-notifications 频道 - 用于部署通知和构建失败提醒 - 不用于单个 PR 更新（这些通过 GitHub webhooks 处理） - 速率限制为每小时 10 条消息
进一步了解 MCP 基础知识和最佳实践。
关于为 Claude Code 设置权限的更多信息，请查看 code.claude.com 上的 settings.json 文档。
定义标准工作流
如果让 Claude 不做计划就直接改代码，往往会造成返工。Claude 可能实现了一个遗漏需求的方案，选择了错误的架构方式，或者做出破坏现有功能的修改。
你需要让 Claude 先思考再行动。在 CLAUDE.md 中定义标准工作流，说明 Claude 面对不同类型任务时应该遵循什么流程。一个可靠的默认工作流，会在修改前回答四个问题：
• 这是不是一个关于当前状态的问题，需要先调查？
• 实现前是否需要详细计划？
• 还缺少哪些额外信息？
• 如何测试效果？
具体工作流可以包括用于功能开发的 explore-plan-code-commit、用于算法工作的测试驱动开发，或用于 UI 修改的视觉迭代。记录你的测试要求、commit message 格式，以及任何审批步骤。当 Claude 预先知道你的工作流时，它会按照你团队真实流程来组织工作，而不是自己猜。
一个工作流说明示例可能是：
1) 在修改以下位置的代码前：X、Y、Z - 考虑它可能如何影响 A、B、C - 制定实现计划 - 制定测试计划，用来验证以下函数……
使用 Claude Code 的更多技巧
除了配置 CLAUDE.md 文件，还有三个额外技巧可以改善你使用 Claude Code 的方式。
保持上下文清爽
长期使用 Claude Code 会积累无关上下文。早先任务中的文件内容、已经不重要的命令输出，以及跑偏的对话，会填满 Claude 的上下文窗口。随着信噪比下降，Claude 会更难专注于当前任务。
在不同任务之间使用 /clear 来重置上下文窗口。这样会清除积累的历史，同时保留你的 CLAUDE.md 配置，以及 Claude 用新鲜上下文处理新问题的能力。你可以把它理解成关闭一个工作会话，然后开启另一个。
当你完成认证问题调试，切换到实现新的 API endpoint 时，清理上下文。认证细节已经不重要了，反而会干扰新的工作。
为不同阶段使用 子Agent
长对话会积累上下文，并干扰新任务。比如你刚调试完一个复杂的认证流程，现在需要对同一段代码做安全评审。调试细节会影响 Claude 的安全分析，可能让它忽略问题，或者把注意力放在已经解决的事项上。
告诉 Claude 针对不同工作阶段使用 子Agent。子Agent 会维护隔离的上下文，防止早先任务的信息干扰新的分析。实现支付处理器后，可以指示 Claude “use a sub-Agent to perform a security 审查 of that code”，而不是在同一个对话里继续。
子Agent 最适合多步骤工作流，因为每个阶段需要不同视角。实现阶段需要架构上下文和功能需求；安全评审阶段需要一双只关注漏洞的新眼睛。上下文隔离能让两种分析都保持清晰。
创建自定义命令
重复输入提示词会浪费时间。你可能会一遍又一遍地输入“审查 this code for security issues”或“analyze this for performance problems”。每次你都要记住哪种具体措辞能得到好结果。
自定义 slash commands 会把这些提示词存成 .claude/commands/ 目录中的 markdown 文件。创建一个名为 performance-optimization.mm 的文件，写入你偏好的性能优化提示词，它就会在任意对话中作为 /performance-optimization 可用。命令支持通过 $ARGUMENTS 或 $1、$2 这样的编号占位符接收参数，让你传入具体文件或参数。
例如，performance-optimization.md 可能如下所示：
# 性能优化 分析提供的代码，找出性能瓶颈和优化机会。请进行全面审查，覆盖以下内容： ## 需要分析的领域 ### 数据库与数据访问 - N+1 查询问题，以及缺少 eager loading - 经常查询的列缺少数据库索引 - 低效的 join 或子查询 - 大结果集缺少分页 - 缺少查询结果缓存 - 连接池问题 ### 算法效率 - 时间复杂度问题（例如存在更优方案时仍使用 O(n²) 或更差复杂度） - 可以优化的嵌套循环 - 冗余计算或重复工作 - 数据结构选择低效 - 缺少 memoization 或动态规划优化机会 ### 内存管理 - 内存泄漏或引用被长期保留 - 本可以流式处理，却一次性加载完整数据集 - 循环中过度创建对象 - 不必要地把大型数据结构保留在内存中 - 缺少垃圾回收优化机会 ### 异步与并发 - 本应异步的阻塞 I/O 操作 - 本可以并行执行，却按顺序执行的操作 - 缺少 Promise.all() 或并发执行模式 - 同步文件操作 - worker thread 使用未优化 ### 网络与 I/O - API 调用过多（缺少请求批处理） - 没有响应缓存策略 - 大 payload 未压缩 - 静态资源缺少 CDN - 缺少连接复用 ### 前端性能 - 阻塞渲染的 JavaScript 或 CSS - 缺少代码拆分或懒加载 - 图片或资源未优化 - 过多 DOM 操作或 reflow - 长列表缺少虚拟化 - 高开销操作缺少 debounce/throttle ### 缓存 - 缺少 HTTP 缓存 header - 没有应用层缓存 - 纯函数缺少 memoization - 静态资源没有 cache busting ## 输出格式 对每个发现的问题，请包含： 1. **Issue**：描述性能问题 2. **Location**：指出文件、函数、行号 3. **Impact**：标注严重程度（Critical/High/Medium/Low），并说明预期的性能下降 4. **Current Complexity**：适用时说明时间/空间复杂度 5. **Recommendation**：给出具体优化策略 6. **Code Example**：尽可能展示优化后的版本 7. **Expected Improvement**：如果可以衡量，请量化性能收益 如果代码已经优化得很好： - 确认优化状态 - 列出已经正确实现的性能最佳实践 - 说明仍可做的轻微改进 **要审查的代码：** ``` $ARGUMENTS ```
你不需要手动编写自定义命令文件。可以让 Claude 帮你创建：
创建一个名为 /performance-optimization 的自定义 slash command，用来分析代码中的数据库查询问题、算法效率、内存管理和缓存优化机会。
Claude 会把 markdown 文件写入 .claude/commands/performance-optimization.md，并且这个命令会立即可用。
从简单开始，有意识地逐步扩展
一开始就创建一个非常全面的 CLAUDE.md 很有诱惑力。但请克制这种冲动。
CLAUDE.md 每次都会被加入 Claude Code 的上下文，所以从 context engineering 和 提示词 engineering 的角度看，它应该保持简洁。一个可选做法是：把信息拆分到多个独立的 markdown 文件中，然后在 CLAUDE.md 文件里引用它们。
不要包含敏感信息、API key、凭证、数据库连接字符串，或详细的安全漏洞信息，尤其是在你会把它提交到版本控制时。因为 CLAUDE.md 会成为 Claude 系统提示词的一部分，所以请把它当作可能公开分享的文档来对待。
让 CLAUDE.md 真正为你服务
CLAUDE.md 文件可以把 Claude Code 从通用助手变成专门为你的代码库配置的工具。先从基础项目结构和构建文档开始，然后根据工作流中真实遇到的卡点逐步扩展。
最有效的 CLAUDE.md 文件解决的都是真实问题：记录你反复输入的命令，沉淀那些需要花十分钟才能讲清楚的架构上下文，并建立能避免返工的工作流。你的文件应该反映团队实际开发软件的方式，而不是那些听起来不错、但不符合现实的理论最佳实践。
把自定义配置当作持续实践，而不是一次性的设置任务。项目会变化，团队会学到更好的模式，新工具也会进入你的工作流。维护良好的 CLAUDE.md 会随代码库一起演进，持续降低在复杂软件中使用 AI assistance 的协作成本。
今天就开始使用 Claude Code。