我如何使用每一个 Claude Code 功能

关于我使用 Claude Code 各种方式的全面总结。

我经常使用 Claude Code。

作为业余爱好者，我每周在虚拟机中运行好几次，用于个人项目，经常使用 --dangerously-skip-permissions 来随性编码我脑海中想到的任何想法。在工作中，我团队的一部分为我们工程团队构建 AI-IDE 规则和工具，每月消耗数十亿个 token 仅用于代码生成。

CLI agent 领域变得越来越拥挤，在 Claude Code、Gemini CLI、Cursor 和 Codex CLI 之间，我觉得真正的比赛是在 Anthropic 和 OpenAI 之间。但说实话，当我和其他开发者交谈时，他们的选择往往归结为看起来很表面的东西------一个"幸运"的功能实现或者他们偏好的系统提示"风格"。在这一点上，这些工具都相当不错。我也觉得人们往往过度关注输出风格或 UI。对我来说，"你完全正确！"的谄媚不是一个值得注意的 bug；这是一个信号，说明你参与得太多了。一般来说，我的目标是"发射后忘记"------委托、设置上下文，然后让它工作。通过最终的 PR 而不是过程来评判工具。

坚持使用 Claude Code 几个月后，这篇文章是我对 Claude Code 整个生态系统的反思。我们将涵盖我使用的几乎每个功能（同样重要的是，我没有使用的功能），从基础的 CLAUDE.md 文件和自定义斜杠命令，到强大的 Subagents、Hooks 和 GitHub Actions 世界。这篇文章有点长，我建议将其作为参考而不是完整阅读的内容。

CLAUDE.md

在你的代码库中有效使用 Claude Code 最重要文件是根目录下的 CLAUDE.md。这个文件是 agent 的"宪法"，是了解你的特定存储库如何工作的主要真实来源。

你如何处理这个文件取决于上下文。对于我的业余项目，我让 Claude 在其中倾倒任何它想要的东西。

在我的专业工作中，我们的单体仓库的 CLAUDE.md 是严格维护的，目前有 13KB（我很容易看到它增长到 25KB）。

它只记录 30%（任意）或更多工程师使用的工具和 API（其他工具在产品或库特定的 markdown 文件中记录）
我们甚至开始为每个内部工具的文档有效分配最大 token 计数，就像向团队出售"广告空间"一样。如果你不能简洁地解释你的工具，它就不适合放在 CLAUDE.md 中。

提示和常见反模式

随着时间的推移，我们为编写有效的 CLAUDE.md 发展了强烈、有观点的哲学。

从护栏开始，而不是手册。 你的 CLAUDE.md 应该从小开始，基于 Claude 出错的地方进行记录。
不要 @-文件文档。 如果你在别处有大量文档，在你的 CLAUDE.md 中 @-提及这些文件很诱人。这会在每次运行时通过嵌入整个文件来膨胀上下文窗口。但如果你只是提及路径，Claude 经常会忽略它。你必须向 agent 推销为什么要以及何时读取文件。"对于复杂......使用或遇到 FooBarError 时，请参阅 path/to/docs.md 以获取高级故障排除步骤。"
不要只说"永远不要"。 避免像"永远不要使用 --foo-bar 标志"这样的仅否定约束。当 agent 认为它必须使用该标志时，它会卡住。始终提供替代方案。
使用 CLAUDE.md 作为强制函数。 如果你的 CLI 命令复杂冗长，不要写段落文档来解释它们。那是修补人的问题。相反，编写一个具有清晰、直观 API 的简单 bash 包装器并记录它。保持 CLAUDE.md 尽可能简短是简化代码库和内部工具的极好强制函数。

这是一个简化的快照：

markdown 复制代码

# 单体仓库

## Python
- 始终 ...
- 使用 <command> 测试
... 另外 10 个 ...

## <内部 CLI 工具>
... 10 个项目，专注于 80% 的用例 ...
- <使用示例>
- 始终 ...
- 永远不要 <x>，偏好 <Y>

对于 <复杂使用> 或 <错误>，请参阅 path/to/<tool>_docs.md

...

最后，我们保持这个文件与 AGENTS.md 文件同步，以保持与我们工程师可能使用的其他 AI IDE 的兼容性。

如果你正在寻找为编码 agents 编写 markdown 的更多提示，请参阅"AI Can't Read Your Docs"、"AI-powered Software Engineering"和"How Cursor (AI IDE) Works"。

要点： 将你的 CLAUDE.md 视为高级、精选的护栏和指针集合。用它来指导你需要在哪里投资更多 AI（和人类）友好的工具，而不是试图使其成为全面的手册。

