使用 CLAUDE.md 文件：为你的代码库定制 Claude Code

来源：本文翻译自 Anthropic 官方博客 Using CLAUDE.md files: Customizing Claude Code for your codebase，发布于 2025 年 11 月 25 日。

如果你在使用 AI 编程助手，你会面临同样的挑战：如何在不重复自己的情况下，给它们足够的上下文来理解你的架构、约定和工作流？

随着代码库的增长，这个问题会变得更加复杂。复杂的模块关系、特定领域的模式和团队约定不容易显现出来。结果就是，你在每次对话开始时都要重复解释相同的架构决策、测试要求和代码风格偏好。

CLAUDE.md 文件通过给 Claude 提供关于你项目的持久上下文来解决这个问题。可以把这想象成一个配置文件，Claude 会自动将其纳入每次对话，确保它始终了解你的项目结构、编码标准和首选工作流。

在这篇文章中，我们将介绍如何构建你的 CLAUDE.md，分享最佳实践，以及如何使用它们从 Claude Code 中获得最大价值。

什么是 CLAUDE.md 文件？

CLAUDE.md 是一个特殊的配置文件，它存在于你的代码仓库中，为 Claude 提供项目特定的上下文。你可以将它放在仓库根目录与团队共享，放在父目录中用于 monorepo 设置，或者放在你的主目录中以在所有项目中通用。

以下是你可能在仓库中使用的 CLAUDE.md 示例：

# 项目上下文

处理此代码库时，优先考虑可读性而非技巧性。在进行架构更改之前，
请提出澄清性问题。

## 关于此项目

用于用户认证和配置文件的 FastAPI REST API。使用 SQLAlchemy 进行
数据库操作，使用 Pydantic 进行验证。

## 关键目录

- `app/models/` - 数据库模型
- `app/api/` - 路由处理器
- `app/core/` - 配置和工具函数

## 标准

- 所有函数都需要类型提示
- 使用 pytest 进行测试（fixtures 在 `tests/conftest.py` 中）
- PEP 8 风格，每行最多 100 个字符

## 常用命令

    uvicorn app.main:app --reload  # 开发服务器
    pytest tests/ -v               # 运行测试

## 注意事项

所有路由使用 `/api/v1` 前缀。JWT 令牌在 24 小时后过期。

配置良好的 CLAUDE.md 会改变 Claude 与你特定项目合作的方式。该文件有多种用途：提供架构上下文、建立工作流，以及将 Claude 连接到你的开发工具。每次添加都应该解决你遇到的实际问题，而不是关于 Claude 可能需要什么的理论性考虑。

这个文件可以记录常见的 bash 命令、核心工具函数、代码风格指南、测试说明、仓库约定、开发环境设置和项目特定的警告。没有必需的格式。建议是保持这个文件简洁且易于阅读，将其视为人类和 Claude 都需要快速理解的文档。

你的 CLAUDE.md 文件会成为 Claude 系统提示的一部分。每次对话开始时，这个上下文已经加载，消除了重复解释基本项目信息的需要。

使用 /init 开始

从头创建 CLAUDE.md 可能会让人望而生畏，尤其是在不熟悉的代码库中。

/init 命令通过分析你的项目并生成初始配置来自动化这个过程。

在任何 Claude Code 会话中运行 /init：

cd your-project
claude
/init

Claude 会检查你的代码库——读取包文件、现有文档、配置文件和代码结构——然后为你项目量身定制一个 CLAUDE.md。生成的文件通常包括构建命令、测试说明、关键目录和它检测到的编码约定。

把 /init 想象成一个起点，而不是成品。生成的 CLAUDE.md 捕获了明显的模式，但可能错过你工作流中特定的细微差别。审查 Claude 生成的内容，并根据你团队的实际实践进行改进。

你也可以在已经拥有 CLAUDE.md 的现有项目上使用 /init。Claude 会审查当前文件，并根据它从探索代码库中学到的内容建议改进。

运行 /init 后，考虑以下后续步骤：

审查生成内容的准确性
添加 Claude 无法推断的工作流说明（分支命名约定、部署流程、代码审查要求）
删除不适用于你项目的通用指导
将文件提交到版本控制，让你的团队受益

/init 命令对于快速入门很有用，但真正的价值在于随着时间的推移迭代生成的文件。当你使用 Claude Code 时，使用 # 键添加你发现自己重复的指令——这些添加会累积成一个真正反映你团队工作方式的 CLAUDE.md。

如何构建你的 CLAUDE.md

以下部分向你展示如何构建内容以获得最大影响：导航复杂架构、跟踪多步任务的进度、集成自定义工具，以及通过一致的工作流防止返工。

给 Claude 一张地图

解释你的项目架构、关键库和编码风格在每个新任务时都会变得繁琐。你需要 Claude 保持对代码库结构的一致上下文，而无需手动强化。

