如何使用Claude Code，看这一篇就够了

访问量 32 Posted recently Updated recently 53~68 min read

安装部署和基础的准备看这篇《Calude Code 使用文档和中转站》，本文主要介绍日常开发中使用到的关键指令的操作。

下面是本篇文章的翻译，根据实际情况选择阅读。原文链接：https://blog.sshh.io/p/how-i-use-every-claude-code-feature

背景

我几乎每天都在使用 Claude Code。

在个人项目中，我每周会在虚拟机里运行它多次，经常配合 --dangerously-skip-permissions，以“随心编码（vibe code）”的方式快速把脑中的点子落地。工作中，我们团队的一部分专注为工程团队构建 AI IDE 的规范与工具，仅代码生成每月就要消耗数十亿 Token。

CLI 代理工具已经进入激烈竞争：Claude Code、Gemini CLI、Cursor、Codex CLI 等等。坦白说，今天更像是 Anthropic 与 OpenAI 的直接对决。不过，很多开发者的选择常常受一些“表面因素”影响，比如某个功能“恰好”更顺手，或系统提示语的“氛围感”更对味。整体来看，这些工具都已相当成熟。我也发现不少人过度在意输出风格或 UI。例如那种“你说得完全正确！”的过度恭维，我并不视为严重问题；它更多说明你把人类介入看得太重。我更倡导“交付后不插手”：把任务委托出去，提供好上下文，让它自行完成。评判工具时，我只看最终 PR（拉取请求）是否可合并，不纠结它的过程。

过去几个月我持续使用 Claude Code，这篇文章是我对其生态的系统性思考。内容几乎覆盖我用过的每一个功能（以及我刻意不用的功能）：从基础的 CLAUDE.md 和自定义斜杠命令，到子代理、钩子、GitHub Action 等高阶组件。文章较长，更适合作为参考手册，而非一口气读完。

CLAUDE.md

想高效使用 Claude Code，仓库根目录的 CLAUDE.md 是最重要的文件。它是代理的“宪法”，也是理解仓库运作方式的首要依据。

如何维护这个文件要看场景。对个人项目，我基本放任 Claude 写入它认为必要的内容。

在工作中，我们在单仓库中严格维护 CLAUDE.md，目前约 13KB（很可能增长到 25KB）。

  • 只记录至少约 30% 工程师会用到的工具与 API（该阈值为经验值）；其他工具放在对应产品或库的 Markdown 文档中说明。

  • 我们甚至为每个内部工具的文档设定“最大 Token 预算”，几乎像给团队“售卖版位”。如果你的工具无法简洁说明，就不适合进入 CLAUDE.md。

写作建议与常见反模式

随着时间推移，我们形成了编写高效 CLAUDE.md 的一套强观点方法论。

  1. 先立护栏，不写长手册。CLAUDE.md 应从小处着手，围绕 Claude 常见错误来写。

  2. 不要用 @ 直接嵌入长文档。虽然很诱人，但会让每次运行都嵌入整份文档，拖垮上下文窗口。而仅写路径时，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。

若需要更多关于“为编码代理编写 Markdown”的建议，可参考《AI 读不懂你的文档》《AI 驱动的软件工程》以及《Cursor（AI IDE）是如何工作的》。

结论：把 CLAUDE.md 视为一组高层次、经过筛选的护栏与指引。用它倒推哪些地方需要投入更“AI/人类友好”的工具，而不是写成面面俱到的冗长手册。

感谢阅读 Shrivu 的 Substack！订阅可免费接收新文章并支持我的写作。

Compact、Context 与 Clear

建议在编码过程中至少运行一次 /context，观察你的 20 万 Token 上下文窗口是如何被使用的（即使是 Sonnet‑1M，我也不太相信它能持续高效利用完整上下文）。在我们的单仓库中，新会话的基础开销约 2 万 Token（约 10%），剩余约 18 万用于具体改动——很快就会被占满。

这是我近期一个副项目里 /context 的截图。可以把它理解为“空间配额”：开发一个功能时会逐步被填满。几分钟到几小时后，你需要清理消息（紫色部分），为后续工作腾出空间。

我主要有三种工作流：

  •  /compact（尽量避免）：尽量不使用。自动压缩不透明、容易出错且优化不足。

  •  /clear + /catchup（简单重启）：我的默认做法。先用 /clear 清空状态，再运行自定义 /catchup 命令，让 Claude 阅读当前分支的所有改动文件。

  • “文档化并清空”（复杂重启）：用于大型任务。先让 Claude 把计划与进度写入一个 .md，再 /clear 清空状态，开启新会话并让它读取该 .md 继续执行。

结论：不要依赖自动压缩。简单任务用 /clear 重启；复杂任务用“文档化并清空”，为代理建立更持久的外部“记忆”。

自定义斜杠命令

我把斜杠命令当作常用提示语的快捷方式，仅此而已。我的配置非常轻量：

  • /catchup：让 Claude 读取当前 Git 分支的所有改动文件。

  • /pr：一个简单辅助命令，用于清理代码、暂存变更并准备 PR（拉取请求）。