Compact, Context, & Clear

我建议在编码会话中途至少运行一次 /context 来了解你如何使用你的 200k token 上下文窗口（即使使用 Sonnet-1M，我也不相信完整上下文窗口被有效使用）。对我们来说，在单体仓库中的新会话基准成本约为 ~20k token（10%），剩余 180k 用于进行更改------这可能会很快填满。

我有三个主要工作流程：

/compact（避免）： 我尽可能避免使用这个。自动压缩是不透明的、容易出错的，并且没有很好地优化。
/clear + /catchup（简单重启）： 我的默认重启方式。我 /clear 状态，然后运行自定义的 /catchup 命令让 Claude 读取我 git 分支中所有更改的文件。
"Document & Clear"（复杂重启）： 对于大型任务。我让 Claude 将其计划和进度转储到 .md 文件中，/clear 状态，然后通过告诉它读取 .md 文件并继续来开始新会话。

要点： 不要相信自动压缩。使用 /clear 进行简单重启，使用"Document & Clear"方法为复杂任务创建持久的外部"记忆"。

Custom Slash Commands

我认为斜杠命令只是频繁使用的提示的简单快捷方式，仅此而已。我的设置是最小化的：

/catchup：我之前提到的命令。它只是提示 Claude 读取我当前 git 分支中所有更改的文件。
/pr：一个简单的助手，清理我的代码、暂存它并准备 pull request。

恕我直言，如果你有一长串复杂的自定义斜杠命令，你就创建了一个反模式。对我来说，像 Claude 这样的 agent 的全部意义在于你可以输入几乎任何你想要的东西并获得有用的、可合并的结果。当你强迫工程师（或非工程师）学习一套新的、在某处记录的基本魔法命令来完成工作时，你就失败了。

要点： 使用斜杠命令作为简单的个人快捷方式，而不是作为构建更直观的 CLAUDE.md 和更好工具的 agent 的替代品。

Custom Subagents

在理论上，自定义 subagents 是 Claude Code 最强大的上下文管理功能。推销很简单：一个复杂任务需要 X 个 token 的输入上下文（例如，如何运行测试），累积 Y 个 token 的工作上下文，并产生 Z 个 token 的答案。运行 N 个任务意味着在你的主窗口中有 (X + Y + Z) * N 个 token。

subagent 解决方案是将 (X + Y) * N 工作外包给专门的 agents，它们只返回最终的 Z token 答案，保持主上下文干净。

我发现它们是一个强大的想法，但在实践中，自定义 subagents 会产生两个新问题：

它们封锁上下文： 如果我制作一个 PythonTests subagent，我现在已经从我的主 agent 中隐藏了所有测试上下文。它不再能对更改进行整体推理。它现在被迫调用 subagent 只是为了知道如何验证自己的代码。
它们强制人类工作流程： 更糟糕的是，它们强迫 Claude 进入僵硬的、人类定义的工作流程。我现在在规定它必须如何委托，这正是我试图让 agent 为我解决的问题。

我偏好的替代方案是使用 Claude 内置的 Task(...) 功能来生成通用 agent 的副本。

我将所有关键上下文放在 CLAUDE.md 中。然后，我让主 agent 决定何时以及如何将工作委托给自身的副本。这给了我所有 subagents 的上下文节省好处，而没有缺点。agent 动态管理自己的编排。

在我的"Building Multi-Agent Systems (Part 2)"文章中，我称之为"Master-Clone"架构，我强烈偏好它而不是自定义 subagents 鼓励的"Lead-Specialist"模型。

要点： 自定义 subagents 是一个脆弱的解决方案。给你的主 agent 上下文（在 CLAUDE.md 中）并让它使用自己的 Task/Explore(...) 功能来管理委托。

Resume, Continue, & History

在简单层面上，我经常使用 claude --resume 和 claude --continue。它们非常适合重启出错的终端或快速重启旧会话。我经常 claude --resume 几天前的会话，只是询问 agent 总结它如何克服特定错误，然后我用它来改进我们的 CLAUDE.md 和内部工具。

更深入地说，Claude Code 将所有会话历史存储在 ~/.claude/projects/ 中，以挖掘原始历史会话数据。我有脚本对这些日志运行元分析，寻找常见异常、权限请求和错误模式，以帮助改进面向 agent 的上下文。

要点： 使用 claude --resume 和 claude --continue 重启会话并发现被埋藏的历史上下文。

Hooks

