GinoGino

我的 Claude Code 实战经验：深度使用每个功能 [译]

14 分钟阅读编程技术

本文翻译自 Shrivu Shankar 的文章 How I Use Every Claude Code Feature，发布于 2025 年 11 月 2 日。

简评：这是一篇难得的深度实践文章。作者既在个人项目中频繁使用 Claude Code，又在企业环境下为每月消耗数十亿 token 的工程团队构建 AI-IDE 工具，这种双重视角让文章兼具灵活性和严谨性。文章不是泛泛而谈，而是针对每个功能给出了明确的使用场景、实践技巧和常见陷阱。比如为什么要避免 /compact，为什么自定义子智能体反而会带来问题，Skills 和 MCP 的真正定位是什么。作为参考手册，它涵盖了从基础配置到高级特性的完整路径；作为经验分享，它提供了很多反直觉但有效的做法。如果你正在使用或考虑使用 Claude Code，这篇文章能帮你少走不少弯路。唯一的问题是内容确实比较长，很多经验适合使用一段时间后进行查阅，而不是一口气读完了事。

引言

我是 Claude Code 的重度用户。

业余时间，我每周会在虚拟机里运行它好几次，用来折腾个人项目。经常加上 --dangerously-skip-permissions 参数，想到什么就直接让它写。工作中，我所在团队为公司工程团队构建 AI-IDE 的规则和工具，光是代码生成，每月就要消耗数十亿 token。

CLI 智能体（命令行智能体）现在很热闹。Claude Code、Gemini CLI、Cursor、Codex CLI，核心竞争其实就是 Anthropic 和 OpenAI 两家。但说实话，和其他开发者聊下来，大家选工具的理由往往挺表面的，某个功能用着顺手，或者就是喜欢某种系统提示的风格。到了现在，这些工具都已经很成熟了。很多人过度关注输出风格或 UI 细节。比如智能体那些过分客气的回复，在我看来根本不是问题，反而是个信号：你管得太细了。我的理念是发射后不管，交代清楚任务，设好上下文，然后让它自己干。评价工具要看最终的 PR，而不是它是怎么写出来的。

用了几个月 Claude Code，写这篇文章记录一下对整个生态的理解。我会讲几乎每个功能的用法（以及为什么不用某些功能），从基础的 CLAUDE.md 文件、自定义斜杠命令，到子智能体（Subagents）、钩子（Hooks）和 GitHub Actions。文章比较长，建议当成参考手册来查，不必一次读完。

CLAUDE.md

要高效使用 Claude Code，代码库里最重要的文件就是根目录的 CLAUDE.md。可以把它看作智能体的宪法，它理解你的代码库如何运作，全靠这个文件。

如何维护这个文件，取决于场景。个人项目里，我让 Claude 随便往里写。

工作中，我们 monorepo（单一代码仓库）的 CLAUDE.md 严格维护，目前 13 KB（预计会涨到 25 KB）：

  • 只记录 30% 以上工程师会用到的工具和 API（比例是我定的）。不够通用的工具，文档放在各自的产品或库里。
  • 我们甚至给每个内部工具的文档分配了 token 上限，像是在卖广告位。工具介绍写不简洁？那就不配进 CLAUDE.md。

实用技巧与常见误区

用久了，我们总结出一套编写 CLAUDE.md 的方法论：

  1. 从护栏开始，不是说明书
    CLAUDE.md 应该很短，只在 Claude 容易出错的地方加说明。别想着写完整手册。

  2. 别用 @ 引用文档
    如果你有详细文档，可能想在 CLAUDE.md 里用 @ 引用。但这会把整个文件塞进上下文，非常臃肿。只写路径？Claude 会忽略。正确做法是推销这个文件，告诉它为什么和何时该读。例如：遇到复杂用法或 FooBarError 错误时，参考 path/to/docs.md 的高级故障排除。

  3. 别只说禁止
    不要写纯否定约束，比如永远不要用某个标志。智能体真需要这个标志时就傻了。永远提供替代方案。

  4. 把 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。

