Skip to main content

企业级Claude Code使用指南

翻译自 Shrivu Shankar 的 "How I Use Every Claude Code Feature"，原作者每月消耗数十亿tokens

Enterprise Development

译者说明

作者既是个人开发者，也在企业团队负责 AI-IDE 工具建设。这种双重视角让他的经验特别有参考价值——哪些功能适合个人用、哪些适合团队用，他都说得很清楚。

这篇文章最有价值的几个点：

  • 反模式警告：明确指出哪些功能是过度设计
  • CLAUDE.md 哲学："从护栏开始，而不是手册"
  • Scripting 模式：给 AI 原始环境访问权，而不是抽象化的工具
  • 企业级实践：GitHub Actions 自动化、日志分析、持续优化的飞轮

我用 Claude Code。用得很多。

作为爱好者，我每周会在虚拟机中运行它好几次来做副项目，经常使用 --dangerously-skip-permissions 来快速实现脑海中的任何想法。在工作中，我所在团队的部分职责是为工程团队构建 AI-IDE 规则和工具，我们每月仅在代码生成上就消耗数十亿 tokens。

CLI agent 领域正变得越来越拥挤，在 Claude Code、Gemini CLI、Cursor 和 Codex CLI 之间，真正的竞争似乎是在 Anthropic 和 OpenAI 之间展开。但说实话，当我和其他开发者交流时，他们的选择往往归结于一些看似表面的东西——某个"幸运"的功能实现，或者他们就是更喜欢某个系统提示词的"氛围"。目前这些工具都相当不错。我也觉得人们经常过度关注输出风格或 UI。对我来说，那种"你说得完全对！"的谄媚并不是一个值得注意的 bug；它是一个信号，说明你过度参与了。总的来说，我的目标是"发射后不管"——委托任务、设置上下文，然后让它自己工作。我通过最终的 PR 来评判工具，而不是它如何完成的过程。

在过去几个月坚持使用 Claude Code 后，这篇文章是我对 Claude Code 整个生态系统的反思总结。我们将涵盖我使用的几乎每个功能（同样重要的是，我不使用的功能），从基础的 CLAUDE.md 文件和自定义 slash 命令，到强大的 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 的哲学。

从护栏开始，而不是手册。你的 CLAUDE.md 应该从小处开始，根据 Claude 做错的地方来编写文档。

不要 @-引用文档文件。如果你在别处有大量文档，你可能会想在 CLAUDE.md 中 @-提及这些文件。这会通过在每次运行时嵌入整个文件来使上下文窗口膨胀。但如果你只是提到路径，Claude 通常会忽略它。你必须向 agent 推销为什么以及何时阅读该文件。"对于复杂的...使用或如果遇到 FooBarError，请参阅 path/to/docs.md 了解高级故障排除步骤。"

不要只说"绝不"。避免纯负面约束，如"绝不使用 --foo-bar 标志"。当 agent 认为它必须使用该标志时，它会卡住。始终提供替代方案。

将 CLAUDE.md 用作强制函数。如果你的 CLI 命令复杂且冗长，不要写几段文档来解释它们。那是在修补一个人类问题。相反，编写一个简单的 bash 包装器，提供清晰、直观的 API，并记录它。尽可能保持 CLAUDE.md 简短是简化代码库和内部工具的绝佳强制函数。

这是一个简化的快照：

# Monorepo

## Python
- 总是...
- 用 <command> 测试
... 还有 10 条...

## <内部 CLI 工具>
... 10 条要点，专注于 80% 的用例...
- <使用示例>
- 总是...
- 绝不 <x>，优先 <Y>

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

...

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

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

要点：将你的 CLAUDE.md 视为一组高层次、精心策划的护栏和指针。用它来指导你需要在哪里投资更 AI（和人类）友好的工具，而不是试图让它成为一本综合手册。

紧凑、上下文和清晰​

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

我最近一个副项目中 /context 的截图。你几乎可以把这看作是磁盘空间，在你处理功能时会填满。几分钟或几小时后，你需要清除消息（紫色）以腾出空间继续。

我有三个主要工作流程：

  1. /compact（避免）：我尽可能避免使用这个。自动压缩是不透明的、容易出错的，而且优化得不好。

  2. /clear + /catchup（简单重启）：我的默认重启方式。我 /clear 状态，然后运行自定义的 /catchup 命令，让 Claude 读取我 git 分支中所有更改的文件。

  3. "文档化并清除"（复杂重启）：用于大型任务。我让 Claude 将其计划和进度转储到一个 .md 文件中，/clear 状态，然后通过告诉它读取 .md 并继续来启动新会话。

要点：不要信任自动压缩。对简单重启使用 /clear，对复杂任务使用"文档化并清除"方法来创建持久的外部"记忆"。