Hooks 很重要。我不在业余项目中使用它们，但它们对于在复杂企业仓库中引导 Claude 至关重要。它们是确定性的"必须做"规则，补充 CLAUDE.md 中的"应该做"建议。

我们使用两种类型：

提交时阻止 Hooks： 这是我们的主要策略。我们有一个 PreToolUse hook 包装任何 Bash(git commit) 命令。它检查 /tmp/agent-pre-commit-pass 文件，我们的测试脚本只有在所有测试通过时才会创建该文件。如果文件缺失，hook 会阻止提交，迫使 Claude 进入"测试并修复"循环，直到构建变为绿色。
提示 Hooks： 这些是简单的、非阻塞的 hooks，如果 agent 正在做次优的事情，会提供"即发即忘"的反馈。

我们有意不使用"写入时阻止" hooks（例如，在 Edit 或 Write 上）。在计划中途阻止 agent 会混淆甚至"挫败"它。让它完成工作然后在提交阶段检查最终的、完成的结果要有效得多。

要点： 使用 hooks 在提交时强制状态验证（block-at-submit）。避免在写入时阻止------让 agent 完成计划，然后检查最终结果。

Planning Mode

对于任何"大型"功能更改，使用 AI IDE 进行规划是必不可少的。

对于我的业余项目，我只使用内置的规划模式。这是在 Claude 开始之前与之对齐的一种方式，定义了如何构建某物以及它需要停止并展示工作的"检查点"。定期使用这个可以建立强烈的直觉，了解获得良好计划而不让 Claude 搞砸实现所需的最小上下文。

在我们的工作单体仓库中，我们开始推出基于 Claude Code SDK 构建的自定义规划工具。它类似于原生计划模式，但经过大量提示以使其输出与我们现有的技术设计格式对齐。它还开箱即用地强制执行我们的内部最佳实践------从代码结构到数据隐私和安全。这让我们的工程师能够" vibe plan"一个新功能，就像他们是高级架构师一样（至少这是推销的说法）。

要点： 对于复杂更改，始终使用内置规划模式在 agent 开始工作之前对齐计划。

Skills

我同意 Simon Willison 的观点：Skills 可能比 MCP 更重要。

如果你一直在关注我的文章，你会知道我已经偏离了 MCP 进行大多数开发工作，偏好构建简单的 CLI（正如我在"AI Can't Read Your Docs"中争论的那样）。我的 agent 自治心智模型已经演变为三个阶段：

单一提示： 在一个巨大的提示中给 agent 所有上下文。（脆弱，不可扩展）
工具调用： "经典" agent 模型。我们手工制作工具并为 agent 抽象现实。（更好，但创建了新的抽象和上下文瓶颈）
脚本编写： 我们给 agent 访问原始环境------二进制文件、脚本和文档------它动态编写代码来与它们交互。

考虑到这个模型，Agent Skills 是明显的下一个功能。它们是"脚本编写"层的正式产品化。

如果你像我一样，已经偏好 CLI 而不是 MCP，你一直在隐含地获得 Skills 的好处。SKILL.md 文件只是一种更有组织、可共享和可发现的方式来记录这些 CLI 和脚本并将它们暴露给 agent。

要点： Skills 是正确的抽象。它们正式化了基于"脚本编写"的 agent 模型，这比 MCP 代表的僵硬、类似 API 的模型更健壮和灵活。

MCP (Model Context Protocol)

Skills 不意味着 MCP 已死（另见"Everything Wrong with MCP"）。以前，许多人构建了糟糕的、上下文繁重的 MCP，有几十个只是镜像 REST API 的工具（read_thing_a()、read_thing_b()、update_thing_c()）。

"脚本编写"模型（现在由 Skills 正式化）更好，但它需要一种安全的方式来访问环境。对我来说，这是 MCP 新的、更集中的角色。

而不是臃肿的 API，MCP 应该是一个简单的、安全的网关，提供几个强大的、高级工具：

download_raw_data(filters...)
take_sensitive_gated_action(args...)
execute_code_in_environment_with_state(code...)

在这个模型中，MCP 的工作不是为 agent 抽象现实；它的工作是管理认证、网络和安全边界，然后让路。它为 agent 提供入口点，然后 agent 使用其脚本编写和 markdown 上下文来完成实际工作。

我仍然使用的唯一 MCP 是用于 Playwright，这很合理------它是一个复杂的、有状态的环境。我所有的无状态工具（如 Jira、AWS、GitHub）都已迁移到简单的 CLI。