我认为，维护一长串复杂的自定义斜杠命令是一种反模式。代理的意义在于：你几乎可以用自然语言表达需求并得到可合并的结果。一旦强迫工程师（甚至非工程师）必须学习一套藏在某处的“神奇命令”才能完成工作，就偏离了初衷。

结论：把斜杠命令当作简单、个人化的快捷方式，而不是用来替代更易用的 CLAUDE.md 与更完善的工具化代理。

自定义子代理

从理论上看，自定义子代理是 Claude Code 在上下文管理方面最有力的功能。思路是：复杂任务需要 X Token 的输入上下文（如如何跑测试），执行过程中会累计 Y Token 的工作上下文，并产出 Z Token 的答案。运行 N 个任务就会占用 (X + Y + Z) * N 的主上下文。

子代理的解法是把 (X + Y) * N 的工作分派给专用代理，它们只返回最终的 Z，从而保持主上下文整洁。

这个思路很强，但在实践中自定义子代理会带来两类问题：

  1. 上下文被“守门”。如果我做了一个 PythonTests 子代理，就把所有测试上下文藏到主代理之外。主代理无法整体推理变更，只有调用子代理才能知道如何验证自己的代码。

  2. 把人类流程强加给代理。更糟的是，它迫使 Claude 遵循僵化的人工定义流程。你在规定它必须如何委派——而这本应由代理自己决定。

我更倾向使用 Claude 的内置 Task(...)，即克隆“通用代理”本身。

把关键上下文写进 CLAUDE.md，让主代理自行决定何时、如何委派给自身的副本。这样既获得子代理在上下文上的节省优势，又避免其弊端，代理可以动态编排自身。

在我的《Building Multi‑Agent Systems（Part 2）》一文中，我称之为“主‑克隆架构”，并且认为它明显优于自定义子代理所倡导的“领导‑专家模型”。

结论：自定义子代理是相对脆弱的方案。将关键上下文放在 CLAUDE.md，让主代理通过 Task/Explore(...) 自主完成委派。

恢复、继续与历史

简单来说，我经常使用 claude --resume 与 claude --continue。它们非常适合重启出问题的终端或快速恢复旧会话。我常会从几天前的会话中执行 claude --resume，让代理总结它如何解决某个错误，再据此完善我们的 CLAUDE.md 和内部工具。

更进一步，Claude Code 会把所有会话历史存到 ~/.claude/projects/，这些原始历史数据可直接利用。我写了脚本对日志做元分析，查找常见异常、权限请求与错误模式，以改进面向代理的上下文。

结论：使用 claude --resume 与 claude --continue 重启会话，挖掘沉淀在历史中的上下文价值。

钩子（Hook）

钩子非常重要。个人项目我用得不多，但在复杂的企业仓库中，它们对引导 Claude 至关重要。钩子与 CLAUDE.md 的“建议”互补，是“必须执行”的确定性规则。

我们使用两类钩子：

  1. 提交阶段阻断钩子：这是我们的主策略。一个包裹 Bash（git commit） 的 PreToolUse 钩子会检查 /tmp/agent-pre-commit-pass 文件——该文件只有在所有测试通过时由测试脚本创建。若文件缺失，钩子就阻断提交，迫使 Claude 进入“测试‑修复”循环，直到构建变绿。

  2. 提示钩子：这类钩子不阻断，仅提供“发射后不管”的轻量反馈；即便代理行为不尽如人意也不会强制阻止。

我们刻意不在写入阶段阻断（如 Edit 或 Write）。中途打断会让代理困惑甚至“挫败”。更好的做法是让它完成计划，再在提交阶段检查最终结果。

结论：在提交阶段用钩子强制状态校验（提交阶段阻断），避免在写入阶段阻断——先让代理完成计划，再检查结果。

规划模式（Planning Mode）

对于任何“大型”功能变更，规划模式都是必需的。

在个人项目中，我只用内置的规划模式。它用于在开始前与 Claude 对齐：既明确“如何实现”，也定义必须停下来的“检查点”。经常使用会帮助你形成直觉，弄清实现好方案所需的最小上下文，避免 Claude 把实现环节搞砸。

在工作单仓库里，我们开始基于 Claude Code SDK 推出自定义规划工具。它与原生规划模式类似，但通过强提示让输出符合我们的技术设计格式，并内置执行最佳实践——从代码结构到数据隐私与安全。工程师可以“随心规划”新特性，像资深架构师一样（至少我们的目标是如此）。

结论：复杂变更务必先使用内置规划模式完成对齐，再让代理开工。

技能（Skills）

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

如果你关注过我的文章，会知道我在多数开发流程中逐渐远离 MCP，更偏好构建简单的 CLI（参见《AI 读不懂你的文档》）。我对代理自主性的心智模型经历了三阶段：

  1. 单提示：把所有上下文塞进一个巨大的提示。（脆弱、不可扩展）

  2. 工具调用：经典代理模型。我们手工构建工具，为代理抽象现实。（更好，但会引入新抽象与上下文瓶颈）

  3. 脚本化：让代理直接访问真实环境——二进制、脚本、文档，并即时编写代码与它们交互。

