本文翻译自 Shrivu Shankar 的博客文章《How I Use Every Claude Code Feature》
原文链接：https://blog.sshh.io/p/how-i-use-every-claude-code-feature

前言

作为一名 AI 开发工具的重度用户，我每周都会在个人项目中多次使用 Claude Code，工作中更是参与了每月消耗数十亿 token 的 AI 工具平台建设。

在 CLI 代理工具领域，Claude Code、Gemini CLI、Cursor 和 Codex CLI 之间的竞争日趋激烈。但在与众多开发者交流后，我发现大家的选择往往取决于某个"幸运"的功能实现或系统提示词的"风格偏好"，而非深层次的技术差异。

经过几个月的深度使用，我决定分享 Claude Code 整个生态系统的使用心得。本文将涵盖几乎所有我使用的功能（以及我不使用的），从基础的 CLAUDE.md 文件和自定义斜杠命令，到强大的子代理、Hooks 和 GitHub Actions。

提示：本文篇幅较长，建议作为参考手册使用，而非一次性读完。

---

一、CLAUDE.md：项目的"宪法"

CLAUDE.md 是有效使用 Claude Code 的最重要文件，它是代理的"宪法"，是理解你的特定仓库如何工作的主要依据。

使用场景

个人项目：我允许 Claude 在其中随意写入任何内容。

专业项目：我们的 monorepo 中的 CLAUDE.md 受到严格维护，目前大小为 13KB（我预计它会增长到 25KB）。

维护策略

• 只记录 30%（或以上）工程师使用的工具和 API（其他工具在特定产品或库的 markdown 文件中记录）
• 为每个内部工具的文档分配有效的最大 token 数，就像出售"广告位"一样。如果你无法简洁地解释你的工具，那它就不适合放入 CLAUDE.md

编写哲学

经过长期实践，我们总结出了一套强有力的编写原则：

1. 从护栏开始，而非手册
你的 CLAUDE.md 应该从小处着手，基于 Claude 犯的错误来记录。

2. 不要 @ 引用文档
如果其他地方有大量文档，很容易想在 CLAUDE.md 中 @ 提及这些文件。这会在每次运行时嵌入整个文件，膨胀上下文窗口。但如果你只是提及路径，Claude 往往会忽略它。你必须向代理推销为什么以及何时读取该文件：

“对于复杂的…用法或遇到 FooBarError 时，请参阅 path/to/docs.md 了解高级故障排除步骤。”

3. 不要只说"绝不避免"
避免仅使用否定性约束，如"绝不使用 --foo-bar 标志"。当代理认为它必须使用该标志时，它会陷入困境。始终提供替代方案。

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

简化示例

# Monorepo

## Python
- 始终 ...
- 使用 <command> 测试
... 10 条更多 ...

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

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

...

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

---

二、上下文管理：context 命令

建议在编码会话中至少运行一次 /context，以了解你如何使用 200k token 上下文窗口（即使使用 Sonnet-1M，我也不相信完整的上下文窗口被有效使用）。

对于我们来说，在 monorepo 中一个新会话的基线成本约为 20k token（10%），剩余 180k token 用于进行更改——这会很快填满。

三种主要工作流程

1. /compact（避免使用）
我尽可能避免使用它。自动压缩是不透明的、容易出错的，并且没有很好地优化。

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

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

核心要点：不要信任自动压缩。使用 /clear 进行简单重启，使用"文档与清除"方法为复杂任务创建持久的、外部的"记忆"。

---

三、斜杠命令：简单的快捷方式

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

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

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

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

---

四、子代理：主克隆架构 vs 领导专家模式

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

子代理的解决方案是将 (X + Y) * N 工作委托给专门的代理，它们只返回最终的 Z token 答案，保持你的主上下文清洁。

实践中的问题

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

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

2. 它们强制人类工作流程
更糟糕的是，它们将 Claude 推入一个僵化的、人类定义的工作流程。我现在规定它必须如何委托，而这正是我试图让代理为我解决的问题。

我的替代方案

我更喜欢使用 Claude 内置的 Task(...) 功能来生成通用代理的克隆。我将所有关键上下文放在 CLAUDE.md 中。然后，让主代理决定何时以及如何将工作委托给自己的副本。这给了我子代理的所有上下文保存好处，而没有缺点。代理动态地管理自己的编排。

在我的"构建多代理系统（第二部分）"文章中，我称这为"主克隆"架构，我强烈偏好它而不是自定义子代理鼓励的"领导专家"模型。

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

