Claude Code 隐藏配置全解析：文档未提及的进阶玩法

背景

Claude Code 作为 Anthropic 推出的终端 AI 编程代理，其官方文档虽然涵盖了基础用法，但许多高级配置能力并未公开说明。这些隐藏功能实际上隐藏在 node_modules 中作为 npm 包分发的源代码里。

本文基于对 @anthropic-ai/[email protected] 版本源码的深度解读，揭示了文档未提及的配置字段、响应格式和设置。这些功能包括通过自然语言描述环境来配置自动模式权限系统（内部代号“YOLO Classifier”）、利用 Hook 机制在命令执行中途重写指令、持久化代理记忆以及自我改进的“梦境循环”等。

需要注意的是，这些 undocumented（未文档化）的功能可能在不同版本间发生变化，且源码中标记为 “EXPERIMENTAL” 的字段明确被 Anthropic 工程师标记为不稳定。以下所有内容均基于当前版本快照，且所有示例均设计为可直接复制到项目中运行。

核心内容

1. 配置文件与技能文件的存放位置

在深入具体功能前，需明确各类配置文件的存储路径，以便区分个人设置与项目共享设置：

• 设置文件 (Settings):
  • 个人级：~/.claude/settings.json
  • 项目级：.claude/settings.json（可通过 Git 共享给团队）
• 技能文件 (Skills):
  • 个人级：~/.claude/skills/<name>/SKILL.md
  • 项目级：.claude/skills/<name>/SKILL.md
• 代理文件 (Agents):
  • 个人级：~/.claude/agents/<name>.md
  • 项目级：.claude/agents/<name>.md
• Hook 脚本:
  • 建议存放于 ~/.claude/hooks/ 目录下。
  • 重要提示：务必对脚本执行 chmod +x 赋予执行权限。

项目级文件（位于 .claude/ 下）可提交至 Git 并与团队共享；个人文件（位于 ~/.claude/ 下）仅对当前用户可见。

2. Hook 机制的深度交互：重写命令与实时反馈

文档仅说明 Hook 接收 stdin 上的 JSON 数据，且退出码 2 会阻止操作。然而，源码揭示 Hook 还可以向 stdout 返回包含特定事件字段的 JSON，从而实时修改 Claude Code 的行为。

PreToolUse Hook（工具使用前）

可返回以下字段：

• updatedInput：在执行前重写工具输入。例如，修改命令参数。
• permissionDecision：强制“允许”或“拒绝”，无需提示用户。
• permissionDecisionReason：解释决策原因（将在 UI 中显示）。
• additionalContext：向对话上下文注入文本。

实战示例：自动为 git push 添加 --dry-run 通过配置 Hook，可以在 Claude 执行 git push 前自动追加 --dry-run 参数，防止误操作。

settings.json 配置：

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/dry-run-pushes.sh"
      }]
    }]
  }
}

~/.claude/hooks/dry-run-pushes.sh 脚本：

#!/bin/bash
INPUT=$(jq -r '.tool_input.command' < /dev/stdin)
if echo "$INPUT" | grep -q 'git push'; then
  jq -n --arg cmd "$INPUT --dry-run" '{"updatedInput": {"command": $cmd}}'
fi

效果：Claude 认为它正在运行 git push origin main，但 Hook 在静默中将其重写为 git push origin main --dry-run。

SessionStart Hook（会话开始时）

可返回以下字段：

• watchPaths：设置自动文件监听，触发 FileChanged 事件。
• initialUserMessage：在会话的第一个用户消息前预置内容。
• additionalContext：注入贯穿整个会话的上下文。

实战示例：自动注入 Git 上下文并监听配置文件 此 Hook 会在每次会话开始时注入当前分支和未提交文件数量，并监听关键配置文件。

settings.json 配置：

{
  "hooks": {
    "SessionStart": [{
      "hooks": [{
        "type": "command",
        "command": "~/.claude/hooks/session-context.sh",
        "statusMessage": "Loading project context..."
      }]
    }]
  }
}

~/.claude/hooks/session-context.sh 脚本：

#!/bin/bash
BRANCH=$(git branch --show-current 2>/dev/null)
CHANGES=$(git status --porcelain 2>/dev/null | wc -l | tr -d ' ')
jq -n \
  --arg branch "$BRANCH" \
  --arg changes "$CHANGES" \
  '{
    "watchPaths": ["package.json", ".env", "tsconfig.json"],
    "additionalContext": "Current branch: \($branch). Uncommitted changes: \($changes) files."
  }'

效果：Claude 自动监听 package.json、.env 和 tsconfig.json 的变化，并在你输入任何内容前就知道当前分支和未提交文件数。

权限自动批准

通过 PreToolUse Hook 结合 permissionDecision 字段，可以构建自定义的权限分类器。例如，自动批准只读的 Bash 命令：

~/.claude/hooks/auto-approve-readonly.sh：

#!/bin/bash
CMD=$(jq -r '.tool_input.command' < /dev/stdin)
if echo "$CMD" | grep -qE '^(ls|cat|echo|pwd|whoami|date|git status|git log|git diff)'; then
  echo '{"permissionDecision": "allow", "permissionDecisionReason": "Safe read-only command"}'
fi

3. 三个被文档遗漏的 Hook 字段

除了文档中列出的 type, command, matcher, timeout, if, statusMessage 外，源码解析器还支持三个改变 Hook 行为的关键字段：

1. once: true

   • 功能：Hook 仅触发一次，随后自动移除。
   • 用途：非常适合首次会话设置。
   • 示例：检查 .env 文件是否存在，若不存在则从模板复制，且后续不再运行。

   {
     "hooks": {
       "SessionStart": [{
         "hooks": [{
           "type": "command",
           "command": "[ -f .env ] || cp .env.example .env && echo 'Created .env from template'",
           "once": true,
           "statusMessage": "First-time setup..."
         }]
       }]
     }
   }
   

2. async: true

   • 功能：在后台运行 Hook，不阻塞 Claude 的执行（Fire and forget）。
   • 用途：记录审计日志而不增加会话延迟。
   • 示例：将每个 Bash 命令记录到审计文件。

   {
     "hooks": {
       "PostToolUse": [{
         "matcher": "Bash",
         "hooks": [{
           "type": "command",
           "command": "jq '{timestamp: now, command: .tool_input.command, session: .session_id}' < /dev/stdin >> ~/.claude/audit.jsonl",
           "async": true
         }]
       }]
     }
   }
   

3