Claude Code – Everything you can configure that the docs don’t tell you

Claude Code：那些官方文档没告诉你的配置秘籍

I Read the Claude Code Source Code. Here’s Everything You Can Configure That the Docs Don’t Tell You. Hook fields that rewrite commands mid-flight, persistent agent memory, auto-mode rules in plain English, self-improving dream loops, and every example is copy-paste ready.

我阅读了 Claude Code 的源代码，以下是你所能配置但官方文档中未提及的所有内容。包括在命令执行前进行重写的 Hook 字段、持久化智能体记忆、纯英文的自动模式规则、自我改进的“梦境循环”，且所有示例均可直接复制粘贴使用。

Claude Code’s auto-mode permission system is internally called the “YOLO Classifier.” That’s the actual variable name in yoloClassifier.ts. And you can configure it with plain English descriptions of your environment, things like “this is a staging server, destructive operations are acceptable,” that the classifier reads to decide what’s safe to auto-approve. This isn’t in any documentation.

Claude Code 的自动模式权限系统在内部被称为“YOLO 分类器”（YOLO Classifier）。这正是 yoloClassifier.ts 文件中的实际变量名。你可以用纯英文描述你的环境来配置它，例如“这是一个暂存服务器，允许执行破坏性操作”，分类器会读取这些描述来决定哪些操作可以自动批准。这些内容在任何文档中都没有提及。

It’s one of dozens of undocumented capabilities buried in the Claude Code source code, which is sitting right there in your node_modules as a publicly distributed npm package. The official docs cover the basics well enough. But the source code reveals fields, response formats, and settings that dramatically expand what you can build. Everything here works right now, and every example is designed to be dropped into your project as-is.

这是埋藏在 Claude Code 源代码中的数十种未公开功能之一，而这些代码就存在于你 node_modules 目录下的 npm 包中。官方文档涵盖了基础知识，但源代码揭示了许多字段、响应格式和设置，极大地扩展了你的开发能力。这里提到的所有内容现在都可以使用，且每个示例都设计为可以直接放入你的项目中。

A note on versioning: These findings come from @anthropic-ai/claude-code@2.1.87. Undocumented features can change between releases, so treat this as a snapshot of what’s available today. Fields with “EXPERIMENTAL” in their names are explicitly flagged as unstable by Anthropic’s own engineers, and I’ll call those out individually.

关于版本说明：这些发现基于 @anthropic-ai/claude-code@2.1.87 版本。未公开的功能可能会在不同版本间发生变化，因此请将其视为当前可用功能的快照。名称中带有“EXPERIMENTAL”（实验性）的字段已被 Anthropic 的工程师明确标记为不稳定，我会在文中单独指出。

Before you start

开始之前

Quick reference for where everything lives: 以下是各项配置存放位置的快速参考：

• Settings: ~/.claude/settings.json (personal) or .claude/settings.json (project, shared via git)

• Skills: ~/.claude/skills/<name>/SKILL.md (personal) or .claude/skills/<name>/SKILL.md (project)

• Agents: ~/.claude/agents/<name>.md (personal) or .claude/agents/<name>.md (project)

• Hook scripts: ~/.claude/hooks/ is a good convention. Remember to chmod +x your scripts.

• 设置： ~/.claude/settings.json（个人）或 .claude/settings.json（项目级，通过 git 共享）

• 技能： ~/.claude/skills/<name>/SKILL.md（个人）或 .claude/skills/<name>/SKILL.md（项目级）

• 智能体： ~/.claude/agents/<name>.md（个人）或 .claude/agents/<name>.md（项目级）

• Hook 脚本： 建议存放在 ~/.claude/hooks/ 目录下。记得给脚本执行权限 (chmod +x)。

Project-level files in .claude/ can be committed to git and shared with your team. Personal files in ~/.claude/ are yours alone.

