原文：Shrivu Shankar - 2025.11.02

我经常使用 Claude Code。

作为一个业余爱好者，我每周都会在虚拟机里跑它好几次，用来做个人项目，还经常用上 --dangerously-skip-permissions 参数，随心所欲地（“vibe code”）实现脑中的任何想法。在专业工作中，我所在的团队负责为我们的工程团队构建 AI-IDE 规则和工具，而我们的工程团队每月仅代码生成（codegen）就要消耗掉数十亿的 token。

CLI 助手（agent）这个领域正变得越来越拥挤，在 Claude Code、Gemini CLI、Cursor 和 Codex CLI 之间，感觉真正的竞赛是在 Anthropic 和 OpenAI 之间展开。但老实说，当我和其他开发者交流时，他们的选择往往取决于一些看起来很表面的东西——某个“幸运的”功能实现，或者是他们就是更喜欢的某种系统提示“氛围”（vibe）。发展到这个阶段，这些工具其实都相当不错了。我还发现，人们也常常过度关注输出的风格或用户界面。比如，对我来说，那种“你说的太对了！”的马屁并不算什么明显的 bug，它只是一个信号，表明你过于“介入”了。总的来说，我的目标是“shoot and forget”——授权、设置好上下文，然后就让它自己工作。评判工具要看最终的 PR，而不是看它如何一步步走到那里的。

在过去几个月里，我一直坚持使用 Claude Code，这篇文章就是对 Claude Code 整个生态系统的一些思考,并且将涵盖我几乎用过的所有功能（同样重要的是，还有那些我不用的功能），从最基础的 CLAUDE.md 文件和自定义斜杠命令，到 Subagents、Hooks 和 GitHub Actions 的强大世界。这篇文章写得有点长，我更推荐你把它当作一篇参考资料，而不是非要一口气读完。

CLAUDE.md

要想高效使用 Claude Code，代码库中最重要的文件莫过于根目录下的 CLAUDE.md。这个文件是这个 agent 的“宪法”，是它了解你特定仓库如何工作的基本事实来源。

如何对待这个文件取决于具体情况。对于我的业余项目，我让 Claude 随便往里面塞东西。

而在我的专业工作中，我们的 monorepo（单一代码库）中的 CLAUDE.md 是受到严格维护的，目前大小为 13KB（我毫不怀疑它会增长到 25KB）。

  • 它只记录那些有 30%（随便定的比例）或更多工程师使用的工具和 API（否则，工具会记录在特定产品或库的 markdown 文件中）。
  • 我们甚至开始为每个内部工具的文档分配一个有效的最大 token 限制，几乎就像在向各个团队出售“广告位”。如果你不能简明扼要地解释你的工具，那它就还没准备好被放进 CLAUDE.md。

提示与常见的否定模式

随着时间推移，我们已经形成了一套强大且主见鲜明的哲学，用于编写高效的 CLAUDE.md。

  1. 从护栏开始，而不是一本手册。 CLAUDE.md 应该从小处着手，根据 Claude 容易出错的地方来补充文档。
  2. 不要 @ 提及（@-File）文档。 如果在别处有详尽的文档，你可能会忍不住在 CLAUDE.md 中 @ 提及那些文件。这会在每次运行时都嵌入整个文件，从而撑爆上下文窗口。但如果你只是提及路径，Claude 往往会忽略它。你必须说服这个助手为什么以及何时去读那个文件。例如：“对于复杂的 … 用法，或者当你遇到 FooBarError 时，请参阅 path/to/docs.md 查看高级故障排除步骤。”
  3. 不要只说“绝不”。 避免使用纯否定的限制，比如“绝不要使用 --foo-bar 标志”。当助手认为它必须使用那个标志时，它就会卡住。要始终提供一个替代方案。
  4. 把 CLAUDE.md 当作一个约束函数。 如果你的 CLI 命令复杂又啰嗦，不要写大段的文档去解释它们。那是在修补一个“人的问题”。相反，你应该写一个简单的 bash 封装脚本，提供清晰、直观的 API，然后去记录那个脚本。保持 CLAUDE.md 尽可能简短，是推动你简化代码库和内部工具的一个极好的约束函数。