基于这个模型，代理技能是显而易见的下一步。它是“脚本化层”的正式产品化。

如果你和我一样更偏向 CLI 而非 MCP，其实早已隐性获得了技能的好处。SKILL.md 只是更有组织、可共享、可发现地记录这些 CLI 与脚本，并将它们暴露给代理的方式。

结论：技能是正确的抽象。它把“脚本化”代理模型正式化，比传统偏“API 模型”的 MCP 更健壮、更灵活。

MCP（模型上下文协议）

技能并不意味着 MCP 已死（另见《Everything Wrong with MCP》）。过去很多 MCP 做得很糟，堆满上下文，几十个工具只是镜像一个 REST API（read_thing_a()、read_thing_b()、update_thing_c()）。

“脚本化”模型（现已由技能正式化）更好，但需要一种安全方式访问环境。这对我而言是 MCP 的新定位：更聚焦。

MCP 不应是臃肿的 API，而应是简单、安全的网关，只提供少量高层次的强力工具：

  • download_raw_data(filters…)

  • take_sensitive_gated_action(args…)

  • execute_code_in_environment_with_state(code…)

在这种模型下，MCP 的职责不是为代理抽象现实，而是负责认证、网络与安全边界，然后尽量“退出视野”。它只提供入口，代理再通过脚本与 Markdown 上下文完成实际工作。

我目前只使用 Playwright 的 MCP，这很合理——它属于复杂、有状态的环境。而对 Jira、AWS、GitHub 等无状态工具，我都迁移到简单的 CLI。

结论：将 MCP 用作数据网关。只给代理一两种高层工具（如原始数据导出），让它自行脚本化使用。

Claude Code SDK

Claude Code 不只是交互式 CLI；它还是一个强大的 SDK，能构建全新的代理——既可做编码任务，也可处理非编码任务。多数新的个人项目我都把它作为默认代理框架，替代 LangChain/CrewAI。

我主要有三种使用方式：

  1. 大规模并行脚本化：做大范围重构、修 Bug 或迁移时，我不走交互式聊天，而是写简单的 Bash 脚本并行调用 claude -p "in /pathA change all refs from foo to bar"。这比让主代理管理几十个子代理任务更可控、更易扩展。

  2. 构建内部聊天工具：把复杂流程封装成简单的聊天界面供非技术用户使用。比如安装器出错时，回退到 Claude Code SDK 直接“修好”。或者做一个“自建版 v0（v0‑at‑home）”，让设计团队在自家 UI 框架里随心编码（vibe code）原型前端，使灵感更高保真，产出的代码更快用于生产前端。

  3. 快速原型验证：这是我最常用的方式，不仅用于编码。想到任何代理化任务（例如用自定义 CLI 或 MCP 构建“威胁调查代理”），我会用 Claude Code SDK 快速搭建并测试原型，再决定是否上完整脚手架。

结论：Claude Code SDK 是强大的通用代理框架。先用它完成批量代码处理、内部工具与快速原型，再考虑更复杂的框架。

Claude Code GHA

Claude Code 的 GitHub Action（GHA）可能是我最喜欢、也最容易被忽视的功能之一。概念很简单：在 GHA 中运行 Claude Code。正因为简单，威力更大。

它类似 Cursor 的后台代理或 Codex 的托管 Web UI，但可定制性更强。你可以掌控整个容器与环境，拿到更多数据，并在沙箱隔离与审计控制方面，远胜多数同类产品。同时也支持钩子与 MCP 等高级功能。

我们用它构建了“随处触发 PR”的定制工具。用户可以在 Slack、Jira，甚至 CloudWatch 告警中触发 PR；GHA 会修复问题或增加新功能，并返回一个已通过测试的 PR1。

由于 GHA 日志就是完整代理日志，我们建立了公司层面的运维流程，定期审阅这些日志，查找常见错误、Bash 异常或不符合工程规范的做法。它形成数据驱动的飞轮：Bug → 改进 CLAUDE.md/CLI → 更好的代理。

$ query-claude-gha-logs --since 5d | claude -p "看其他 Claude 卡在哪儿并修复，然后提一个 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 Key（通过 apiKeyHelper）。这使我们从“按座位授权”转向“按用量计费”，更符合我们的使用习惯。

    • 它能反映开发者使用量的巨大差异（我们见过 1:100 的差距）。

    • 它允许工程师在单一企业账号下尝试非 Claude Code 的各类 LLM 脚本。

  • "permissions"：我会不定期自查，审计允许 Claude 自动执行的命令列表。

结论：settings.json 是进行高级定制的关键入口。

总结

内容不少，希望对你有所帮助。如果你还没用过像 Claude Code 或 Codex CLI 这样的 CLI 代理工具，现在大概是时候了。关于这些高级功能的好指南很少，最有效的学习方式就是亲自下水实践。

Claude Code(CC)
实操案例 工具框架 技术开发
License:  CC BY 4.0

©2025 AI全书. Some rights reserved.

    备案号: 浙ICP备06043869号-8