解锁 Claude Code：深入未记录配置和高级钩子

虽然 Claude Code 的官方文档提供了坚实的基础，但对源码的深入探索——该源码以公共 npm 包形式提供——揭示了一层复杂且未记录的功能。这些特性将 Claude Code 从普通的 AI 助手转变为可编程的开发环境，拥有用于工具使用的中间件层以及持久化学习循环。

本指南探讨了在源码中发现的高级配置，重点介绍如何通过钩子、自定义技能和代理记忆来扩展工具的行为。

可编程中间件：高级钩子

官方文档中最大的缺口是钩子可以通过在 stdout 输出 JSON 来实时修改 Claude Code 行为的能力。文档仅提到退出码 2 会阻止操作，而源码则揭示了允许动态干预的具体字段。

PreToolUse 钩子

PreToolUse 钩子可以返回以下字段以拦截并修改工具执行：

  • updatedInput：重写工具的输入（例如，自动向 git push 命令添加 --dry-run）。
  • permissionDecision：强制“allow”或“deny”决定，且不提示用户。
  • permissionDecisionReason：提供决定的原因，显示在 UI 中。
  • additionalContext：直接向对话上下文注入文本。

SessionStart 和 PostToolUse 钩子

  • SessionStart：可以返回 watchPaths 以触发自动文件监视，initialUserMessage 用于在第一条消息前添加内容，以及 additionalContext 用于会话范围的持久化。
  • PostToolUse：可以返回 updatedMCPToolOutput 来修改 Claude 从 MCP 工具响应中看到的内容，并可返回 additionalContext 在工具运行后注入上下文。

高级钩子执行字段

除了标准的 type 和 command 字段外，源码解析器还接受三个关键修饰符：

  • once: true：钩子仅触发一次后即自删除。适用于首次项目设置（例如，将 .env.example 复制为 .env）。
  • async: true：在后台运行钩子，不阻塞模型的响应。非常适合审计日志记录。
  • asyncRewake: true：在后台运行，但如果钩子以退出码 2 结束，则会“唤醒”模型并阻塞操作。这允许非阻塞的安全扫描（如机密检测），仅在发现违规时中断流程。

使用自定义技能扩展能力

.claude/skills/ 中的自定义技能支持超出基础文档的 frontmatter 字段，允许对模型行为和资源分配进行细粒度控制。

模型和努力级别覆盖

  • model：为特定技能覆盖默认模型。可以使用 haiku 进行快速、低成本的 lint，使用 opus 进行复杂的架构评审。
  • effort：控制推理深度。选项包括 low、medium、high 或 max。

范围钩子与委派

  • hooks：可以定义仅在特定技能运行期间激活的钩子。例如，strict-typescript 技能可以注册一个 PostToolUse 钩子，在每次文件编辑后运行 tsc，并在技能完成后注销该钩子。
  • agent：将技能的执行委派给特定的自定义代理。
  • disable-model-invocation: true：阻止模型自动调用该技能；只能通过显式的 /skill-name 命令触发。

持久化代理与学习循环

.claude/agents/ 中的自定义代理可以配置长期记忆和视觉区分。

代理记忆

memory 字段允许代理在会话之间保持状态：

  • user：跨所有项目的全局持久化。
  • project：针对当前项目的持久化。
  • local：每个项目私有的持久化（通常被 gitignore）。

这使得可以创建能够学习代码库模式、记住先前架构决策并随时间跟踪重复问题的代理。

高级代理配置

  • color：设置 UI 颜色（例如 red、blue、green），以视觉区分不同代理。
  • omitClaudeMd: true：跳过加载 CLAUDE.md 指令层级，允许代理从第一原理审查代码，而不受项目特定偏见影响。
  • criticalSystemReminder_EXPERIMENTAL：在每一次对话轮次重新注入的简短信息，确保安全约束在对话压缩过程中永不丢失。

“YOLO 分类器” 与自动模式

在内部，Claude Code 使用 “YOLO 分类器” 来决定在自动模式下哪些操作可以自动批准。虽然模式匹配（例如 Bash(npm *)）是主要方法，但 settings.json 中的 environment 数组允许你提供对环境的自然语言描述。

通过添加类似 “This is a local dev machine with no production database access” 的字符串，你为分类器提供上下文，使其在处理模糊命令时能够做出安全决策，从而向 AI 简要说明你的环境风险画像。

自我改进：自动记忆与自动梦境

两个设置启用了复合学习循环，使 Claude Code 能在无需模型再训练的情况下自行进化：

  1. autoMemoryEnabled：自动从会话中提取持久记忆并写入项目记忆存储。
  2. autoDreamEnabled：每 24 小时，后台代理审阅会话记录，合并记忆、去重并清理陈旧条目。

社区观点与注意事项

虽然这些特性提供了巨大的力量，但社区也提出了重要的警示。多位 Hacker News 用户指出，由于这些功能未被文档化或埋藏在源码中，可能会在没有通知的情况下改变。

“Claude 包每周发布十个新版本……绝对不应依赖一些未记录的技巧：它们会改变，会导致深度超特定配置失效。”

此外，一些用户注意到，随着 Anthropic 更新官方文档，这些 “未记录” 的特性（如 asyncRewake 和某些 frontmatter 字段）正逐步出现在官方文档中，尽管仍然难以查找。用户还被鼓励查看用于 Bedrock 部署的环境变量，以进一步调优模型行为，例如禁用自适应思考或遥测。

Sources