Claude Code MCP、Hooks 与 CLAUDE.md 配置教程：从规则到自动化
Claude Code 的能力不只来自模型本身。CLAUDE.md 负责告诉它项目如何工作，MCP 负责连接外部工具，Hooks 负责在特定事件前后运行脚本。三者解决的问题不同，混在一起配置会让排错变得困难。本文按“先写规则，再接工具，最后加自动化”的顺序，给出一套能复核的配置方法。
内容依据 Anthropic 当前的 Claude Code 官方文档。MCP 服务器的安全性、认证方式和可用工具由服务器提供方决定；Hooks 执行本地命令，也可能改变工具调用结果，必须经过代码审查。
三种机制分别解决什么问题
| 机制 | 主要作用 | 配置位置示例 | 是否适合提交到仓库 |
|---|---|---|---|
CLAUDE.md | 项目说明、编码规范、验收步骤 | ./CLAUDE.md、.claude/rules/ | 团队规则可以提交 |
| MCP | 连接文档、工单、数据库或自定义工具 | ~/.claude.json、.mcp.json、命令行 | 配置可共享，凭证不要提交 |
| Hooks | 在事件前后执行脚本或做决策 | .claude/settings.json、settings.local.json | 团队自动化可以提交 |
先处理规则，再接工具的原因很简单：如果项目目标、目录边界和验收标准都没写清楚，MCP 只会让 Claude Code 更快地访问更多信息，Hooks 也可能把错误动作自动化。
CLAUDE.md 怎么写才有用
项目根目录的 CLAUDE.md 会在会话开始时作为项目上下文加载。建议控制长度，官方文档给出的实践是尽量保持短小，超过约 200 行时考虑拆成路径规则。内容应包含：
# 项目工作约定
## 目录
- API handler 在 src/api/handlers/
- 数据访问层在 src/db/
- 测试在 test/，不要把临时脚本放进去
## 命令
- 安装依赖：pnpm install
- 单元测试：pnpm test
- 代码检查：pnpm lint
## 修改流程
- 先阅读相关文件并列出计划
- 修改后展示 git diff
- 运行与改动相关的测试
- 不读取 .env 和生产凭证“保持高质量”“注意性能”都过于抽象。应改成能检查的动作，比如“新增 API handler 后运行 pnpm test --filter api”。如果只有某一目录需要特殊规则，可以使用 .claude/rules/，并按路径范围组织文件。个人偏好可放在用户级 ~/.claude/CLAUDE.md，团队项目约定放在仓库内。
CLAUDE.md 是上下文，不是不可绕过的安全边界。拒绝读取密钥、限制命令或强制合规要求，应放在权限设置和组织托管策略中。官方还支持 AGENTS.md，但团队应统一约定文件来源，避免同一条规则在多处冲突。
MCP 的连接类型
官方 MCP 文档当前列出远程 HTTP、远程 SSE、本地 stdio 和远程 WebSocket 等方式。HTTP 适合只需请求响应的远程服务；WebSocket 适合持续双向连接；stdio 适合在本机启动一个命令作为服务器。服务器需要什么认证，由服务器说明决定。
先查看已有服务器：
claude mcp list添加远程 HTTP 服务器时，命令格式以当前 CLI 帮助为准。常见形式是：
claude mcp add --transport http docs https://example.com/mcp本地 stdio 服务器通常需要命令和参数：
claude mcp add --transport stdio local-tools -- npx -y example-mcp-server上面的域名和包名只是格式示例，不代表一个可用服务。实际接入前要核对服务器文档、认证、数据范围和维护方。添加完成后，在会话中查看服务器状态，确认工具是否真的连接，而不是只看配置文件里出现了一行文字。
项目级 MCP 配置可能需要工作区信任。官方文档说明，未信任的克隆仓库不能自行批准项目服务器；这能降低打开陌生仓库时自动连接外部服务的风险。对第三方服务器要特别警惕提示注入：外部文档、工单或网页内容可能包含诱导 Claude 执行不相关动作的文本。
MCP 凭证变量的坑
MCP 配置支持环境变量展开，但 Claude Code 会对自己的凭证变量和若干云 provider 凭证做特殊保护。官方文档明确提醒，直接在服务器 headers 中写 ${ANTHROPIC_AUTH_TOKEN} 可能得到空值，最终表现为 401。若服务器确实需要一个变量，应按照其文档使用专门的变量名，并在当前 shell 中验证变量存在，不要打印完整凭证。
推荐这样检查：
test -n "$MCP_SERVER_TOKEN" && echo "token is set" || echo "token is empty"
claude mcp list不要把真实 Token 写入 .mcp.json 并提交。共享配置只放服务器地址和非敏感选项，密钥放环境变量、系统密钥管理或组织托管配置。
Hooks 的工作方式
Hooks 可以在 Claude Code 的事件前后运行 shell 命令、HTTP 处理器或其他处理程序。常见事件包括 SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PermissionRequest、Stop、TaskCompleted 等。事件和字段会随版本增加，配置前先看官方 Hooks reference。
Hook 的位置决定范围：用户级 ~/.claude/settings.json 影响你的所有项目；项目级 .claude/settings.json 可以提交给团队；.claude/settings.local.json 适合个人测试；插件和 skill 也可以携带自己的 Hooks。PreToolUse 适合在工具执行前检查命令，必要时返回拒绝决策；PostToolUse 适合记录结果或触发格式化。
一个简化的项目设置示例：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "./scripts/check-command.sh"
}
]
}
]
}
}脚本应读取官方定义的 JSON 输入，并在需要阻止动作时返回正确的决策结构。不要只依赖退出码猜测行为：不同事件对退出码、标准输出和 JSON 输出的处理不同。脚本要设置超时，避免每次工具调用都被一个挂起进程拖住。
Hook 最适合做确定性检查，例如禁止删除生产目录、检查格式化结果、在会话开始加载环境信息。它不适合承载复杂业务逻辑，也不应偷偷上传完整提示词、源码或凭证。任何会修改文件的 Hook，都应在临时分支中验证。
一个可落地的配置顺序
第一步，只创建 CLAUDE.md，让 Claude Code 复述项目入口和测试命令。第二步，添加一个只读 MCP，例如文档检索服务，确认工具名称、连接状态和数据范围。第三步，配置一个只做日志的 Hook，观察它收到的事件输入。第四步，再加入拒绝危险命令的 Hook，并用安全命令和危险命令各测试一次。每一步都保留 Git diff 和终端输出。
| 验证项 | 通过标准 | 失败时先查什么 |
|---|---|---|
| 项目规则 | 能复述目录、命令和限制 | 文件位置、拼写、范围 |
| MCP 连接 | claude mcp list 状态正常，工具可调用 | URL、认证、工作区信任 |
| Hook 触发 | 指定事件产生预期输出 | matcher、事件名、脚本权限 |
| Hook 拒绝 | 危险样例被阻止，普通样例通过 | JSON 决策格式、退出码 |
| 凭证安全 | 配置和日志没有完整 Token | 环境变量、调试输出、提交记录 |
FAQ
MCP 配置放在哪里？
不同范围使用不同位置：用户级设置、项目级 .mcp.json 或 Claude Code 自己维护的配置。以当前 CLI 的 claude mcp add 和官方文档为准，先用 claude mcp list 查看实际状态。
为什么 MCP 服务器显示 Pending approval？
项目目录可能尚未被信任，或者服务器需要用户批准。先确认仓库来源和服务器可信度，再在会话中完成批准。
Hooks 能代替权限设置吗？
不能。Hook 可以在某些事件中做检查，但权限规则和托管策略仍是主要控制面。
CLAUDE.md 写得越长越好吗？
不是。只写项目真正需要的规则，局部规则放到 .claude/rules/，减少无关上下文。
远程 MCP 与本地 stdio 怎么选？
远程服务适合团队共享或已有云端接口，本地 stdio 适合本机工具和内网资源。选择时同时考虑认证、数据流向、可用性和维护责任。
官方资料与相关接入
