我是怎么用Claude Code的每一个功能的-环球搭子

你用过 Claude Code，但你可能只用了 claude -p "帮我改个 bug" 这一招。

这篇文章把 Claude Code 的每一个功能——从 CLAUDE.md、Hooks、SubAgent，到 GitHub Action 和 Agent SDK——都在环境里跑了个遍。

这不是一篇"入门教程"，而是一份操盘手视角的功能地图：哪些功能该重度投入，哪些是陷阱（比如 /compact 和自定义 SubAgent），以及怎么把一个 CLI 工具变成工程体系里可审计、能自我改进的生产组件。

适合所有不想只停在"对话写代码"阶段的开发者。

先说背景

我每周会跑几次 Claude Code，搞个人项目的时候经常加 –dangerously-skip-permissions，图个省事。

CLI Agent 这条赛道越来越挤了——Claude Code、Gemini CLI、Codex CLI、Cursor CLI、Copilot CLI……说实话，真正在掰手腕的就是 Anthropic 和 OpenAI。

跟其他开发者聊的时候我发现，大家选工具的理由其实挺随意的：碰巧用某个工具做成了一个功能，或者喜欢它系统提示词的"语气"。到了现在这个阶段，这些工具都够用了。我觉得很多人太纠结输出风格和界面了。那种"你说得对！"的讨好语气确实有点烦，但说明你已经在深度使用了，这不是坏事。

我的用法是：把任务丢出去，设好上下文，让它自己跑，最后看 PR 的质量来评判，不盯过程。

用了几个月之后，这篇文章算是我对整个 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。

写法上的经验

用了一段时间之后，我们总结出几条比较明确的原则：

1. 先写限制，不写指南。从小处开始，根据 Claude 反复犯的错来补充内容。
2. 别到处 @ 引用文档。你可能想在 CLAUDE.md 里 @ 一堆已有文档，但这会把整份文件塞进上下文窗口，很浪费。你得告诉 Agent 什么时候该去读那份文件："遇到 FooBarError 时，去看 path/to/docs.md。"
3. 别只说"禁止"。纯粹的负面约束（"绝对不要用 –foo-bar"）会让 Agent 卡住——它觉得必须用的时候就左右为难了。永远给一个替代方案。
4. 把 CLAUDE.md 当强制手段。 CLI 命令又长又复杂？写个 bash 包装器，提供清晰的 API，然后记录这个包装器。

示例结构：

代码块
Markdown
复制
# Monorepo

## Python

一句话总结：把 CLAUDE.md 当成一套精心策划的护栏。用它来指导你在哪里需要投入精力做更好的工具，别试图把它变成百科全书。

上下文管理：压缩和清理

建议在编码会话中至少跑一次 /context，看看 200k token 的上下文窗口是怎么被吃掉的。我们在 monorepo 里，一个新会话的基线成本大约 20k token（10%），剩下 180k 给实际工作——填满的速度比你想的快。

三种工作流：

• /compact（别用）自动压缩不透明、容易出错，优化也不好。
• /clear + /catchup（简单重启）我的默认方式。/clear 清状态，然后跑自定义的 /catchup 让 Claude 读当前 git 分支里所有改过的文件。
• "记录并清除"（复杂重启）大型任务用。让 Claude 把计划和进展写到一个 .md 文件里，/clear 清上下文，再让它读那个文件继续干。

一句话：别信自动压缩。简单重启用 /clear，复杂任务用"记录并清除"来做外部记忆。

自定义斜杠命令

我把斜杠命令当成常用提示的快捷方式，没别的。配置很少：

• /catchup：让 Claude 读当前 git 分支里所有改过的文件。
• /pr：清理代码、暂存更改、准备 Pull Request。

如果你搞了一长串复杂的自定义命令，那就走偏了。一旦工程师为了干活还得去查文档学一套新的魔法命令，你就失败了。

斜杠命令就是简单的个人快捷方式，别用它替代好的 CLAUDE.md 和好的工具。

自定义 SubAgent

SubAgent 是 Claude Code 在上下文管理上最强的功能。原理很直接：一个复杂任务需要 X token 输入，工作中累积 Y token，产出 Z token 的答案。跑 N 个这样的任务，主窗口就有 (X + Y + Z) * N 个 token。

但实际用起来有两个问题：

1. 上下文被锁住了。创建一个 PythonTests SubAgent，所有测试相关的上下文就对主 Agent 不可见了。
2. 强迫 Agent 走人类定义的流程。把 Claude 塞进一个僵硬的工作流里，效果往往不好。

我更倾向于用 Claude 内置的 Task(…) 来生成通用代理的克隆体。关键上下文放在 CLAUDE.md 里，让主 Agent 自己决定什么时候、怎么把工作分出去。这就是"主-克隆"模式。

自定义 SubAgent 是个脆弱的方案。把上下文给主 Agent（放 CLAUDE.md 里），让它用自己的 Task/Explore(…) 来管理委派。

恢复、继续与历史记录

claude –resume 和 claude –continue 我用得很多。终端挂了可以重启，旧会话可以快速恢复。我经常 claude –resume 一个几天前的会话，就为了问 Agent 它当时是怎么绕过某个错误的，然后拿这些信息去改进 CLAUDE.md 和内部工具。