在 CLAUDE.md 中添加项目摘要和高级目录结构。这给 Claude 在导航代码库时提供即时定位。

一个简单的树形输出显示关键目录有助于 Claude 理解不同组件的位置：

main.py
├── logs
│   ├── application.log
├── modules
│   ├── cli.py
│   ├── logging_utils.py
│   ├── media_handler.py
│   ├── player.py

包含关于你的主要依赖项、架构模式和任何非标准组织选择的信息。如果你使用领域驱动设计、微服务或特定框架，请记录下来。Claude 使用这个地图来更好地决定在哪里查找代码和在哪里进行更改。

定义标准工作流

让 Claude 直接跳入代码更改而不进行规划会导致返工。Claude 可能实现一个遗漏需求的解决方案，选择错误的架构方法，或进行破坏现有功能的更改。

你需要 Claude 在行动之前思考。在 CLAUDE.md 中定义 Claude 应该为不同类型任务遵循的标准工作流。一个可靠的工作流在进行更改之前解决四个问题：

这是否是关于当前状态的问题，需要先进行调查？
这是否需要在实现之前制定详细计划？
缺少哪些额外信息？
如何测试有效性？

特定的工作流可能包括功能的 explore-plan-code-commit、算法工作的测试驱动开发，或 UI 更改的视觉迭代。记录你的测试要求、提交消息格式和任何审批步骤。当 Claude 提前了解你的工作流时，它会构建工作以匹配你团队的实际流程，而不是猜测。

一个示例工作流指令可能是：

1) 在修改以下位置的代码之前：X, Y, Z
   - 考虑它可能如何影响 A, B, C
   - 构建实现计划
   - 开发测试计划以验证以下功能...

使用 Claude Code 的额外技巧

除了配置 CLAUDE.md 文件外，还有三种额外技术可以改善你与 Claude Code 的合作方式。

保持上下文新鲜

随着时间的推移使用 Claude Code 会累积不相关的上下文。来自早期任务的文件内容、不再重要的命令输出和无关的对话会填满 Claude 的上下文窗口。随着信噪比下降，Claude 难以保持对当前任务的专注。

在不同任务之间使用 /clear 来重置上下文窗口。这会移除累积的历史记录，同时保留你的 CLAUDE.md 配置和 Claude 用新鲜上下文处理新问题的能力。想象一下关闭一个工作会话并打开另一个。

当你完成调试认证并切换到实现新的 API 端点时，清除上下文。认证细节不再重要，并且会分散新工作的注意力。

使用 subagent 处理不同阶段

长对话会累积干扰新任务的上下文。你已经调试了一个复杂的认证流程，现在需要对该相同代码进行安全审查。调试细节会影响 Claude 的安全分析，可能导致它忽视问题或关注已经解决的问题。

告诉 Claude 为工作的不同阶段使用 subagent。Subagent 维护隔离的上下文，防止来自早期任务的信息干扰新的分析。在实现支付处理器后，指示 Claude “使用 sub-agent 对该代码进行安全审查”，而不是在同一对话中继续。

Subagent 最适合每阶段需要不同视角的多步工作流。实现需要架构上下文和功能需求；安全审查需要专注于漏洞的新鲜视角。上下文分离使两种分析都保持敏锐。

创建自定义命令

重复的提示会浪费时间。你发现自己一遍又一遍地输入 “review this code for security issues” 或 “analyze this for performance problems”。每次你都需要记住能获得好结果的确切措辞。

从简单开始，有意识地扩展

一开始就创建一个全面的 CLAUDE.md 是很诱人的。抵制这种冲动。

CLAUDE.md 每次都会添加到 Claude Code 的上下文中，因此从上下文工程和提示工程的角度来看，保持简洁。一个选择是：将信息分解成单独的 markdown 文件，并在 CLAUDE.md 文件中引用它们。

不要包含敏感信息、API 密钥、凭据、数据库连接字符串或详细的安全漏洞信息——特别是如果你提交到版本控制。由于 CLAUDE.md 成为 Claude 系统提示的一部分，将其视为可以公开共享的文档。

让 CLAUDE.md 为你工作

CLAUDE.md 文件将 Claude Code 从通用助手转变为专门为你的代码库配置的工具。从简单的项目结构和构建文档开始，然后根据工作流中的实际摩擦点进行扩展。

最有效的 CLAUDE.md 文件解决实际问题：它们记录你重复输入的命令，捕获需要十分钟解释的架构上下文，并建立防止返工的工作流。你的文件应该反映你的团队实际开发软件的方式——而不是听起来不错但与现实不符的理论最佳实践。

将定制视为持续实践，而不是一次性的设置任务。项目会变化，团队会学习更好的模式，新的工具会进入你的工作流。维护良好的 CLAUDE.md 会随着你的代码库一起发展，持续减少在复杂软件上使用 AI 辅助的摩擦。

开始使用 Claude Code 今天。