自定义 Slash 命令​

我认为 slash 命令只是常用提示词的简单快捷方式，仅此而已。我的设置很简单：

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

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

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

自定义 Subagents​

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

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

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

  1. 它们把守上下文：如果我创建一个 PythonTests subagent，我现在已经对主 agent 隐藏了所有测试上下文。它不再能够整体推理一个更改。现在它被迫调用 subagent 只是为了知道如何验证自己的代码。

  2. 它们强制人类工作流程：更糟的是，它们强制 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 中的"应该做"建议。

我们使用两种类型：

  1. 提交时阻止 Hooks：这是我们的主要策略。我们有一个 PreToolUse hook，它包装任何 Bash(git commit) 命令。它检查 /tmp/agent-pre-commit-pass 文件，只有当所有测试通过时，我们的测试脚本才会创建该文件。如果文件缺失，hook 会阻止提交，强制 Claude 进入"测试和修复"循环，直到构建成功。

  2. 提示 Hooks：这些是简单的、非阻塞性的 hooks，如果 agent 正在做一些次优的事情，会提供"一次性"反馈。

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

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

计划模式​

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

对于我的爱好项目，我专门使用内置的计划模式。这是在 Claude 开始之前与它对齐的一种方式，定义如何构建某些东西以及它需要停下来向我展示其工作的"检查点"。定期使用这个功能可以建立一个强大的直觉，了解获得一个好计划所需的最少上下文是什么，而不会让 Claude 搞砸实施。

在我们的工作 monorepo 中，我们已经开始推出基于 Claude Code SDK 构建的自定义计划工具。它类似于原生计划模式，但经过大量提示，以将其输出与我们现有的技术设计格式对齐。它还强制执行我们内部的最佳实践——从代码结构到数据隐私和安全——开箱即用。这让我们的工程师可以像高级架构师一样"快速规划"一个新功能（或者至少这是宣传）。

要点：对于复杂的更改，始终使用内置的计划模式，以便在 agent 开始工作之前就计划达成一致。

Skills​

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

如果你一直在关注我的帖子，你会知道我已经在大多数开发工作流程中远离了 MCP，更倾向于构建简单的 CLI（正如我在"AI Can't Read Your Docs"中所论证的）。我对 agent 自主性的心智模型已经演变为三个阶段：

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

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

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

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

MCP（模型上下文协议）​

Skills 并不意味着 MCP 已经死了（另见"Everything Wrong with 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 的工作不是为 agent 抽象现实；它的工作是管理身份验证、网络和安全边界，然后让开。它为 agent 提供入口点，然后 agent 使用其脚本编写和 markdown 上下文来完成实际工作。

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

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

Claude Code SDK​

Claude Code 不仅仅是一个交互式 CLI；它也是一个强大的 SDK，用于构建全新的 agents——无论是编码还是非编码任务。我已经开始将它用作大多数新爱好项目的默认 agent 框架，而不是 LangChain/CrewAI 等工具。

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

  1. 大规模并行脚本编写：对于大规模重构、bug 修复或迁移，我不使用交互式聊天。我编写简单的 bash 脚本，并行调用 claude -p "in /pathA change all refs from foo to bar"。这比试图让主 agent 管理数十个 subagent 任务更具可扩展性和可控性。

  2. 构建内部聊天工具：SDK 非常适合为非技术用户将复杂流程包装在简单的聊天界面中。比如一个安装程序，在出错时，回退到 Claude Code SDK 只是为用户修复问题。或者一个内部的"v0-at-home"工具，让我们的设计团队在我们的内部 UI 框架中快速编写模拟前端，确保他们的想法是高保真的，代码在前端生产代码中更直接可用。

  3. 快速 Agent 原型设计：这是我最常见的用途。它不仅仅用于编码。如果我对任何 agentic 任务有想法（例如，使用自定义 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 将修复 bug 或添加功能并返回一个经过充分测试的 PR。

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

$ query-claude-gha-logs --since 5d | claude -p "看看其他 claudes 在哪里卡住了并修复它，然后提交 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:100 倍的差异）。
    • 它让工程师可以使用非 Claude-Code LLM 脚本进行修补，所有这些都在我们的单一企业账户下。

  • "permissions"：我会偶尔自我审计我允许 Claude 自动运行的命令列表。

要点：你的 settings.json 是进行高级定制的强大场所。

结论​

内容很多，但希望对你有用。如果你还没有使用像 Claude Code 或 Codex CLI 这样的基于 CLI 的 agent，你可能应该使用。这些高级功能很少有好的指南，所以学习的唯一方法就是深入研究。

原文信息
  • 原文作者: Shrivu Shankar
  • 原文标题: How I Use Every Claude Code Feature
  • 发布时间: 2025年11月