Claude Code 把所有会话历史存在 ~/.claude/projects/ 里。我写了一些脚本对这些日志做元分析，找常见的异常、权限请求和错误模式，用来改进 Agent 的上下文。

Hooks

Hooks 很重要。它们是确定性的"必须做"规则，跟 CLAUDE.md 里"应该做"的建议互补。

我们用两种：

• 提交时阻断（Block-at-Submit）主要策略。一个 PreToolUse 钩子包裹 Bash(git commit) 命令，检查 /tmp/agent-pre-commit-pass 文件——只有所有测试通过才会创建这个文件。文件不存在就阻止提交，逼 Claude 进入"测试-修复"循环直到构建通过。
• 提示钩子（Hint Hooks）非阻塞的，Agent 做了次优操作时给个反馈，不打断。

我们刻意不用"写入时阻断"的钩子。在 Agent 执行计划的中途打断它，会让它困惑。更好的做法是让它干完，在提交阶段检查最终结果。

用 Hooks 在提交时做状态验证。别在写入时阻断——让 Agent 完成计划，再检查结果。

Plan 模式

大功能变更之前，规划不能省。

个人项目我用内置的 Plan 模式就够了。在 Claude 动手之前先对齐：怎么建，哪些地方需要停下来给我看。

工作上，我们基于 Claude Agent SDK 做了一个自定义规划工具，跟原生 Plan 模式类似，但做了大量提示工程，让输出跟内部的技术设计格式对齐，开箱就能用。

复杂变更之前，先用 Plan 模式把计划定下来。

Skills

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

我对 Agent 自主性的理解经历了三个阶段：

1. 单次提示：一个大提示塞进所有上下文。脆弱，扩展不了。
2. 工具调用：手动做工具，给 Agent 抽象现实世界。好一些，但制造了新的抽象瓶颈。
3. 脚本化：给 Agent 访问原始环境的权限——二进制文件、脚本、文档——让它自己写代码来交互。

Skills 就是"脚本化"这一层的产品化。SKILL.md 是一种更有组织、可共享的方式来记录 CLI 和脚本，暴露给 Agent 用。

Skills 是对的抽象方向。它把基于脚本的 Agent 模型正式化了，比 MCP 那种僵硬的 API 模型更灵活。

MCP

Skills 不意味着 MCP 没用了。一个好的 MCP 不该是臃肿的 API，而是一个简单、安全的网关，提供几个高层工具：

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

MCP 管认证、网络和安全边界，然后让开。Agent 拿到入口点之后，靠自己的脚本能力和 markdown 上下文完成实际工作。

我现在唯一还在用的 MCP 是 Playwright——它是有状态的复杂环境。所有无状态工具（Jira、AWS、GitHub）都迁移到了简单的 CLI。

MCP 当数据网关用。给 Agent 一两个高层工具，让它自己编脚本。

Claude Code（Agent）SDK

Claude Code 不只是交互式 CLI，它也是一个 SDK——现在叫 Claude Agent SDK，可以拿来构建新的 Agent。我的新个人项目已经默认用它当 Agent 框架了，不再用 LangChain 或 CrewAI。

三个主要用法：

1. 大规模并行脚本。大规模重构或迁移时，写 bash 脚本并行调用 claude -p "in /pathA change all refs from foo to bar"。
2. 内部聊天工具。把复杂流程包装成聊天界面给非技术用户用。
3. 快速原型。有 Agent 想法的时候，先用 SDK 快速验证，再决定要不要投入到正式框架里。

Claude Agent SDK 是个通用的 Agent 框架。批量处理代码、做内部工具、快速验证想法，都好用。

Claude Code GHA（GitHub Action）

这可能是我最喜欢也最被低估的功能。就是在 GitHub Action 里跑 Claude Code，听起来简单，但正因为简单所以强。

跟 Cursor 的 Background Agent 或 Codex 的 Web UI 比，GHA 的可定制性强得多。你控制整个容器和环境，能接触更多数据，沙盒和审计控制也更好。而且 Hooks、MCP 这些高级功能全都支持。

我们拿它做了"随处发 PR"的工具。用户从 Slack、Jira、甚至 CloudWatch 告警触发一个 PR，GHA 修 bug 或加功能，返回一个跑过完整测试的 PR。

GHA 的日志就是完整的 Agent 日志，我们定期审查这些日志，找常见错误和不一致的工程实践。这形成了一个飞轮：Bug → 改进 CLAUDE.md / CLI → 更好的 Agent。

代码块
Bash
复制
$ query-claude-gha-logs --since 5d | claude -p "看看其他 Claude 卡在了哪里，修复它，然后提交一个PR"

GHA 是把 Claude Code 投入生产的终极方式。它把个人工具变成了工程系统里一个可审计、能自我改进的组件。

settings.json

几个值得关注的配置：

• HTTPS_PROXY / HTTP_PROXY：对调试非常有用。可以检查原始流量，看 Claude 到底发了什么 Prompt。Background Agent 场景下也能做细粒度的网络沙盒工具。
• MCP_TOOL_TIMEOUT / BASH_MAX_TIMEOUT_MS：调高这些值。默认超时太保守了。
• ANTHROPIC_API_KEY：工作上用企业 API 密钥，从按席位付费变成按用量付费。
• "permissions"：偶尔审计一下允许 Claude 自动运行的命令列表。