下面是一个简化的快照：

# Monorepo

## Python
- Always ...
- Test with <command>
... 10 more ...

## <Internal CLI Tool>
... 10 bullets, focused on the 80% of use cases ...
- <usage example>
- Always ...
- Never <x>, prefer <Y>

For <complex usage> or <error> see path/to/<tool>_docs.md

...

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

核心要点： 把 CLAUDE.md 当作一套高层次、精心策划的护栏和指引。用它来指导你需要在哪些地方投入更多资源来开发对 AI（和人类）更友好的工具，而不是试图把它变成一本无所不包的手册。

精简、上下文与清空

我建议在编码过程中至少运行一次 /context，来了解你那 200k token 的上下文窗口是如何被使用的（即使有 Sonnet-1M，我也不相信完整的上下文窗口能被真正有效地利用）。在我们的 monorepo 中，一个全新的会话基线成本大约是 20k token（10%），剩下的 180k 用于进行你的更改——而这很快就会被填满。

（这是我最近一个个人项目里 /context 的截图。你几乎可以把它想象成磁盘空间，随着你开发一个功能，它会逐渐被填满。几分钟或几小时后，你就需要清除消息（紫色部分）来腾出空间继续工作。）

我有三种主要的工作流：

  • /compact （避免使用）： 我尽可能避免使用这个。自动精简的过程不透明、容易出错，而且优化得不好。
  • /clear + /catchup （简单重启）： 我的默认重启方式。我用 /clear 清除状态，然后运行一个自定义的 /catchup 命令，让 Claude 读取我的 git 分支中所有已更改的文件。
  • “记录并清空”（复杂重启）： 用于大型任务。我让 Claude 把它的计划和进度转储到一个 .md 文件中，然后 /clear 清除状态，接着通过告诉它读取那个 .md 文件并继续工作来开始一个新的会话。

核心要点： 不要相信自动精简。使用 /clear 进行简单重启，使用“记录并清空”方法为复杂任务创建持久的、外部的“记忆”。

自定义斜杠命令

我把斜杠命令看作是常用提示（prompts）的简单快捷方式，仅此而已。我的设置非常精简：

  • /catchup：我前面提到的命令。它只是提示 Claude 读取我当前 git 分支中所有已更改的文件。
  • /pr：一个简单的辅助工具，用来清理我的代码、暂存它们，并准备一个 PR。

恕我直言，如果你有一长串复杂的自定义斜杠命令，你就制造了一个反面模式。对我来说，像 Claude 这样的助手的全部意义在于，你几乎可以输入任何你想说的，并得到一个有用的、可合并的结果。一旦你强迫一个工程师（或非工程师）去学习一堆新的、不知记录在哪里的、必须掌握的魔法命令才能完成工作，你就已经失败了。

核心要点： 把斜杠命令当作简单的个人快捷方式，而不是用它来替代构建一个更直观的 CLAUDE.md 和工具更完善的助手。

自定义 Subagents

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

Subagent 解决方案是把 (X + Y) * N 的工作分包给专门的助手，它们只返回最终的 Z token 答案，从而保持你的主上下文干净整洁。

我发现这是一个很强大的想法，但在实践中，自定义 subagents 会带来两个新问题：

  1. 它们把上下文“关起来”了： 如果我创建了一个 PythonTests subagent，我就把所有关于测试的上下文从我的主助手中隐藏起来了。主助手无法再对一个变更进行全盘的（holistically）思考。它现在被迫要调用那个 subagent 才能知道如何验证它自己的代码。
  2. 它们强加了人类的工作流： 更糟糕的是，它们迫使 Claude 遵循一个僵化的、由人类定义的工作流。我现在是在指定它必须如何授权，而这正是我试图让助手帮我解决的问题。

我更喜欢的替代方案是使用 Claude 内置的 Task(...) 功能来派生通用助手的克隆体。

