Claude Code 最佳实践经验分享

CLAUDE.md

CLAUDE.md 是代码库的根目录中最重要的文件，它是代理理解你项目运作方式的核心规则。如何维护它，取决于使用场景。

• 个人项目： 随性发挥，让 Claude 自由记录。
• 专业项目： 严格维护。例如，在一个大型单体仓库中，CLAUDE.md 文件可能达到 13KB，并且只包含超过 30% 工程师会使用到的工具和 API 文档。我们甚至为内部工具的文档分配了“最大令牌数”，如同广告位，以此敦促团队保持文档的简洁性。

CLAUDE.md 的配置

• 随时随地优化
  CLAUDE.md 从小处着手，根据 Claude 犯错的地方来补充文档。它是一个动态优化修正的笔记，而不是一本静态的书本。

• 不要直接 @ 文件
  直接在 CLAUDE.md 中 @ 引用其他文档文件，会在每次运行时将整个文件内容注入上下文，造成严重浪费。正确做法是“引导”代理去阅读它。

  正确示例:
  “对于复杂的…用法，或当您遇到 FooBarError 错误时，请参阅 path/to/docs.md 以获取高级故障排除步骤。”

  你需要向代理建议阅读这份文档的理由和时机。

• 提供替代方案
  避免仅使用“永远不要 --foo-bar ”这样的纯否定约束。当代理认为必须使用该标志时，它会陷入困境。

  正确示例:
  “不要使用 --foo-bar，请优先选择 --new-baz。”

• 定义自己的工具
  如果你的命令行工具复杂难用，不要试图用长篇大论的文档去解释它。这只是在用文档掩盖工具设计上的缺陷。正确的做法是：编写一个简单的 Bash 包装脚本，提供清晰直观的 API，然后只文档化这个脚本。 保持 CLAUDE.md 的简短，是简化代码库和内部工具的绝佳驱动力。

CLAUDE.md 结构示例

# Monorepo

## Python
- 总是 ...
- 使用 <command> 进行测试
... 另外 10 条规则 ...

## <内部 CLI 工具>
... 10 个要点，聚焦于 80% 的使用场景 ...
- <用法示例>
- 总是 ...
- 绝不 <X>，优先 <Y>

若需了解 <复杂用法> 或处理 <错误>，请参阅 path/to/<tool>_docs.md

...

上下文窗口

建议在编码会话中至少运行一次 /context，以了解你的 200k 令牌上下文窗口是如何被消耗的。

在一个大型单体仓库中，一次新的会话基本消耗可能就高达约 20k 令牌（10%），剩下的 180k 会很快被填满。

你可以将上下文窗口想象成磁盘空间，它会随着你的工作而填满。几分钟或几小时后，你需要清理（紫色部分）来腾出空间。

会话管理

小提醒：
不要信任自动压缩。
使用 /clear 进行简单任务，并利用存储方法为复杂任务创建持久的外部记录。

斜杠命令 (/)

我将斜杠命令视为常用提示词的快捷方式，仅此而已。我的设置非常精简：

• /catchup：让 Claude 读取当前 Git 分支中所有已更改的文件。
• /pr：一个简单的助手，用于清理代码、暂存更改并准备一个拉取请求。

小提醒：
如果你发现自己有一长串复杂的自定义斜杠命令，那你可能过度思考了。
AI 代理的魅力在于自然语言交互，一旦你开始强迫自己和团队去记一堆指令，就违背了初衷。
将斜杠命令用作简单的个人快捷方式，而不是用来替代构建更直观的 CLAUDE.md 和更完善的工具。

子代理

子代理听起来很美：把特定任务（比如跑测试）外包给专门的代理，只返回最终结果，从而保持主上下文的清洁。

然而，在实践中，自定义子代理会带来两个问题：

• 上下文隔离: 创建一个 PythonTests 子代理，会将所有测试相关的上下文从主代理中剥离。主代理无法再对变更进行整体性推理，甚至无法验证自己的代码，除非调用子代理。
• 强制固定工作流: 这迫使 Claude 遵循一个由我们定义的固定工作模式。这限制它必须如何完成任务，而这可能是希望代理帮助我们解决的问题。

Task 方案

我更喜欢使用 Claude 内置的 Task(...) 功能来生成通用代理的副本。

• 将所有关键上下文放入 CLAUDE.md。
• 让主代理自行决定何时以及如何将工作委派给它自己的副本。

这既能享受到子代理节省上下文的好处，又避免了其缺点。代理能够动态地管理自己的任务编排，而不是遵循固定的模式。

会话记录 (--resume)

我经常使用 claude --resume 和 claude --continue 来重启出问题的终端或快速恢复旧会话。

我甚至会恢复几天前的会话，只为让代理总结它是如何解决某个特定错误的，然后用这些信息来优化改进 CLAUDE.md 和内部工具。

更进一步，Claude Code 将所有会话记录存储在 ~/.claude/projects/ 中。可以使用脚本定期对这些原始日志进行元分析，寻找常见的异常、权限请求和错误模式，以帮助优化改进给 AI 的上下文。

钩子 (Hooks)