---

五、会话管理：resume 和 continue

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

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

核心要点：使用 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，如果代理在做次优的事情，它们会提供"即发即弃"的反馈。

我们有意不使用的 Hooks

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

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

---

七、计划模式：对齐预期

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

个人项目

对于我的业余项目，我专门使用内置的计划模式。这是在 Claude 开始之前与其对齐的一种方式，定义了如何构建某物以及它需要停下来并展示其工作的"检查点"。经常使用它可以建立强大的直觉，了解获得良好计划而不至于 Claude 搞砸实施所需的最少上下文。

企业项目

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

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

---

八、Skills：脚本化代理模型的正式化

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

如果你一直在关注我的文章，你会知道我已经偏离了 MCP 用于大多数开发工作流程，更喜欢构建简单的 CLI（正如我在"AI 无法阅读你的文档"中所论证的那样）。我对代理自主性的心智模型已经演变为三个阶段：

1. 单一提示：在一个巨大的提示中给代理所有上下文。（脆弱，不可扩展）

2. 工具调用："经典"代理模型。我们手工制作工具并为代理抽象现实。（更好，但创造了新的抽象和上下文瓶颈）

3. 脚本化：我们给代理访问原始环境——二进制文件、脚本和文档——它即时编写代码与它们交互。

在这种模式下，Agent Skills 是明显的下一个功能。它们是"脚本化"层的正式产品化。如果你像我一样已经偏爱 CLI 而不是 MCP，那么你一直都在隐含地获得 Skills 的好处。SKILL.md 文件只是一种更有组织、可共享和可发现的方式来记录这些 CLI 和脚本并将它们暴露给代理。

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

MCP 的新角色

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 的工作不是为代理抽象现实；它的工作是管理身份验证、网络和安全边界，然后避开。它为代理提供入口点，然后代理使用其脚本和 markdown 上下文来完成实际工作。

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

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

---

九、Claude Code SDK：通用代理框架

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

我的三种主要使用方式

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

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

3. 快速代理原型制作
这是我最常见的用途。它不仅用于编码。如果我对任何代理任务有想法（例如，使用自定义 CLI 或 MCP 的"威胁调查代理"），我使用 Claude Code SDK 在承诺完整的、部署的脚手架之前快速构建和测试原型。

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

---

十、GitHub Actions：运营化的终极方式

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

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

我们的使用场景

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

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

$ query-claude-gha-logs --since 5d | claude -p "看看其他 Claude 遇到了什么问题并修复它，然后提交 PR"

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

---

十一、高级配置：settings.json

最后，我有几个特定的 settings.json 配置，我发现它们对于业余和专业工作都是必不可少的。

1. HTTPS_PROXY/HTTP_PROXY
这对于调试非常有用。我将使用它来检查原始流量，以确切了解 Claude 发送了什么提示词。对于后台代理，它也是细粒度网络沙盒的强大工具。

2. MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS
我会提高这些值。我喜欢运行长而复杂的命令，默认超时通常过于保守。老实说，我不确定现在有了 bash 后台任务是否仍然需要这个，但我保留它以防万一。

3. ANTHROPIC_API_KEY
在工作中，我们使用我们的企业 API 密钥（通过 apiKeyHelper）。它将我们从"按席位"许可证转变为"基于使用量"的定价，这对我们的工作方式来说是更好的模式。

• 它考虑了开发者使用的巨大差异（我们看到工程师之间有 1:100 倍的差异）
• 它让工程师可以在我们的单一企业账户下修改非 Claude Code LLM 脚本

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

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

---

总结

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

核心要点回顾

1. CLAUDE.md：保持简洁，从护栏开始，不要试图写成完整手册
2. 上下文管理：使用 /clear + /catchup 而非自动压缩
3. 斜杠命令：简单的个人快捷方式，不要过度设计
4. 子代理：使用内置 Task(...) 而非自定义子代理
5. Hooks：在提交时验证，而非写入时阻止
6. 计划模式：复杂任务必用，与代理对齐预期
7. Skills vs MCP：优先脚本化模型，MCP 作为安全网关
8. SDK：并行脚本、内部工具、快速原型
9. GitHub Actions：运营化的终极方式，创建改进飞轮

---

原文作者：Shrivu Shankar
原文发布时间：2025 年 11 月 2 日
翻译时间：2026 年 1 月 25 日

---

欢迎关注公众号 FishTech Notes，一块交流使用心得！