Claude Code 未文档化配置深度解析：Hook 编程化、YOLO 分类器与自改进系统

Claude Code 的官方文档仅展示了基础配置能力，但其源码（以 npm 包形式分发）中隐藏着一套完整的可编程接口层。这些未文档化的配置参数不仅允许开发者重写工具输入、注入会话上下文、自定义权限决策逻辑，更构建了一个具备持久记忆和自主学习的 Agent 运行时环境。

Hook 系统的编程化扩展

官方文档仅说明 Hook 接收 JSON 输入且退出码 2 可阻断操作，但源码揭示了 Hook 可通过 stdout 返回结构化数据实时修改 Claude Code 行为。PreToolUse 事件支持 updatedInput 字段重写工具参数 —— 例如在 git push 命令执行前自动注入 --dry-run；permissionDecision 字段可强制允许或拒绝操作，绕过用户确认流程；additionalContext 则能在执行前后向对话上下文注入动态信息。

SessionStart Hook 支持 watchPaths 配置自动文件监控，可在会话启动时监听 package.json、.env 等关键文件的变更；initialUserMessage 允许预设首条用户消息，实现会话初始化自动化。PostToolUse 更进一步，支持 updatedMCPToolOutput 修改 MCP 工具的响应内容，为工具链集成提供中间层处理能力。

Hook 配置本身也存在未文档化的执行模式控制字段。once: true 使 Hook 仅执行一次后自动从配置中移除，适用于首次环境初始化；async: true 将 Hook 转为后台非阻塞执行，适合审计日志记录等旁路操作；asyncRewake: true 则结合了异步执行与错误阻断能力 —— 正常路径下不阻塞主流程，但当 Hook 以退出码 2 结束时唤醒模型并阻断操作，实现 "静默监控、异常拦截" 的安全模式。

Skill 与 Agent 的精细化控制

Skill 和 Agent 的 frontmatter 支持大量官方未提及的字段。model 字段允许覆盖默认模型，对简单任务指定 haiku 以降低成本，对复杂分析指定 opus 并配合 effort: max 获取深度推理。hooks 字段支持在 Skill 激活期间注册临时 Hook，Skill 结束后自动注销，实现作用域隔离的工具链增强。

Agent 配置中的 memory 字段是构建自学习系统的核心，支持 user（跨项目全局）、project（项目级）、local（项目级私有）三种持久化级别。配合 color 字段的 UI 颜色标识，可在多 Agent 并行运行时实现视觉区分。omitClaudeMd: true 跳过 CLAUDE.md 指令层级，适用于需要 "fresh eyes" 进行无偏见代码审查的场景。criticalSystemReminder_EXPERIMENTAL 在每轮对话中重新注入系统级提醒，即使上下文压缩后仍保持关键约束可见 —— 但需注意该字段带有 EXPERIMENTAL 标记，存在未来版本变更风险。

YOLO 分类器与自然语言权限

Claude Code 的自动模式内部称为 "YOLO Classifier"，其配置支持 environment 数组字段，允许用自然语言描述运行环境。开发者可声明 "这是本地开发机，无生产数据库访问权限" 或 "所有 Docker 容器使用隔离网络"，分类器会将这些描述纳入安全决策考量。这种设计将权限规则从硬编码模式匹配升级为上下文感知判断，使自动批准策略能够适配复杂的企业环境。

权限模式语言本身也支持更精细的语法：Bash(npm *) 匹配 npm 子命令，Read(src/**/*.ts) 递归匹配 TypeScript 文件，mcp__slack__post_message 精确控制 MCP 服务器工具权限。if 字段的匹配条件复用相同语法，实现 Hook 的条件触发。

自改进与记忆系统

settings.json 中的 autoMemoryEnabled 和 autoDreamEnabled 激活 Claude Code 的自改进能力。前者在每次会话后自动提取持久记忆 —— 包括用户偏好、代码库模式、已做决策 —— 写入项目记忆目录；后者每 24 小时（当积累 5 个以上会话时）启动 "梦境" 整合，合并重复记忆、解决冲突、将相对日期转为绝对时间戳、清理过期条目。

这套系统创造了复合学习循环：会话产生记忆，梦境整合记忆，整合后的记忆指导未来会话。数周后，Agent 能在未被明确告知的情况下回忆代码库惯例和用户偏好，实现无需模型重训练的经验学习。

Fork 与缓存优化

context: fork 创建后台子 Agent 执行耗时任务（安全扫描、依赖分析、文档生成），保持主会话响应性。源码揭示 Fork 通过 CacheSafeParams 契约与父会话共享提示缓存，要求所有 Fork 产生字节级相同的 API 请求前缀以最大化缓存命中。若在 Forked Skill 中指定不同模型（如父会话用 Opus、Fork 用 Haiku），前缀分歧将导致缓存失效。建议对 Fork 使用 model: inherit 或省略模型字段以保持缓存一致性。

工程实践建议

未文档化功能虽强大，但需审慎使用。EXPERIMENTAL 标记字段可能在未来版本中移除或重命名，建议仅用于非关键场景。Hook 脚本需正确处理 JSON 输入输出，建议用 jq 进行结构化数据处理。权限配置应遵循最小权限原则，对 rm -rf、sudo 等危险操作保持 soft_deny 或显式确认。记忆系统启用后建议定期审查记忆文件，避免过时信息累积。

这些隐藏配置揭示了 Claude Code 从交互式助手向持久化、可学习、自主运行的开发环境演进的架构意图。对于需要深度定制 Agent 行为的工程团队，源码本身就是最权威的配置文档。

资料来源

• André Figueira, "I Read the Claude Code Source Code. Here's Everything You Can Configure That the Docs Don't Tell You", BuildingBetter, 2026-04-01.

ai-systems