scaffold-cc-hooks

scaffold-cc-hooks

先审计目标项目，再以确定性的 bash 优先布局搭建 Claude Code hooks。

决策树

用户想做什么？

• 在尚未设置 hook 的项目中新增 Claude Code hooks： 先实时验证文档，审计项目，选择 hook 方案，然后搭建。
• 已有 .claude/settings*.json 或 .claude/hooks/ 文件： 审计现有内容，选择 additive 或 overhaul，然后仅重新生成受管理的 hook 层。
• 已有 hooks 会显示在 /hooks 中，但从未实际触发： 首先将工作区信任作为诊断重点。在排查设置或脚本逻辑前，检查 ~/.claude.json 中是否存在准确的项目路径；如果信任仍处于关闭状态，再提供启用信任的选项。
• 已有 hooks，且 Claude Code 功能可能发生变化： 写入文件前，先验证实时的官方 hook 事件列表。如果文档已更改，先更新搭建所需的输入。
• 仅需说明，不需要实现： 阅读 references/hook-events.md 和 references/scaffold-layout.md，然后直接回答，不要搭建。

快速参考

任务	操作
验证当前官方 hook 模型	阅读实时官方文档 https://code.claude.com/docs/en/hooks 和 https://code.claude.com/docs/en/hooks-guide，然后与 assets/hook-events.json 对照
审计目标仓库	运行 scripts/audit_project.sh /path/to/project
检查 Claude Code 是否信任目标工作区	运行 scripts/check_workspace_trust.sh /path/to/project --json
为目标工作区启用信任	运行 scripts/check_workspace_trust.sh /path/to/project --enable
了解事件目录	阅读 references/hook-events.md
设计可复用的仓库自有脚本	阅读 references/reusable-scripts.md
决定采用追加还是全面替换	阅读 references/merge-strategy.md
生成或刷新受管理的 hook 搭建内容	运行 `scripts/scaffold_hooks.sh --project /path/to/project --plan /path/to/plan.json --mode additive
将生成的 hooks 合并到设置中	让 scripts/scaffold_hooks.sh 调用 scripts/merge_settings.sh，或直接运行合并脚本
在目标项目中重新生成 hooks README	运行 scripts/render_hooks_readme.sh --project /path/to/project --plan /path/to/plan.json

不可妥协的工作流

1. 在规划任何脚手架之前，先核实 Claude Code 官方钩子文档的最新内容。
2. 将最新的事件列表、钩子类型支持情况和异步规则与 assets/hook-events.json 进行比较。
3. 在决定启用哪些事件之前，详细审查目标项目。
4. 在选择合并模式之前，检查现有的 .claude/settings.json、.claude/settings.local.json、.claude/hooks/、CLAUDE.md、.claude/rules/ 以及相关自动化文件。
5. 生成或更新具体的钩子计划 JSON。将项目特定的判断放入计划中，而不是脚手架脚本中，以保持脚手架的确定性。
6. 对于可能迁移到 Codex、OpenCode、Git 钩子、GitHub Actions 或本地 shell 用法的行为，优先使用仓库自有的共享脚本。将生成的 Claude 钩子文件保留为这些脚本的轻量适配器。
7. 在受管理的钩子根目录下，为所有当前钩子事件生成带注释的 bash 桩，即使该事件在设置中保持禁用。
8. 只将已启用的事件写入所选设置文件，避免项目为未启用的桩产生运行时开销。
9. 重新生成 .claude/hooks/README.md，确保项目始终有易读的事件映射。
10. 如果用户报告钩子已注册但未触发，或者你刚完成了实际的脚手架搭建、需要验证设置，请在调试钩子逻辑之前检查或明确提出检查确切项目路径的工作区信任状态。
11. 如果信任已禁用，请说明该项目的 hasTrustDialogAccepted 为 false。向用户提供两种恢复方式：在新的 Claude Code 会话中接受对话框，或直接修改该标志。只有在用户要求你这么做或明确要求你确保信任已启用时，才修改 ~/.claude.json。

优先检查信任的启发式规则

出现以下任一情况时，默认尽早检查信任状态：

• 用户表示钩子未激活、未触发或被忽略
• /hooks 显示已注册处理程序，数量符合预期，但没有任何内容执行
• 钩子脚本手动运行正常，但 Claude Code 从未调用它们
• 你刚搭建完钩子，用户希望确认它们确实有效

按以下流程操作：

1. 先规范化目标路径。信任状态与确切的绝对项目路径关联。
2. 运行 scripts/check_workspace_trust.sh /path/to/project --json。
3. 如果状态为 untrusted，告知用户该标志为 false，并询问是否要启用。
4. 如果用户希望修复，运行 scripts/check_workspace_trust.sh /path/to/project --enable。
5. 只有确认信任状态后，才花时间调试设置合并、钩子匹配器、脚本权限或钩子逻辑。

优先查阅最新文档

Claude Code 官方文档是权威来源：

• https://code.claude.com/docs/en/hooks
• https://code.claude.com/docs/en/hooks-guide

仅将以下两篇 reading.sh 文章作为实践模式和权衡说明的辅助资料：

• https://reading.sh/claude-code-hooks-a-bookmarkable-guide-to-git-automation-11b4516adc5d
• https://reading.sh/claude-code-async-hooks-what-they-are-and-when-to-use-them-61b21cd71aad

如果官方文档与辅助文章存在冲突，请遵循官方文档并更新本地参考资料。

渐进式维护者漂移检查

更新此技能本身时，应将文档漂移检查作为维护的第一步：

1. 在编辑当天实时获取 Claude Code 官方文档，然后将当前事件列表、处理程序类型、匹配器规则、输入／输出契约、异步行为和信任行为与 assets/hook-events.json 进行比较。
2. 在有相关证据时检查本地版本信息，例如 claude --version，并记录能够说明此次更新的来源或文档日期。
3. 如果存在漂移，应一并更新整个脚手架范围：assets/hook-events.json、references/hook-events.md、脚手架生成器、模板、计划示例、验证器、测试、评估和轻量封装。
4. 如果不存在漂移，仍要说明已检查实时文档。不得凭记忆更新此技能，也不得照搬对 Codex 或 OpenCode 的假设。

项目分析规则

选择任何钩子结构之前，请检查：

• 仓库根目录和工作区结构
• Claude Code 将信任的确切绝对项目路径，因为信任按路径记录在 ~/.claude.json 中
• 语言和包管理器
• 构建、测试、Lint 和格式化的入口
• 现有的仓库自有命令入口，例如任务运行器、包脚本、仓库文档中记录的框架命令、CI 作业、Make／Just／Taskfile 目标和本地脚本
• 可复用的 Agent 或自动化脚本，例如 <project>/scripts/agent-session-context.sh、<project>/scripts/agent-stop-checks.sh、适配器脚本、Husky 钩子和 GitHub Actions 作业；这些应共享逻辑
• Turborepo、Nx、pnpm workspaces、Bun workspaces 或自定义任务运行器等 monorepo 工具
• 现有的 Claude Code 设置、规则、钩子、插件和技能
• 现有的 Git 钩子、Husky、Lefthook 或 CI 门禁
• .env、密钥、迁移、锁文件、生成代码和基础设施目录等敏感路径
• direnv、.envrc 或按目录配置工具等环境重新加载需求

先运行 scripts/audit_project.sh，需要完整检查清单时再阅读 references/project-analysis.md。

确定性与项目特定的工作

以下部分应保持确定性：

• 受管理的钩子根路径
• 事件存根文件名
• 生成的设置片段结构
• 对先前受管理钩子的合并行为
• 钩子 README 生成
• 覆盖所有当前官方钩子事件的事件清单

以下部分可保持项目特定：

• 启用哪些事件
• 事件匹配器
• 同步或异步的选择
• 工具事件上的 if 过滤条件
• 超时设置
• 事件在运行自定义钩子逻辑前应运行的已配置仓库命令
• 事件在运行自定义钩子逻辑前应委托执行的可复用仓库自有脚本
• 已启用事件脚本中的实际逻辑
• 刷新采用 additive 还是 overhaul 模式

重复运行规则

再次对某个项目调用此技能时：

• 重新实时验证文档，再假定事件集未发生变化。
• 重新审计项目，再假定当前钩子计划仍适用。
• 如果用户表示钩子从未触发，或脚手架需要验证，应先重新检查确切项目路径的工作区信任，再假定生成的设置有误。
• 默认保留非受管理的钩子。
• 在 overhaul 模式下，将受管理根目录中先前生成的钩子视为可替换。
• 在 additive 模式下，将先前生成的钩子视为仅追加；但缺少事件或 README 过时需要刷新时除外。
• 如果出现新的官方钩子事件，即使项目仍禁用这些事件，也要添加新的存根和 README 条目。

脚手架规则

• 为项目钩子运行时生成 bash 脚本，而不是 Python 脚本。
• 使用通俗易懂的语言为生成的 bash 存根添加注释。
• 将生成的事件脚本构建为 main() 加一个 handle_event() 编辑点，让人类和 Agent 能快速看清控制流。
• 在钩子计划中支持与语言无关的 scripts 条目，用于可复用的仓库自有脚本；也支持 commands 条目，用于现有仓库命令。不要在生成的脚本中硬编码包管理器、框架或示例工具链。
• 将共享行为放在与路径无关的仓库脚本中，通常位于 scripts/ 下；当输出协议不同时，传入 claude 之类的 harness 参数。生成的事件存根应保持精简。
• 在生成的命令路径中使用 $CLAUDE_PROJECT_DIR。
• 默认将 .claude/hooks/generated 作为托管根目录，除非项目已有更合适的约定。
• 如果钩子设置应当共享，默认使用 .claude/settings.json。仅当项目需要机器本地行为或已有此惯例时，才使用 .claude/settings.local.json。
• 每个事件只保留一个托管脚本，让事件映射一目了然。
• 合并后的设置应保持确定性：只移除先前托管的处理程序，绝不移除无关的自定义钩子。

阅读指南

需求	阅读
完整的审计清单和优先检查事项	references/project-analysis.md
当前官方事件列表和支持矩阵	references/hook-events.md
托管文件夹布局和计划文件结构	references/scaffold-layout.md
在 Claude Code、Codex、OpenCode、Git 钩子和 CI 之间放置可复用脚本	references/reusable-scripts.md
增量添加与全面改造行为	references/merge-strategy.md
async、if、shell 和设置方面的注意事项	references/gotchas.md

运维脚本

• scripts/audit_project.sh 根据仓库中的真实信号构建项目概况。
• scripts/check_workspace_trust.sh 检查或启用指定项目路径的 Claude Code 工作区信任。
• scripts/scaffold_hooks.sh 生成托管钩子树、清单、README 和设置片段。
• scripts/merge_settings.sh 保留非托管钩子，同时替换先前托管的处理程序。
• scripts/render_hooks_readme.sh 根据清单和当前计划重新生成 .claude/hooks/README.md。

注意事项

1. async 仅适用于命令钩子；异步钩子无法在触发操作完成后阻止 Claude 或影响其行为。
2. if 字段仅适用于工具事件，且要求 Claude Code v2.1.85 或更高版本。
3. Stop 钩子可能会无限循环，除非你正确处理 stop_hook_active。
4. 钩子的 shell 是非交互式的。Shell 配置文件中的噪声可能会破坏 JSON 输出。
5. 在非交互式 -p 模式下不会触发 PermissionRequest。
6. 钩子不会在不受信任的工作区中触发。Claude Code 会依据 ~/.claude.json 中 .projects["/absolute/path/to/project"] 下的 hasTrustDialogAccepted 来控制执行。如果钩子看似已安装却从未运行，或完成实际脚手架生成后出现此情况，请先使用 scripts/check_workspace_trust.sh 检查信任状态，再归咎于钩子配置。确切的恢复流程请参阅 references/gotchas.md 中的注意事项 9。
7. 不要将可复用的验证或上下文逻辑埋在生成的 .claude/hooks/generated/events/*.sh 文件中。应将其放在仓库自有脚本中，并让 Claude 钩子将这些脚本作为适配器调用。