钩子 (Hooks) 是确定性的“必须做”规则，与 CLAUDE.md 中“应该做”的建议形成互补。在复杂的任务代码库里，这东西至关重要。

两种钩子策略

• 阻止未经确认的提交
  这是我们的主要策略。我们有一个 PreToolUse 钩子，它会拦截任何 git commit 命令。该钩子会检查是否存在一个 /tmp/agent-pre-commit-pass 文件，这个文件只有在我们的测试脚本全部通过时才会被创建。如果文件不存在，钩子会阻止提交，迫使 Claude 进入一个“测试-修复”循环，直到构建变绿。
• 提示型钩子
  这些是简单的、非阻止的钩子，当代理执行次优操作时，提供各种反馈。

小提醒：
不要在“写入时”（比如 Edit 或 Write 操作）阻止。
打断它的思考过程会让它出现不明所以的判断。更好的方式是让它完成整个工作，然后在最后提交时检查结果。

规划模式 (Planning)

对于任何大型功能变更，使用规划模式至关重要。

• 个人项目：
  使用内置的规划模式。它能让我在 Claude 开始工作前与其达成一致，定义如何构建以及在哪些“检查点”需要停下来向我展示工作。
• 专业项目：
  可以做一个基于 Claude Code SDK 构建的自定义规划工具。可以通过大量提示工程，使其输出符合技术设计规范的计划，并默认强制执行内部的最佳实践（从代码结构到数据隐私和安全）。

技能 (Skills)

技能（Skills）可能是比 MCP 更好用。

智能体模型三个阶段：

• 单一提示:
  把所有东西塞进一个巨大的 prompt 里。（很脆弱）
• 工具调用 (Tool Calling):
  为代理制作特定工具，将不同的平台、服务接入。（更好，但同样有瓶颈）。
• 脚本化 (Scripting):
  给 AI 访问真实环境的权限（二进制文件、脚本、文档），让它自己即时编写代码来和环境交互。

Agent Skills
正是“脚本化”阶段的正式产品化。如果你像我一样，倾向于使用 CLI 而非 MCP，那么你其实一直在享受 Skills 带来的好处。
SKILL.md 文件就是一个更规范、可共享的方式来告诉 AI 它能用哪些脚本和 CLI。

MCP

Skills 的出现并不意味着 MCP 已死，而是使其更加聚焦。

与其成为一个包含几十个工具、镜像 REST API 的臃肿接口，MCP 应该是一个简单、安全、提供少数强大高阶工具的网关。比如：

• download_raw_data(filters…)
• take_sensitive_gated_action(args…)
• execute_code_in_environment_with_state(code…)

MCP 的工作会是管理认证、网络和安全边界，然后让开。为代理提供入口点，代理则利用其脚本化能力和上下文来完成实际工作。

SDK 构建自定义代理

Claude Code 不仅仅是一个交互式 CLI，它还是一个强大的 SDK，可用于构建全新的通用代理框架。

主要用法

1. 大规模并行脚本：搞大型重构或迁移时，我会写 bash 脚本并行调用 claude 命令，比让一个代理管理一堆任务高效多了。
2. 构建内部工具：比如做一个安装程序，出错时直接调用 SDK 让 AI 帮用户解决问题。或者做一个内部的“v0”工具，让设计师能用自然语言生成符合我们 UI 框架的前端代码。
3. 快速原型验证：任何代理类的想法，我都会先用 Claude Code SDK 搭个原型，跑通了再考虑上更重的框架。

GitHub Action (GHA)

Claude Code GitHub Action 是最被低估的功能之一。概念很简单：在 GHA 中运行 Claude Code。

它比 Cursor 的后台代理 或 Codex 的托管 Web UI 更具可定制性。你完全控制容器和环境，拥有更强的数据访问权限、沙盒能力和审计控制。

我们可以用它来打造智能 PR 的工具：从 Slack、Jira 或者监控警报触发一个 GHA，让 AI 自动修复 bug 或添加功能，然后提交一个测试通过的 PR。

GHA 的日志就是 AI 的完整工作记录。我们可以定期分析这些日志，以发现常见的错误和不一致的工程实践，然后优化我们的 CLAUDE.md 和 CLI，形成一个数据驱动的飞轮

# 一个概念性命令：查询过去 5 天的 GHA 日志，让另一个 Claude 实例来修复其他 Claude 实例遇到的问题
$ query-claude-gha-logs --since 5d | claude -p “see what the other claudes were getting stuck on and fix it, then put up a PR“

settings.json 配置

最后，分享几个常用的 settings.json 配置：

• HTTPS_PROXY/HTTP_PROXY
  调试神器，通过它可以检查 Claude 发送的原始流量。对于后台代理，这也是一个强大的网络沙盒工具。
• MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS
  我调高了这些值。默认的超时设置对于运行复杂的长命令来说过于保守。
• ANTHROPIC_API_KEY
  在公司，我们用这个来接入企业账户，实现按量计费。这比按席位付费的模式更适合我们，因为它能适应开发者之间巨大的用量差异。
• “permissions”
  定期检查这个列表，看看自己都授权了哪些命令可以被自动执行，确保安全。