核心要点：把 CLAUDE.md 当作高层护栏和指引。用它来判断哪里需要改进工具，让 AI（和人）都更好用，而不是写成大而全的手册。

精简、上下文与清空

建议编码时至少运行一次 /context，看看 200k 个 token 的上下文窗口用了多少。即使有 Sonnet-1M，我也不信全部上下文都能被有效利用。我们 monorepo 里，新会话基础开销约 20k 个 token（10%），剩下 180k 个用来干活——但很快就会用完。（可以把上下文想象成磁盘空间，工作一段时间后，需要清理消息才能继续）

上下文窗口

我的三种工作流：

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

  • /clear + /catchup（简单重启）：我的默认方式。先 /clear 清状态，再运行自定义的 /catchup 命令，让 Claude 读取当前 git 分支的所有改动。

  • 文档化后清空（复杂任务重启）：大任务专用。让 Claude 把计划和进度写进 .md 文件，/clear 清状态，然后新会话读取 .md 继续干。

核心要点：别信自动压缩。简单重启用 /clear，复杂任务用文档化后清空给它创建外部记忆。

自定义斜杠命令

我把斜杠命令当作常用提示词的快捷方式，仅此而已。我只设了两个：

  • /catchup：让 Claude 读取当前 git 分支的所有改动。
  • /pr：清理代码、暂存改动、准备 Pull Request 的小助手。

如果你有一长串复杂的自定义命令，那就是反模式了。Claude 这种智能体的意义，就是让你输入几乎任何想法，都能得到有用、可合并的结果。一旦你强迫工程师（或非工程师）为了干活必须学习一堆不知道记在哪的魔法命令，那你就失败了。

核心要点：斜杠命令只是个人快捷方式，别用它替代更直观的 CLAUDE.md 和更好的工具设计。

自定义子智能体

理论上，自定义子智能体（Subagent）是 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 里，让主智能体自己决定何时、如何把工作分给它的副本。既有节省上下文的好处，又避免了缺点。智能体动态管理自己的协作流程。

我在文章《构建多智能体系统（第二部分）》里把这叫主干-克隆（Master-Clone）架构，强烈推荐它，而不是自定义子智能体鼓励的领导-专家（Lead-Specialist）模型。

核心要点：自定义子智能体是脆弱方案。把上下文给主智能体（通过 CLAUDE.md），让它用 Task/Explore(...) 自己管理任务分配。

恢复、继续与历史记录

我经常用 claude --resume 和 claude --continue。重启出 bug 的终端，或恢复旧会话，都很方便。有时会 claude --resume 几天前的会话，就为了问智能体当时怎么解决某个错误的，然后用这些信息改进我们的 CLAUDE.md 和内部工具。

往深了说，Claude Code 把所有会话历史存在 ~/.claude/projects/，可以挖掘原始数据。我有脚本运行元分析（meta-analysis），找常见的异常、权限请求和错误模式，帮助改进面向智能体的上下文。

核心要点：用 claude --resume 和 claude --continue 重启会话，挖掘历史记录里埋藏的上下文。

钩子（Hooks）

钩子很重要。个人项目我不用，但企业级代码仓库里，它们对引导 Claude 行为至关重要。钩子是确定性的必须做规则，配合 CLAUDE.md 里应该做的建议。

我们用两种钩子：

  1. 提交时阻塞（Block-at-Submit）
    主要策略。我们有个 PreToolUse 钩子，包裹所有 Bash(git commit) 命令。钩子检查 /tmp/agent-pre-commit-pass 文件是否存在，测试脚本只有在所有测试通过时才创建这个文件。文件不存在？钩子阻止提交，逼 Claude 进测试-修复循环，直到构建成功。

  2. 提示型（Hint）
    简单的非阻塞钩子。智能体做次优操作时，提供即发即忘式的反馈。

我们特意不用写入时阻塞（block-at-write）钩子（比如在 Edit 或 Write 操作上）。中途打断智能体会让它困惑甚至沮丧。更有效的方法是让它完成工作，提交时再检查最终结果。