我把所有关键上下文都放在 CLAUDE.md 里。然后，让主助手自己决定何时以及如何将工作分配给它自己的副本。这让我既享受了 subagents 节省上下文的好处，又避免了它们的缺点。助手可以动态地管理它自己的协作。

核心要点： 自定义 subagents 是一个脆弱的解决方案。把上下文（放在 CLAUDE.md 里）交给你的主助手，让它使用自己的 Task/Explore(...) 功能来管理任务分配。

恢复、继续与历史记录

在简单的层面上，我经常使用 claude --resume 和 claude --continue。它们对于重启一个出了 bug 的终端或快速重启一个旧会话非常有用。我经常 claude --resume 一个几天前的会话，只是为了问问助手它是如何克服某个特定错误的，然后再用这些信息来改进我们的 CLAUDE.md 和内部工具。

更深入一点，Claude Code 会把所有会话历史存储在 ~/.claude/projects/ 中，以便利用原始的历史会话数据。我有一些脚本会对这些日志运行元分析（meta-analysis），寻找常见的异常、权限请求和错误模式，以帮助改进面向助手的上下文。

核心要点： 使用 claude --resume 和 claude --continue 来重启会话，并发掘埋藏在历史记录中的上下文。

Hooks

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

我们使用两种类型：

  1. 提交时阻断（Block-at-Submit） Hooks： 这是我们的主要策略。我们有一个 PreToolUse 钩子，它会封装任何 Bash(git commit) 命令。它会检查是否存在一个 /tmp/agent-pre-commit-pass 文件，而我们的测试脚本只有在所有测试都通过时才会创建这个文件。如果文件不存在，钩子就会阻止提交，迫使 Claude 进入一个“测试并修复”的循环，直到构建通过。
  2. 提示（Hint）Hooks： 这些是简单的、非阻断的钩子，如果助手在做一些不够理想的事情，它们会提供 “fire-and-forget” 的反馈。

我们刻意不使用“写入时阻断”（block-at-write）的钩子（例如，在 Edit 或 Write 上）。在助手执行计划的中途阻断它，会使它感到困惑甚至“沮丧”。更有效的方法是让它完成它的工作，然后在提交阶段检查最终完成的结果。

核心要点： 使用钩子在提交时强制执行状态验证。避免在写入时进行阻断——让助手完成它的计划，然后再检查最终结果。

规划模式

对于使用 AI IDE 进行任何“大型”功能变更来说，规划都是必不可少的。

对于我的业余项目，我只使用内置的规划模式。这是一种在 Claude 开始工作前与它达成一致的方式，既定义了如何构建某样东西，也定义了它需要停下来向我展示其工作的“检查点”。经常使用这个功能可以培养一种强大的直觉，即需要什么样的最小化上下文才能得出一个好的计划，而又不会让 Claude 在实施过程中搞砸。

在我们的工作 monorepo 中，我们已经开始推广一个基于 Claude Code SDK 构建的自定义规划工具。它与原生的规划模式类似，但经过了大量的提示（prompted），使其输出与我们现有的技术设计格式保持一致。它还能开箱即用地强制执行我们的内部最佳实践——从代码结构到数据隐私和安全。这让我们的工程师可以像资深架构师一样“随想随规划”（vibe plan）一个新功能（至少我们的宣传是这么说的）。

核心要点： 对于复杂的变更，一定要使用内置的规划模式，在助手开始工作前先就计划达成一致。

Skills

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

如果你一直关注我的文章，就会知道对于大多数开发工作流，我已经逐渐放弃了 MCP，转而选择构建简单的 CLI（正如我在 “AI 无法阅读你的文档” 中所论述的）。我对助手自主性的心智模型已经演化为三个阶段：

  1. 单一提示（Single Prompt）： 在一个巨大的提示中给助手提供所有上下文。（脆弱，无法扩展）。
  2. 工具调用（Tool Calling）： “经典”的助手模型。我们手工制作工具，为助手抽象出现实世界。（更好，但创造了新的抽象和上下文瓶颈）。
  3. 脚本化（Scripting）： 我们给予助手访问原始环境的权限——二进制文件、脚本和文档——它会即时编写代码来与它们交互。