.claude/ 下的项目级文件可以提交到 git 并与团队共享。而 ~/.claude/ 下的个人文件仅供你自己使用。

Your hooks can talk back, and nobody told you how

你的 Hook 可以“回话”，但没人告诉你怎么做

This is the biggest gap in the documentation. The docs tell you hooks receive JSON on stdin and that exit code 2 blocks an operation. What they don’t tell you is that hooks can return JSON on stdout with event-specific fields that modify Claude Code’s behavior in real time. The source code reveals exactly what each event type accepts.

这是文档中最大的缺失。文档只告诉你 Hook 通过 stdin 接收 JSON，且退出代码 2 会阻止操作。但它们没告诉你，Hook 可以通过 stdout 返回 JSON，其中包含特定于事件的字段，可以实时修改 Claude Code 的行为。源代码揭示了每种事件类型具体接受哪些参数。

PreToolUse hooks can return: PreToolUse（工具使用前）Hook 可以返回：

• updatedInput - rewrite the tool’s input before it executes. You can modify commands mid-flight.

• permissionDecision - force “allow” or “deny” without prompting the user.

• permissionDecisionReason - explain the decision (shown in UI).

• additionalContext - inject text into the conversation context.

• updatedInput - 在工具执行前重写其输入。你可以在命令执行过程中进行修改。

• permissionDecision - 强制“允许”或“拒绝”，无需提示用户。

• permissionDecisionReason - 解释决策原因（显示在 UI 中）。

• additionalContext - 将文本注入到对话上下文中。

SessionStart hooks can return: SessionStart（会话开始）Hook 可以返回：

• watchPaths - set up automatic file watching that triggers FileChanged events.

• initialUserMessage - prepend content to the first user message in the session.

• additionalContext - inject context that persists for the whole session.

• watchPaths - 设置自动文件监控，触发 FileChanged 事件。

• initialUserMessage - 在会话的第一条用户消息前添加内容。

• additionalContext - 注入在整个会话期间持续存在的上下文。

PostToolUse hooks can return: PostToolUse（工具使用后）Hook 可以返回：

• updatedMCPToolOutput - modify what Claude sees from an MCP tool response.

• additionalContext - inject context after a tool runs.

• updatedMCPToolOutput - 修改 Claude 从 MCP 工具响应中看到的内容。

• additionalContext - 在工具运行后注入上下文。

PermissionRequest hooks can return: PermissionRequest（权限请求）Hook 可以返回：

• decision - programmatically allow or deny with updatedInput or updatedPermissions.

• decision - 通过编程方式允许或拒绝，并可配合 updatedInput 或 updatedPermissions 使用。

This is powerful stuff. Here’s a PreToolUse hook that automatically adds --dry-run to any git push command before Claude executes it.

这功能非常强大。下面是一个 PreToolUse Hook 示例，它会在 Claude 执行任何 git push 命令之前，自动为其添加 --dry-run 参数。

(…code examples omitted for brevity…) (…代码示例略…)

Claude thinks it’s running git push origin main, but your hook quietly rewrites it to git push origin main --dry-run before execution. The updatedInput field isn’t in any docs.

Claude 以为它在运行 git push origin main，但你的 Hook 在执行前悄悄将其重写为 git push origin main --dry-run。updatedInput 字段在任何文档中都没有提及。

Three hook fields the docs forgot to mention

文档遗漏的三个 Hook 字段

The documented hook fields are type, command, matcher, timeout, if, and statusMessage. The source code parser accepts three more that fundamentally change how hooks behave.

文档中记录的 Hook 字段包括 type、command、matcher、timeout、if 和 statusMessage。但源代码解析器还接受另外三个字段，它们从根本上改变了 Hook 的行为。

once: true fires the hook exactly once, then auto-removes it. Perfect for first-session setup:

once: true 会让 Hook 只触发一次，然后自动移除。非常适合首次会话的设置：

(…code example…)

Simple enough to inline. 简单到可以直接内联使用。