核心要点：用钩子在提交时强制状态验证（提交时阻塞）。别在写入时阻塞，让智能体完成计划，再检查最终结果。

规划模式

用 AI IDE 做大型功能变更，规划必不可少。

个人项目，我全用内置规划模式。这是在 Claude 开工前跟它对齐的方式，既定义如何构建，也设定检查点，也就是它需要停下来展示工作的地方。常用这功能能培养直觉：知道提供哪些最精简的上下文，就能得到好计划，而不会让 Claude 在实现时搞砸。

我们 monorepo 里，已经在推广基于 Claude Code SDK 的自定义规划工具。和原生规划模式类似，但经过深度提示工程，输出和我们现有的技术设计格式一致。它还能开箱即用地强制执行内部最佳实践，从代码结构到数据隐私和安全。让工程师能随心所欲地规划新功能，像资深架构师一样，至少宣传是这么说的。

核心要点：复杂变更一定要用内置规划模式，在智能体开工前对齐计划。

技能（Skills）

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

关注我帖子的话，你会知道我在大多数开发工作流里已经放弃 MCP，转而构建简单的命令行工具（详见《AI 无法阅读你的文档》）。我对智能体自主性的心智模型已经演变成三个阶段：

  1. 单次提示：一个巨大提示包含所有上下文。（脆弱，不可扩展）
  2. 工具调用：经典智能体模型。手动创建工具，为智能体抽象现实。（更好，但引入新的抽象和上下文瓶颈）
  3. 脚本化：让智能体访问原始环境——二进制、脚本、文档——它即时写代码与它们交互。

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

如果你像我一样，已经偏爱命令行工具而非 MCP，那你一直在隐式享受技能（Skills）的好处。SKILL.md 文件只是更组织化、可共享、可发现的方式，用来记录这些 CLI 工具和脚本，并暴露给智能体。

核心要点：技能是正确的抽象。它们将基于脚本化的智能体模型正式化，比 MCP 代表的僵化、类 API 模型更健壮、更灵活。

MCP（Model Context Protocol）

技能出现不代表 MCP 已死（参见《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 上下文执行实际工作。

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

核心要点：用 MCP 当数据网关。给智能体一两个高层工具（比如原始数据转储 API），然后智能体对其进行脚本化操作。

Claude Code SDK

Claude Code 不只是交互式命令行，它还是强大的 SDK，用来构建全新的智能体，编码和非编码任务都行。大多数新的业余项目，我已经把它当默认智能体框架，不用 LangChain/CrewAI 之类的了。

三种主要用法：

  1. 大规模并行脚本
    大规模重构、bug 修复或迁移，我不用交互式聊天。写简单的 Bash 脚本，并行调用 claude -p "in /pathA change all refs from foo to bar"。比让主智能体管理几十个子智能体任务更可扩展、可控。

  2. 构建内部聊天工具
    SDK 非常适合把复杂流程封装成简单聊天界面，给非技术用户用。比如安装程序出错时，回退到 Claude Code SDK 来修复问题。或者内部的 v0-at-home 工具，让设计团队在我们内部 UI 框架里随意写前端原型，想法高保真，代码更直接能用到生产。

  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 修复 bug 或添加功能，返回一个充分测试的 PR。

因为 GHA 日志就是完整的智能体日志，我们有运维流程定期在公司层面审查这些日志，查找常见错误、Bash 错误或不一致的工程实践。这形成数据驱动的飞轮：Bug → 改进的 CLAUDE.md / CLI → 更好的智能体。

$ 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 投入运营的终极方式。它把 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 智能体，值得试试。关于这些高级功能，好的指南很少，唯一的学习方法就是亲自上手。

Claude CodeAI CodingCLAUDE.mdHooksSkillsMCPGitHub ActionsSDK

相关文章

从指挥家到编排者：AI 编程的未来 [译]作为一名资深工程师，我是如何影响公司政治的[译]技术债并不存在，只有权衡取舍[译]Java 24 与 IntelliJ IDEA[译]
查看更多 编程技术 的文章