带着这个模型来看，Agent Skills 显然是下一个合乎逻辑的功能。它们是“脚本化”这一层的正式产品化形态。

如果你像我一样，已经开始倾向于使用 CLI 而不是 MCP，那么你其实一直在不知不觉中享受着 Skills 带来的好处。SKILL.md 文件只是一种更组织化、可共享、可发现的方式，用来记录这些 CLI 和脚本，并将它们暴露给助手。

核心要点： Skills 是正确的抽象。它们将基于“脚本化”的助手模型正式化，这种模型比 MCP 所代表的僵化的、类似 API 的模型更加健壮和灵活。

MCP (Model Context Protocol)

Skills 并不意味着 MCP 已死（另见 “MCP 的所有问题”）。以前，许多人构建了糟糕的、上下文重的 MCP，包含了数十个只是镜像了 REST API 的工具（read_thing_a()、read_thing_b()、update_thing_c()）。

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

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

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

在这个模型中，MCP 的工作不是为助手抽象现实；它的工作是管理认证、网络和安全边界，然后“闪到一边”。它为助手提供了入口点（entry point），然后助手利用它的脚本能力和 markdown 上下文来完成实际工作。

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

核心要点： 使用那些充当数据网关的 MCP。给助手一两个高层次的工具（比如一个原始数据转储 API），然后让它基于这些工具编写脚本。

Claude Code SDK

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

我主要有三种使用方式：

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

核心要点： Claude Code SDK 是一个强大的、通用的助手框架。在转向更复杂的框架之前，用它来批量处理代码、构建内部工具以及快速设计新助手的原型。

Claude Code GHA

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

它类似于 Cursor 的后台助手或 Codex 管理的 Web UI，但可定制性要强得多。你可以控制整个容器和环境，这让你能访问更多数据，并且至关重要的是，它提供了比任何其他产品都更强的沙盒和审计控制。此外，它还支持像 Hooks 和 MCP 这样的所有高级功能。

我们已经用它来构建自定义的 “PR-from-anywhere” 工具。用户可以从 Slack、Jira，甚至 CloudWatch 警报触发一个 PR，GHA 将修复 bug 或添加功能，并返回一个经过全面测试的 PR。

由于 GHA 日志就是完整的助手日志，我们有一个运维流程，会定期在公司层面审查这些日志，寻找常见的错误、bash 错误或未对齐的工程实践。这就创造了一个数据驱动的飞轮：Bugs -> 改进 CLAUDE.md / CLIs -> 更好的助手。

$ 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 到底在发送什么提示。对于后台助手来说，它也是一个用于细粒度网络沙盒的强大工具。
  • MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS：我把这些值调高了。我喜欢运行冗长、复杂的命令，默认的超时时间往往过于保守。老实说，我不确定现在 bash 后台任务功能出来了，这个设置是否还有必要，但以防万一我保留了它。
  • ANTHROPIC_API_KEY：在工作中，我们使用我们的企业 API 密钥（通过 apiKeyHelper）。这将我们从“按席位”许可转变为“按使用量”计费，这对我们的工作方式来说是一个好得多的模型。
    • 它解决了开发者使用量巨大差异的问题（我们观察到工程师之间的差异有 1:100 倍）。
    • 它让工程师可以在我们统一的企业账户下，去鼓捣那些非 Claude-Code 的 LLM 脚本。
  • “permissions”：我偶尔会自我审计一下允许 Claude 自动运行的命令列表。

核心要点： settings.json 是一个用于高级定制的强大工具。

结论

内容很多，但希望你觉得有用。如果你还没有在使用像 Claude Code 或 Codex CLI 这样基于 CLI 的助手，你或许应该开始用了。这些高级功能很少有好的指南，所以唯一的学习方法就是一头扎进去。