要点： 使用充当数据网关的 MCP。给 agent 一两个高级工具（如原始数据转储 API），然后它可以编写脚本来对抗。

Claude Code SDK

Claude Code 不仅仅是一个交互式 CLI；它也是一个强大的 SDK，用于构建全新的 agents------既用于编码任务也用于非编码任务。我已经开始将它作为我默认的 agent 框架，而不是像 LangChain/CrewAI 这样的工具，用于大多数新的业余项目。

我以三种主要方式使用它：

大规模并行脚本编写： 对于大规模重构、错误修复或迁移，我不使用交互式聊天。我编写简单的 bash 脚本并行调用 claude -p "in /pathA change all refs from foo to bar"。这比试图让主 agent 管理几十个 subagent 任务更具可扩展性和可控性。
构建内部聊天工具： SDK 非常适合将复杂过程包装在简单的聊天界面中，供非技术用户使用。比如一个安装程序，在出错时回退到 Claude Code SDK 来为用户修复问题。或者一个内部的"v0-at-home"工具，让我们的设计团队在我们内部的 UI 框架中 vibe-code 模拟前端，确保他们的想法是高保真的，并且代码更直接可用在前端生产代码中。
快速 Agent 原型制作： 这是我最常见的用法。它不仅用于编码。如果我对任何 agent 任务有想法（例如，使用自定义 CLI 或 MCP 的"威胁调查 agent"），我使用 Claude Code SDK 在投入完整的、部署的脚手架之前快速构建和测试原型。

要点： Claude Code SDK 是一个强大的、通用的 agent 框架。用它来批处理代码、构建内部工具，以及在采用更复杂的框架之前快速原型化新的 agents。

Claude Code GHA

Claude Code GitHub Action (GHA) 可能是我最喜欢和最被低估的功能之一。这是一个简单的概念：只是在 GHA 中运行 Claude Code。但正是这种简单性使其如此强大。

它类似于 Cursor 的后台 agents 或 Codex 托管的 web UI，但可定制性更强。你控制整个容器和环境，给你更多的数据访问权限，关键是，比任何其他产品提供更强的沙盒和审计控制。此外，它支持所有高级功能，如 Hooks 和 MCP。

我们用它来构建自定义的"从任何地方创建 PR"工具。用户可以从 Slack、Jira 甚至 CloudWatch 警报触发 PR，GHA 将修复错误或添加功能并返回一个完全测试的 PR¹。

由于 GHA 日志是完整的 agent 日志，我们有一个操作流程，在公司层面定期审查这些日志，寻找常见错误、bash 错误或不对齐的工程实践。这创建了一个数据驱动的飞轮：Bugs → 改进的 CLAUDE.md / CLIs → 更好的 Agent。

bash 复制代码

$ 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"

要点： GHA 是操作化 Claude Code 的终极方式。它将它从个人工具转变为工程系统的核心、可审计和自我改进的部分。

settings.json

最后，我发现对于业余和专业工作，有几个特定的 settings.json 配置至关重要。

HTTPS_PROXY/HTTP_PROXY：这对于调试很棒。我用它来检查原始流量，看看 Claude 正在发送什么提示。对于后台 agents，它也是细粒度网络沙盒的强大工具。
MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS：我提高了这些。我喜欢运行长而复杂的命令，默认超时通常过于保守。老实说，既然 bash 后台任务已经存在，我不确定这是否仍然需要，但我保留它以防万一。
ANTHROPIC_API_KEY：在工作中，我们使用企业 API 密钥（通过 apiKeyHelper）。它将我们从"按座位"许可模式转变为"基于使用"定价，这对我们的工作方式来说是更好的模型。
- 它考虑了开发者使用的巨大差异（我们看到工程师之间有 1:100x 的差异）。
- 它让工程师可以在我们的单一企业账户下尝试非 Claude Code LLM 脚本。
"permissions"：我偶尔会自我审计我允许 Claude 自动运行的命令列表。

要点： 你的 settings.json 是高级自定义的强大地方。

Conclusion

内容很多，但希望你觉得有用。如果你还没有使用基于 CLI 的 agent，如 Claude Code 或 Codex CLI，你可能应该开始使用。关于这些高级功能很少有好的指南，所以学习的唯一方法是投入其中。

¹对我来说，一个相当有趣的哲学问题是，一个直接从客户请求（没有内部人类提示者）生成的 PR 应该有多少审查者？我们现在暂时对任何 AI 发起的 PR 采用 2 个人类批准，但当不再是人为另一个人类制作东西供其审查时，这有点奇怪的模式转变（至少对我来说是这样）。