尧图网站建设 
文档提示工程人工智能【免费下载链接】claude-code-system-promptsAll parts of Claude Codes system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.项目地址https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts点击查看免费下载本文基于 Claude Code System Prompts 仓库中内置的 update-config 技能族文档撰写。该技能负责通过settings.json配置 Claude Code 运行框架harness的自动化行为hooks、工具权限permissions与运行环境env并给出了从构造 → 管道测试 → 写入 → 校验 → 证明生效的完整闭环流程。读完本文你将掌握三类配置的落盘位置与作用域优先级、hook 事件与 matcher 的精确写法、权限规则的语法边界以及如何用 7 步验证流程确保一条 hook 在真实项目中确实被触发且按预期工作。一、update-config 技能是做什么的在 Claude Code 的提示词体系中skill-update-config-description.md 是Update config技能的触发描述frontmatterdescription字段。它界定了这个技能的适用范围配置 Claude Code 的 settings.json 文件。它的职责被明确划分为三类Hooks自动化行为凡是从现在起当 X 发生时每次 X 时每当 X 时在 X 之前/之后这类表述都必须通过 settings.json 中配置的 hooks 实现。Permissions权限允许 X添加权限把权限移动到……等表述。Env vars环境变量设置 XY。一个关键设计判断是自动化行为必须由 harness运行框架执行而不是由 Claude 的记忆/偏好执行。因为 Claude 只在会话中活动而 hook 是挂在工具调用生命周期上的框架级回调——Claude 停止输出后hook 依然会在事件发生时被框架执行。因此记忆memory无法替代 hooks 来实现自动化触发。该技能的典型触发示例来自原文档allow npm commands允许 npm 命令add bq permission to global settings向全局设置添加 bq 权限move permission to user settings把权限移动到用户设置set DEBUGtrue设置环境变量when claude stops show XClaude 停止时显示 X同时文档也给出了边界判断对于theme、model这类简单设置应建议用户直接使用/config斜杠命令而不是手动改文件。完整的决策逻辑参见 skill-update-claude-code-config.md。二、settings.json 的存储位置与作用域优先级在动手配置之前必须先确定改哪个文件。根据 skill-update-config-settings-file-locations.mdClaude Code 的设置在三个作用域分布文件作用域Git 策略用途~/.claude/settings.json全局Global不适用所有项目的个人偏好.claude/settings.json项目Project提交Commit团队级 hooks、权限、插件.claude/settings.local.json项目Project加入 .gitignore该项目下的个人覆盖加载顺序user → project → local后者覆盖前者。也就是说.claude/settings.local.json的优先级最高适合放个人私有覆盖.claude/settings.json适合随仓库提交、让团队共享的配置~/.claude/settings.json则承载跨项目的全局偏好。这里有一个与 update-config 技能强相关的实践细节当首次创建.claude/settings.local.json时应主动将其加入.gitignore——因为 Write 工具不会自动为它添加 gitignore 规则该提醒来自 skill-update-config-7-step-verification-flow.md 第 4 步。三、核心配置 Schema 参考settings.json 是严格的 JSON 文件不支持//注释与尾随逗号下面按配置块逐一展开以下 schema 均继承自 skill-update-config-settings-file-locations.md。3.1 Permissions权限{ permissions: { allow: [Bash(npm *), Edit(.claude), Read], deny: [Bash(rm -rf *)], ask: [Edit(//etc/*)], defaultMode: default | plan | acceptEdits | dontAsk, additionalDirectories: [/extra/dir] } }权限规则Permission Rule语法有四种形态精确匹配Bash(npm run test)—— 只匹配这一条命令前缀通配Bash(git *)—— 匹配git、git status、git commit等一切以git开头的命令注意*前的空格是前缀匹配正确工作的必要条件仅工具名Read—— 放行该工具的全部操作文件路径规则Edit(src/**)—— 在permissions中路径规则统一用Edit(path)表示所有写文件工具Write、Edit、NotebookEdit用Read(path)表示读取。特别需要注意的是Write(path)、NotebookEdit(path)、Glob(path)这类规则不参与文件权限检查裸工具名如Write、deny/ask 形式的Tool(param:value)规则以及 hook 的if条件仍然使用各工具自己的名称。3.2 Environment Variables环境变量{ env: { DEBUG: true, MY_API_KEY: value } }env 块是一个键值对象用于为会话注入环境变量。技能文档中的典型场景就是set DEBUGtrue。3.3 Model Agent模型与代理{ model: sonnet, agent: agent-name, alwaysThinkingEnabled: true }model可取sonnet、fable、opus、haiku或完整的模型 ID。这类设置属于简单设置按技能建议优先引导用户走/config命令。3.4 Attribution提交与 PR 署名{ attribution: { commit: Custom commit trailer text, pr: Custom PR description text } }将commit或pr设为空字符串可隐藏对应署名要全部隐藏需两者都设为并额外设置sessionUrl: false。必须写成对象形式不能写成attribution: false旧版 Claude Code 会拒绝 true/false 布尔值并跳过整个 settings 文件。3.5 MCP Server 管理{ enableAllProjectMcpServers: true, enabledMcpjsonServers: [server1, server2], disabledMcpjsonServers: [blocked-server] }3.6 Plugins插件{ enabledPlugins: { formatteranthropic-tools: true } }插件语法为plugin-namesource其中source取claude-code-marketplace、claude-plugins-official或builtin之一。3.7 其他常用设置language首选回复语言如japanesecleanupPeriodDays会话转录自动清理保留天数默认 30最小 1respectGitignore是否尊重 .gitignore默认 truespinnerTipsEnabledspinner 中是否显示提示timeFormatUI 时钟格式auto默认、12-hour、24-hour、24-hour-utc或 strftime 模式如%H:%MtimeZoneIANA 时区默认系统时区如UTCspinnerVerbs自定义 spinner 动词{ mode: append | replace, verbs: [...] }spinnerTipsOverride覆盖 spinner 提示{ excludeDefault: true, tips: [Custom tip] }syntaxHighlightingDisabled禁用 diff 高亮。四、Hooks自动化行为的核心机制update-config 技能最重要的应用场景是配置 hooks。Hook 在 Claude Code 生命周期的特定节点执行命令是唯一能实现框架级自动化的机制。完整结构参考 system-prompt-hooks-configuration.md。4.1 Hook 结构{ hooks: { EVENT_NAME: [ { matcher: ToolName|OtherTool, hooks: [ { type: command, command: your-command-here, timeout: 60, statusMessage: Running... } ] } ] } }结构分三层事件 → matcher匹配器→ hooks 数组。每个 hook 条目支持type、command、timeout超时秒数、statusMessage执行时显示的状态消息等字段。4.2 Hook 事件与 Matcher事件Matcher用途PermissionRequest工具名权限提示弹出前运行PreToolUse工具名工具调用前运行可以阻止调用PostToolUse工具名工具成功调用后运行PostToolUseFailure工具名工具调用失败后运行Notification通知类型收到通知时运行Stop-Claude 停止时运行包括 clear、resume、compactPreCompactmanual/auto压缩会话上下文之前PostCompactmanual/auto压缩之后会收到摘要UserPromptSubmit-用户提交提示时SessionStart-会话启动时常见工具 matcherBash、Write、Edit、Read、Glob、Grep可用|组合如Write|Edit。4.3 Hook 类型Command Hook命令型运行一条 shell 命令{ type: command, command: prettier --write $FILE, timeout: 30 }Prompt Hook提示型用 LLM 评估条件仅可用于工具事件PreToolUse、PostToolUse、PermissionRequest{ type: prompt, prompt: Is this safe? $ARGUMENTS }Agent Hook代理型运行一个带工具的 agent同样仅限工具事件{ type: agent, prompt: Verify tests pass: $ARGUMENTS }4.4 Hook 的标准输入stdin JSONHook 命令通过 stdin 接收 JSON 载荷{ session_id: abc123, tool_name: Write, tool_input: { file_path: /path/to/file.txt, content: ... }, tool_response: { success: true } }其中tool_response仅 PostToolUse 提供。这正是构造 hook 命令时需要用jq -r安全提取字段的原因。4.5 Hook 的 JSON 输出控制行为Hook 可以输出 JSON 来控制 Claude Code 的行为{ systemMessage: Warning shown to user in UI, continue: false, stopReason: Message shown when blocking, suppressOutput: false, decision: block, reason: Explanation for decision, hookSpecificOutput: { hookEventName: PostToolUse, additionalContext: Context injected back to model } }字段语义systemMessage向用户显示消息所有 hook 可用continue设为false即阻止/停止默认 truestopReasoncontinue为 false 时显示的消息suppressOutput从转录中隐藏 stdout默认 falsedecisionPostToolUse/Stop/UserPromptSubmit 事件取block对 PreToolUse 已废弃改用hookSpecificOutput.permissionDecisionreason决策的解释hookSpecificOutput事件专属输出必须包含hookEventNameadditionalContext注入模型上下文的文本permissionDecisionallow/deny/ask仅 PreToolUsepermissionDecisionReason权限决策原因仅 PreToolUseupdatedInput修改后的工具输入仅 PreToolUse。4.6 三个常见实战模式自动格式化PostToolUse Write|Edit{ hooks: { PostToolUse: [{ matcher: Write|Edit, hooks: [{ type: command, command: jq -r .tool_response.filePath // .tool_input.file_path | { read -r f; prettier --write \$f\; } 2/dev/null || true }] }] } }记录所有 bash 命令PreToolUse Bash{ hooks: { PreToolUse: [{ matcher: Bash, hooks: [{ type: command, command: jq -r .tool_input.command ~/.claude/bash-log.txt }] }] } }代码变更后运行测试PostToolUse Write|Edit{ hooks: { PostToolUse: [{ matcher: Write|Edit, hooks: [{ type: command, command: jq -r .tool_input.file_path // .tool_response.filePath | grep -E \\.(ts|js)$ npm test || true }] }] } }五、什么必须用 Hook什么不能用记忆替代skill-update-claude-code-config.md 用一个清晰的判断框定了使用边界只要用户想要的是响应某个事件自动发生的事情就需要 hook记忆/偏好无法触发自动化动作。必须使用 hook 的典型需求压缩上下文前问我保留什么 →PreCompacthook写完文件后运行 prettier →PostToolUsehookmatcher 为Write|Edit我运行 bash 命令时记录它们 →PreToolUsehookmatcher 为Bash代码变更后总是运行测试 →PostToolUsehookHook 事件全集PreToolUse、PostToolUse、PreCompact、PostCompact、Stop、Notification、SessionStart再加上 PermissionRequest、PostToolUseFailure、UserPromptSubmit 等见上文事件表。六、配置工作流与合并铁律6.1 标准工作流澄清意图Clarify intent请求含糊时先用 AskUserQuestion 澄清——改哪个设置文件user/project/local、是追加到现有数组还是替换、多个可选值时取哪个具体值先读后写Read existing file改动前必须读取目标 settings 文件小心合并Merge carefully保留已有设置尤其是数组编辑文件Edit file用 Edit 工具修改文件不存在时先请用户创建确认Confirm告知用户改了什么。6.2 合并数组正确与错误示范错误做法覆盖了已有权限{ permissions: { allow: [Bash(npm *)] } }正确做法保留既有 追加新项{ permissions: { allow: [ Bash(git *), // 已有 Edit(.claude), // 已有 Bash(npm *) // 新增 ] } }6.3 /config 命令 vs 直接编辑的选择建议/config命令处理的简单设置theme、editorMode、verbose、model、language、alwaysThinkingEnabled、permissions.defaultMode。应直接编辑 settings.json的复杂配置hooksPreToolUse、PostToolUse 等、复杂权限规则allow/deny 数组、环境变量、MCP server 配置、插件配置。七、构造并验证 Hook 的 7 步流程这是 update-config 技能族中最具工程价值的流程出自 skill-update-config-7-step-verification-flow.md。给定事件、matcher、目标文件和期望行为按以下步骤执行——每一步捕获一类不同的失败一条静默不做任何事的 hook 比没有 hook 更糟。去重检查Dedup check读取目标文件。若同一 eventmatcher 上已存在 hook展示现有命令并询问保留、替换、还是并列添加。为当前项目构造命令——不要臆断hook 从 stdin 接收 JSON。构造命令时要安全提取所需载荷——用jq -r存入带引号的变量或用{ read -r f; ... $f; }不要用不带引号的| xargs它会按空格拆分以本项目实际运行工具的方式调用npx/bunx/yarn/pnpmMakefile 目标还是全局安装跳过工具不处理的输入格式化器通常有--ignore-unknown没有的话按扩展名做守卫先保持 RAW 状态——不加|| true、不抑制 stderr等管道测试通过后再包裹。管道测试原始命令Pipe-test合成 hook 将收到的 stdin 载荷直接管道输入Pre|PostToolUse作用于Write|Editecho {tool_name:Edit,tool_input:{file_path:仓库里的真实文件}} | cmdPre|PostToolUse作用于Bashecho {tool_name:Bash,tool_input:{command:ls}} | cmdStop/UserPromptSubmit/SessionStart多数命令不读 stdinecho {} | cmd即可。同时检查退出码和副作用文件是否真的被格式化、测试是否真的运行了。失败就得到真实报错——修复包管理器选错了工具没装jq 路径不对后重测。通过后再用2/dev/null || true包裹除非用户想要阻塞式检查。写入 JSON合并进目标文件schema 结构见上文Hook 结构。若首次创建.claude/settings.local.json记得加入 .gitignore。一次校验语法 schemajq -e .hooks.event[] | select(.matcher matcher) | .hooks[] | select(.type command) | .command target-file退出 0 并打印出命令 正确退出 4 matcher 不匹配退出 5 JSON 畸形或嵌套错误。注意一个损坏的 settings.json 会静默禁用该文件里的所有设置——文件中既有的任何畸形也一并修复。证明 hook 确实触发仅对可在当前回合触发的Pre|PostToolUsematcher 执行Write|Edit用 Edit 触发Bash用 Bash 触发。Stop/UserPromptSubmit/SessionStart在本回合之外触发直接跳到第 7 步。对PostToolUse/Write|Edit上的格式化器通过 Edit 引入一个可被该格式化器修正的违规连续两个空行、错误缩进、缺失分号——注意不要用尾部空白Edit 写入前会剥离它重新读取确认 hook 已修复它对其他任何 hook临时在 settings.json 的命令前加echo $(date) hook fired /tmp/claude-hook-check.txt;触发对应工具Write|Edit用 Edit、Bash用无害的true读取哨兵文件。无论通过与否都要清理——还原违规、去掉哨兵前缀。若证明失败但管道测试和jq -e都通过了说明 settings 监视器没有监视.claude/目录——它只监视本次会话启动时已存在设置文件的目录。hook 本身写得没错告诉用户打开一次设置菜单重新加载配置或重启你无法自己完成这一步。交接Handoff告诉用户 hook 已生效或按监视器注意事项需要重载/重启并告知他们以后可在设置文件中查看、编辑或禁用它。UI 只在 hook 报错或过慢时显示 Ran N hooks——静默成功在设计上就是不可见的。八、常见错误与 Hook 排障8.1 常见错误来自技能文档替换而非合并——必须始终保留既有设置改错文件——作用域不明时先问用户无效 JSON——改完必须校验语法忘记先读后写——写之前永远先读。8.2 Hook 不运行的排障清单检查设置文件——读~/.claude/settings.json或.claude/settings.json验证 JSON 语法——无效 JSON 会静默失败检查 matcher——是否匹配工具名如Bash、Write、Edit检查 hook 类型——是command、prompt还是agent手动测试命令——单独运行 hook 命令看是否工作使用--debug——运行claude --debug查看 hook 执行日志。九、权限配置的进阶参考从转录生成 allowlistupdate-config 技能生态中还有一个高度相关的配套技能——skill-generate-permission-allowlist-from-transcripts.md它演示了权限规则语法在真实场景中的运用权限格式Bash(foo*)、Bash(foo)、Bash(foo bar *)、mcp__slack__slack_read_thread等会话转录位于~/.claude/projects/sanitized-cwd/*.jsonl可据此统计高频只读工具调用生成去重后的permissions.allow追加列表该文档同时强调了一条与 update-config 强相关的安全红线永远不要 allowlist 一个会授予任意代码执行的模式——解释器python/node/bun/ruby/php 等、shellbash/sh/zsh/ssh 等、包运行器npx/bunx/uvx 等、任务运行器通配npm run *、make *等、gh api *、docker run/exec、sudo等一律排除精确形式如Bash(bun run typecheck)可以Bash(bun run *)不可以。十、结语从文档到可验证的工程实践update-config 技能的核心价值在于它不只是改文件而是给出了一个可验证的配置闭环先确定作用域user/project/local再判断该走/config还是直接编辑对 hooks 走构造 → 管道测试 → 写入 → jq 校验 → 证明触发 → 交接的 7 步流程对权限牢记合并不覆盖最窄模式禁止任意代码执行三条铁律最后用claude --debug兜底排障。这套方法论可以直接迁移到任何使用 settings.json 驱动 agent harness 的场景中。本文对应的原始提示词文档均可在本仓库的 system-prompts 目录下找到技能触发描述见 skill-update-config-description.md完整配置流程见 skill-update-claude-code-config.md设置位置与 schema 见 skill-update-config-settings-file-locations.mdhook 验证流程见 skill-update-config-7-step-verification-flow.mdhook 结构细节见 system-prompt-hooks-configuration.md。这些文件是随 Claude Code 版本更新而维护的第一手配置契约也是排查与学习的最佳参照。赞分享文档提示工程人工智能【免费下载链接】claude-code-system-promptsAll parts of Claude Codes system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.项目地址https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts点击查看免费下载相关推荐Claude Code settings.json 完全配置指南解析 update-config Skill 的权限、Hooks 与全量 SchemaClaude Code settings.json 完全配置指南解析 update config Skill 的权限、Hooks 与全量 Schema 本篇技文档知识库Claude Code settings.json 配置修改完全指南hooks、权限与环境变量的正确姿势Claude Code settings.json 配置修改完全指南hooks、权限与环境变量的正确姿势 Claude Code 的自动化行为hooks、文档提示工程人工智能Claude Code settings.json 配置权威指南140 设置项与 315 环境变量的实战参考claude-code-best-practiceClaude Code settings.json 配置权威指南140 设置项与 315 环境变量的实战参考claude code best pract文档教程AI 技能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Claude Code settings.json 配置指南：hooks、权限与环境变量的 update-config 技能全解析
文档提示工程人工智能【免费下载链接】claude-code-system-promptsAll parts of Claude Codes system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.项目地址https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts点击查看免费下载本文基于 Claude Code System Prompts 仓库中内置的 update-config 技能族文档撰写。该技能负责通过settings.json配置 Claude Code 运行框架harness的自动化行为hooks、工具权限permissions与运行环境env并给出了从构造 → 管道测试 → 写入 → 校验 → 证明生效的完整闭环流程。读完本文你将掌握三类配置的落盘位置与作用域优先级、hook 事件与 matcher 的精确写法、权限规则的语法边界以及如何用 7 步验证流程确保一条 hook 在真实项目中确实被触发且按预期工作。一、update-config 技能是做什么的在 Claude Code 的提示词体系中skill-update-config-description.md 是Update config技能的触发描述frontmatterdescription字段。它界定了这个技能的适用范围配置 Claude Code 的 settings.json 文件。它的职责被明确划分为三类Hooks自动化行为凡是从现在起当 X 发生时每次 X 时每当 X 时在 X 之前/之后这类表述都必须通过 settings.json 中配置的 hooks 实现。Permissions权限允许 X添加权限把权限移动到……等表述。Env vars环境变量设置 XY。一个关键设计判断是自动化行为必须由 harness运行框架执行而不是由 Claude 的记忆/偏好执行。因为 Claude 只在会话中活动而 hook 是挂在工具调用生命周期上的框架级回调——Claude 停止输出后hook 依然会在事件发生时被框架执行。因此记忆memory无法替代 hooks 来实现自动化触发。该技能的典型触发示例来自原文档allow npm commands允许 npm 命令add bq permission to global settings向全局设置添加 bq 权限move permission to user settings把权限移动到用户设置set DEBUGtrue设置环境变量when claude stops show XClaude 停止时显示 X同时文档也给出了边界判断对于theme、model这类简单设置应建议用户直接使用/config斜杠命令而不是手动改文件。完整的决策逻辑参见 skill-update-claude-code-config.md。二、settings.json 的存储位置与作用域优先级在动手配置之前必须先确定改哪个文件。根据 skill-update-config-settings-file-locations.mdClaude Code 的设置在三个作用域分布文件作用域Git 策略用途~/.claude/settings.json全局Global不适用所有项目的个人偏好.claude/settings.json项目Project提交Commit团队级 hooks、权限、插件.claude/settings.local.json项目Project加入 .gitignore该项目下的个人覆盖加载顺序user → project → local后者覆盖前者。也就是说.claude/settings.local.json的优先级最高适合放个人私有覆盖.claude/settings.json适合随仓库提交、让团队共享的配置~/.claude/settings.json则承载跨项目的全局偏好。这里有一个与 update-config 技能强相关的实践细节当首次创建.claude/settings.local.json时应主动将其加入.gitignore——因为 Write 工具不会自动为它添加 gitignore 规则该提醒来自 skill-update-config-7-step-verification-flow.md 第 4 步。三、核心配置 Schema 参考settings.json 是严格的 JSON 文件不支持//注释与尾随逗号下面按配置块逐一展开以下 schema 均继承自 skill-update-config-settings-file-locations.md。3.1 Permissions权限{ permissions: { allow: [Bash(npm *), Edit(.claude), Read], deny: [Bash(rm -rf *)], ask: [Edit(//etc/*)], defaultMode: default | plan | acceptEdits | dontAsk, additionalDirectories: [/extra/dir] } }权限规则Permission Rule语法有四种形态精确匹配Bash(npm run test)—— 只匹配这一条命令前缀通配Bash(git *)—— 匹配git、git status、git commit等一切以git开头的命令注意*前的空格是前缀匹配正确工作的必要条件仅工具名Read—— 放行该工具的全部操作文件路径规则Edit(src/**)—— 在permissions中路径规则统一用Edit(path)表示所有写文件工具Write、Edit、NotebookEdit用Read(path)表示读取。特别需要注意的是Write(path)、NotebookEdit(path)、Glob(path)这类规则不参与文件权限检查裸工具名如Write、deny/ask 形式的Tool(param:value)规则以及 hook 的if条件仍然使用各工具自己的名称。3.2 Environment Variables环境变量{ env: { DEBUG: true, MY_API_KEY: value } }env 块是一个键值对象用于为会话注入环境变量。技能文档中的典型场景就是set DEBUGtrue。3.3 Model Agent模型与代理{ model: sonnet, agent: agent-name, alwaysThinkingEnabled: true }model可取sonnet、fable、opus、haiku或完整的模型 ID。这类设置属于简单设置按技能建议优先引导用户走/config命令。3.4 Attribution提交与 PR 署名{ attribution: { commit: Custom commit trailer text, pr: Custom PR description text } }将commit或pr设为空字符串可隐藏对应署名要全部隐藏需两者都设为并额外设置sessionUrl: false。必须写成对象形式不能写成attribution: false旧版 Claude Code 会拒绝 true/false 布尔值并跳过整个 settings 文件。3.5 MCP Server 管理{ enableAllProjectMcpServers: true, enabledMcpjsonServers: [server1, server2], disabledMcpjsonServers: [blocked-server] }3.6 Plugins插件{ enabledPlugins: { formatteranthropic-tools: true } }插件语法为plugin-namesource其中source取claude-code-marketplace、claude-plugins-official或builtin之一。3.7 其他常用设置language首选回复语言如japanesecleanupPeriodDays会话转录自动清理保留天数默认 30最小 1respectGitignore是否尊重 .gitignore默认 truespinnerTipsEnabledspinner 中是否显示提示timeFormatUI 时钟格式auto默认、12-hour、24-hour、24-hour-utc或 strftime 模式如%H:%MtimeZoneIANA 时区默认系统时区如UTCspinnerVerbs自定义 spinner 动词{ mode: append | replace, verbs: [...] }spinnerTipsOverride覆盖 spinner 提示{ excludeDefault: true, tips: [Custom tip] }syntaxHighlightingDisabled禁用 diff 高亮。四、Hooks自动化行为的核心机制update-config 技能最重要的应用场景是配置 hooks。Hook 在 Claude Code 生命周期的特定节点执行命令是唯一能实现框架级自动化的机制。完整结构参考 system-prompt-hooks-configuration.md。4.1 Hook 结构{ hooks: { EVENT_NAME: [ { matcher: ToolName|OtherTool, hooks: [ { type: command, command: your-command-here, timeout: 60, statusMessage: Running... } ] } ] } }结构分三层事件 → matcher匹配器→ hooks 数组。每个 hook 条目支持type、command、timeout超时秒数、statusMessage执行时显示的状态消息等字段。4.2 Hook 事件与 Matcher事件Matcher用途PermissionRequest工具名权限提示弹出前运行PreToolUse工具名工具调用前运行可以阻止调用PostToolUse工具名工具成功调用后运行PostToolUseFailure工具名工具调用失败后运行Notification通知类型收到通知时运行Stop-Claude 停止时运行包括 clear、resume、compactPreCompactmanual/auto压缩会话上下文之前PostCompactmanual/auto压缩之后会收到摘要UserPromptSubmit-用户提交提示时SessionStart-会话启动时常见工具 matcherBash、Write、Edit、Read、Glob、Grep可用|组合如Write|Edit。4.3 Hook 类型Command Hook命令型运行一条 shell 命令{ type: command, command: prettier --write $FILE, timeout: 30 }Prompt Hook提示型用 LLM 评估条件仅可用于工具事件PreToolUse、PostToolUse、PermissionRequest{ type: prompt, prompt: Is this safe? $ARGUMENTS }Agent Hook代理型运行一个带工具的 agent同样仅限工具事件{ type: agent, prompt: Verify tests pass: $ARGUMENTS }4.4 Hook 的标准输入stdin JSONHook 命令通过 stdin 接收 JSON 载荷{ session_id: abc123, tool_name: Write, tool_input: { file_path: /path/to/file.txt, content: ... }, tool_response: { success: true } }其中tool_response仅 PostToolUse 提供。这正是构造 hook 命令时需要用jq -r安全提取字段的原因。4.5 Hook 的 JSON 输出控制行为Hook 可以输出 JSON 来控制 Claude Code 的行为{ systemMessage: Warning shown to user in UI, continue: false, stopReason: Message shown when blocking, suppressOutput: false, decision: block, reason: Explanation for decision, hookSpecificOutput: { hookEventName: PostToolUse, additionalContext: Context injected back to model } }字段语义systemMessage向用户显示消息所有 hook 可用continue设为false即阻止/停止默认 truestopReasoncontinue为 false 时显示的消息suppressOutput从转录中隐藏 stdout默认 falsedecisionPostToolUse/Stop/UserPromptSubmit 事件取block对 PreToolUse 已废弃改用hookSpecificOutput.permissionDecisionreason决策的解释hookSpecificOutput事件专属输出必须包含hookEventNameadditionalContext注入模型上下文的文本permissionDecisionallow/deny/ask仅 PreToolUsepermissionDecisionReason权限决策原因仅 PreToolUseupdatedInput修改后的工具输入仅 PreToolUse。4.6 三个常见实战模式自动格式化PostToolUse Write|Edit{ hooks: { PostToolUse: [{ matcher: Write|Edit, hooks: [{ type: command, command: jq -r .tool_response.filePath // .tool_input.file_path | { read -r f; prettier --write \$f\; } 2/dev/null || true }] }] } }记录所有 bash 命令PreToolUse Bash{ hooks: { PreToolUse: [{ matcher: Bash, hooks: [{ type: command, command: jq -r .tool_input.command ~/.claude/bash-log.txt }] }] } }代码变更后运行测试PostToolUse Write|Edit{ hooks: { PostToolUse: [{ matcher: Write|Edit, hooks: [{ type: command, command: jq -r .tool_input.file_path // .tool_response.filePath | grep -E \\.(ts|js)$ npm test || true }] }] } }五、什么必须用 Hook什么不能用记忆替代skill-update-claude-code-config.md 用一个清晰的判断框定了使用边界只要用户想要的是响应某个事件自动发生的事情就需要 hook记忆/偏好无法触发自动化动作。必须使用 hook 的典型需求压缩上下文前问我保留什么 →PreCompacthook写完文件后运行 prettier →PostToolUsehookmatcher 为Write|Edit我运行 bash 命令时记录它们 →PreToolUsehookmatcher 为Bash代码变更后总是运行测试 →PostToolUsehookHook 事件全集PreToolUse、PostToolUse、PreCompact、PostCompact、Stop、Notification、SessionStart再加上 PermissionRequest、PostToolUseFailure、UserPromptSubmit 等见上文事件表。六、配置工作流与合并铁律6.1 标准工作流澄清意图Clarify intent请求含糊时先用 AskUserQuestion 澄清——改哪个设置文件user/project/local、是追加到现有数组还是替换、多个可选值时取哪个具体值先读后写Read existing file改动前必须读取目标 settings 文件小心合并Merge carefully保留已有设置尤其是数组编辑文件Edit file用 Edit 工具修改文件不存在时先请用户创建确认Confirm告知用户改了什么。6.2 合并数组正确与错误示范错误做法覆盖了已有权限{ permissions: { allow: [Bash(npm *)] } }正确做法保留既有 追加新项{ permissions: { allow: [ Bash(git *), // 已有 Edit(.claude), // 已有 Bash(npm *) // 新增 ] } }6.3 /config 命令 vs 直接编辑的选择建议/config命令处理的简单设置theme、editorMode、verbose、model、language、alwaysThinkingEnabled、permissions.defaultMode。应直接编辑 settings.json的复杂配置hooksPreToolUse、PostToolUse 等、复杂权限规则allow/deny 数组、环境变量、MCP server 配置、插件配置。七、构造并验证 Hook 的 7 步流程这是 update-config 技能族中最具工程价值的流程出自 skill-update-config-7-step-verification-flow.md。给定事件、matcher、目标文件和期望行为按以下步骤执行——每一步捕获一类不同的失败一条静默不做任何事的 hook 比没有 hook 更糟。去重检查Dedup check读取目标文件。若同一 eventmatcher 上已存在 hook展示现有命令并询问保留、替换、还是并列添加。为当前项目构造命令——不要臆断hook 从 stdin 接收 JSON。构造命令时要安全提取所需载荷——用jq -r存入带引号的变量或用{ read -r f; ... $f; }不要用不带引号的| xargs它会按空格拆分以本项目实际运行工具的方式调用npx/bunx/yarn/pnpmMakefile 目标还是全局安装跳过工具不处理的输入格式化器通常有--ignore-unknown没有的话按扩展名做守卫先保持 RAW 状态——不加|| true、不抑制 stderr等管道测试通过后再包裹。管道测试原始命令Pipe-test合成 hook 将收到的 stdin 载荷直接管道输入Pre|PostToolUse作用于Write|Editecho {tool_name:Edit,tool_input:{file_path:仓库里的真实文件}} | cmdPre|PostToolUse作用于Bashecho {tool_name:Bash,tool_input:{command:ls}} | cmdStop/UserPromptSubmit/SessionStart多数命令不读 stdinecho {} | cmd即可。同时检查退出码和副作用文件是否真的被格式化、测试是否真的运行了。失败就得到真实报错——修复包管理器选错了工具没装jq 路径不对后重测。通过后再用2/dev/null || true包裹除非用户想要阻塞式检查。写入 JSON合并进目标文件schema 结构见上文Hook 结构。若首次创建.claude/settings.local.json记得加入 .gitignore。一次校验语法 schemajq -e .hooks.event[] | select(.matcher matcher) | .hooks[] | select(.type command) | .command target-file退出 0 并打印出命令 正确退出 4 matcher 不匹配退出 5 JSON 畸形或嵌套错误。注意一个损坏的 settings.json 会静默禁用该文件里的所有设置——文件中既有的任何畸形也一并修复。证明 hook 确实触发仅对可在当前回合触发的Pre|PostToolUsematcher 执行Write|Edit用 Edit 触发Bash用 Bash 触发。Stop/UserPromptSubmit/SessionStart在本回合之外触发直接跳到第 7 步。对PostToolUse/Write|Edit上的格式化器通过 Edit 引入一个可被该格式化器修正的违规连续两个空行、错误缩进、缺失分号——注意不要用尾部空白Edit 写入前会剥离它重新读取确认 hook 已修复它对其他任何 hook临时在 settings.json 的命令前加echo $(date) hook fired /tmp/claude-hook-check.txt;触发对应工具Write|Edit用 Edit、Bash用无害的true读取哨兵文件。无论通过与否都要清理——还原违规、去掉哨兵前缀。若证明失败但管道测试和jq -e都通过了说明 settings 监视器没有监视.claude/目录——它只监视本次会话启动时已存在设置文件的目录。hook 本身写得没错告诉用户打开一次设置菜单重新加载配置或重启你无法自己完成这一步。交接Handoff告诉用户 hook 已生效或按监视器注意事项需要重载/重启并告知他们以后可在设置文件中查看、编辑或禁用它。UI 只在 hook 报错或过慢时显示 Ran N hooks——静默成功在设计上就是不可见的。八、常见错误与 Hook 排障8.1 常见错误来自技能文档替换而非合并——必须始终保留既有设置改错文件——作用域不明时先问用户无效 JSON——改完必须校验语法忘记先读后写——写之前永远先读。8.2 Hook 不运行的排障清单检查设置文件——读~/.claude/settings.json或.claude/settings.json验证 JSON 语法——无效 JSON 会静默失败检查 matcher——是否匹配工具名如Bash、Write、Edit检查 hook 类型——是command、prompt还是agent手动测试命令——单独运行 hook 命令看是否工作使用--debug——运行claude --debug查看 hook 执行日志。九、权限配置的进阶参考从转录生成 allowlistupdate-config 技能生态中还有一个高度相关的配套技能——skill-generate-permission-allowlist-from-transcripts.md它演示了权限规则语法在真实场景中的运用权限格式Bash(foo*)、Bash(foo)、Bash(foo bar *)、mcp__slack__slack_read_thread等会话转录位于~/.claude/projects/sanitized-cwd/*.jsonl可据此统计高频只读工具调用生成去重后的permissions.allow追加列表该文档同时强调了一条与 update-config 强相关的安全红线永远不要 allowlist 一个会授予任意代码执行的模式——解释器python/node/bun/ruby/php 等、shellbash/sh/zsh/ssh 等、包运行器npx/bunx/uvx 等、任务运行器通配npm run *、make *等、gh api *、docker run/exec、sudo等一律排除精确形式如Bash(bun run typecheck)可以Bash(bun run *)不可以。十、结语从文档到可验证的工程实践update-config 技能的核心价值在于它不只是改文件而是给出了一个可验证的配置闭环先确定作用域user/project/local再判断该走/config还是直接编辑对 hooks 走构造 → 管道测试 → 写入 → jq 校验 → 证明触发 → 交接的 7 步流程对权限牢记合并不覆盖最窄模式禁止任意代码执行三条铁律最后用claude --debug兜底排障。这套方法论可以直接迁移到任何使用 settings.json 驱动 agent harness 的场景中。本文对应的原始提示词文档均可在本仓库的 system-prompts 目录下找到技能触发描述见 skill-update-config-description.md完整配置流程见 skill-update-claude-code-config.md设置位置与 schema 见 skill-update-config-settings-file-locations.mdhook 验证流程见 skill-update-config-7-step-verification-flow.mdhook 结构细节见 system-prompt-hooks-configuration.md。这些文件是随 Claude Code 版本更新而维护的第一手配置契约也是排查与学习的最佳参照。赞分享文档提示工程人工智能【免费下载链接】claude-code-system-promptsAll parts of Claude Codes system prompt, 27 builtin tool descriptions, sub agent prompts (Plan/Explore/Task), utility prompts (CLAUDE.md, compact, statusline, magic docs, WebFetch, Bash cmd, security review, agent creation). Updated for each Claude Code version.项目地址https://gitcode.com/gh_mirrors/cl/claude-code-system-prompts点击查看免费下载相关推荐Claude Code settings.json 完全配置指南解析 update-config Skill 的权限、Hooks 与全量 SchemaClaude Code settings.json 完全配置指南解析 update config Skill 的权限、Hooks 与全量 Schema 本篇技文档知识库Claude Code settings.json 配置修改完全指南hooks、权限与环境变量的正确姿势Claude Code settings.json 配置修改完全指南hooks、权限与环境变量的正确姿势 Claude Code 的自动化行为hooks、文档提示工程人工智能Claude Code settings.json 配置权威指南140 设置项与 315 环境变量的实战参考claude-code-best-practiceClaude Code settings.json 配置权威指南140 设置项与 315 环境变量的实战参考claude code best pract文档教程AI 技能创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考