scaffold-cc-hooks

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

scaffold-cc-hooks

Audit the target project first, then scaffold Claude Code hooks with a deterministic bash-first layout.

先审核目标项目，然后以确定性的bash优先布局搭建Claude Code钩子。

Decision Tree

决策树

What is the user asking for?

New Claude Code hooks in a project with no hook setup yet: Run live docs verification, audit the project, choose a hook plan, then scaffold.
Existing
```
.claude/settings*.json
```
or
```
.claude/hooks/
```
files: Audit what already exists, choose
```
additive
```
or
```
overhaul
```
, then regenerate only the managed hook layer.
Existing hooks that show up in
```
/hooks
```
but never actually fire: Treat workspace trust as the first diagnostic. Check
```
~/.claude.json
```
for the exact project path before debugging settings or script logic, then offer to enable trust if it is still off.
Existing hooks plus possible Claude Code feature drift: Verify the live official hook event list before writing files. If the docs changed, update the scaffold inputs first.
Explanation only, not implementation: Read
```
references/hook-events.md
```
and
```
references/scaffold-layout.md
```
, then answer without scaffolding.

用户的需求是什么？

项目尚未设置钩子，需要新增Claude Code钩子：执行实时文档验证，审核项目，选择钩子方案，然后搭建脚手架。
已存在
```
.claude/settings*.json
```
或
```
.claude/hooks/
```
文件：审核现有内容，选择「增量式（additive）」或「全面重构（overhaul）」模式，然后仅重新生成托管钩子层。
```
/hooks
```
目录下存在钩子但从未触发：首先诊断工作区信任问题。在调试设置或脚本逻辑前，检查
```
~/.claude.json
```
中的精确项目路径，若信任未开启则提供启用选项。
已有钩子但可能存在Claude Code功能漂移：在编写文件前先验证官方实时钩子事件列表。若文档有更新，先更新脚手架输入内容。
仅需解释无需实现：阅读
```
references/hook-events.md
```
和
```
references/scaffold-layout.md
```
，然后直接解答，无需搭建脚手架。

Quick Reference

快速参考

Task	Action
Verify the current official hook model	Read the live official docs at `https://code.claude.com/docs/en/hooks` and `https://code.claude.com/docs/en/hooks-guide` , then compare them to `assets/hook-events.json`
Audit a target repo	Run `scripts/audit_project.sh /path/to/project`
Check whether Claude Code trusts the target workspace	Run `scripts/check_workspace_trust.sh /path/to/project --json`
Enable workspace trust for the target workspace	Run `scripts/check_workspace_trust.sh /path/to/project --enable`
Understand the event catalog	Read `references/hook-events.md`
Decide additive vs overhaul	Read `references/merge-strategy.md`
Generate or refresh the managed hook scaffold	Run `scripts/scaffold_hooks.sh --project /path/to/project --plan /path/to/plan.json --mode additive
Merge generated hooks into settings	Let `scripts/scaffold_hooks.sh` call `scripts/merge_settings.sh` , or run the merge script directly
Regenerate the hooks README in a target project	Run `scripts/render_hooks_readme.sh --project /path/to/project --plan /path/to/plan.json`

任务	操作
验证当前官方钩子模型	读取官方实时文档 `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/merge-strategy.md`
生成或刷新托管钩子脚手架	运行 `scripts/scaffold_hooks.sh --project /path/to/project --plan /path/to/plan.json --mode additive
将生成的钩子合并到设置中	让 `scripts/scaffold_hooks.sh` 调用 `scripts/merge_settings.sh` ，或直接运行合并脚本
在目标项目中重新生成钩子README	运行 `scripts/render_hooks_readme.sh --project /path/to/project --plan /path/to/plan.json`

Non-Negotiable Workflow

不可妥协的工作流程

Verify the live official Claude Code hook docs before planning any scaffold.
Compare the live event list, hook type support, and async rules with
```
assets/hook-events.json
```
.
Audit the target project in detail before deciding which events to enable.

Inspect any existing

.claude/settings.json

.claude/settings.local.json

.claude/hooks/

CLAUDE.md

.claude/rules/

, and related automation files before choosing a merge mode.

Produce or update a concrete hook plan JSON. Keep the scaffold deterministic by putting project-specific judgment into the plan, not into the scaffold script.
Scaffold every current hook event as a commented bash stub under the managed hook root, even if the event stays disabled in settings.
Wire only the enabled events into the chosen settings file so the project does not pay runtime cost for inactive stubs.
Regenerate
```
.claude/hooks/README.md
```
so the project always has a readable event map.
If the user reports that hooks are registered but not firing, or you just completed a real scaffold and need to verify the setup, check or explicitly offer to check workspace trust for the exact project path before debugging hook logic.
If trust is disabled, explain that
```
hasTrustDialogAccepted
```
is false for that project. Offer the user two recovery paths: accept the dialog in a fresh Claude Code session, or flip the flag directly. Only mutate
```
~/.claude.json
```
when the user asks you to do so or explicitly asks you to ensure trust is enabled.

在规划任何脚手架之前，先验证官方Claude Code钩子的实时文档。
将实时事件列表、钩子类型支持和异步规则与
```
assets/hook-events.json
```
进行对比。
在决定启用哪些事件之前，详细审核目标项目。
在选择合并模式之前，检查所有现有
```
.claude/settings.json
```
、
```
.claude/settings.local.json
```
、
```
.claude/hooks/
```
、
```
CLAUDE.md
```
、
```
.claude/rules/
```
及相关自动化文件。
生成或更新具体的钩子方案JSON。通过将项目特定判断放入方案而非脚手架脚本，保持脚手架的确定性。
在托管钩子根目录下为当前每个钩子事件生成带注释的bash存根，即使该事件在设置中保持禁用状态。
仅将启用的事件接入所选设置文件，避免项目为非活动存根支付运行时成本。
重新生成
```
.claude/hooks/README.md
```
，确保项目始终拥有可读的事件映射。
如果用户反馈钩子已注册但未触发，或者你刚完成实际搭建并需要验证设置，请先检查或主动提出检查对应项目路径的工作区信任，再调试钩子逻辑。
如果信任已禁用，说明该项目的
```
hasTrustDialogAccepted
```
为false。为用户提供两种恢复路径：在新的Claude Code会话中接受信任弹窗，或直接修改该标志。仅当用户明确要求或确认需要启用信任时，才修改
```
~/.claude.json
```
。

Trust First Heuristic

优先信任启发式规则

Default to a trust check early when any of these signals appear:

the user says hooks are not activating, not firing, or being ignored
```
/hooks
```
shows registered handlers with the expected counts, but nothing executes
the hook scripts work when run by hand, but Claude Code never invokes them
you just scaffolded hooks and the user wants you to confirm they actually work

Use this flow:

Canonicalize the target path first. Trust is keyed by the exact absolute project path.

Run

scripts/check_workspace_trust.sh /path/to/project --json

If status is
```
untrusted
```
, tell the user the flag is false and offer to enable it.

If the user wants it fixed, run

scripts/check_workspace_trust.sh /path/to/project --enable

Only after trust is confirmed should you spend time debugging settings merges, hook matchers, script permissions, or hook logic.

当出现以下任一信号时，默认提前进行信任检查：

用户表示钩子未激活、未触发或被忽略
```
/hooks
```
显示已注册预期数量的处理程序，但无任何执行记录
钩子脚本手动运行正常，但Claude Code从未调用
你刚搭建完钩子，用户要求确认其是否正常工作

使用以下流程：

首先规范化目标路径。信任是通过精确的绝对项目路径来关联的。

运行

scripts/check_workspace_trust.sh /path/to/project --json

。

如果状态为
```
untrusted
```
，告知用户该标志为false并提供启用选项。

如果用户需要修复，运行

scripts/check_workspace_trust.sh /path/to/project --enable

。

只有在确认信任已启用后，才花费时间调试设置合并、钩子匹配器、脚本权限或钩子逻辑。

Live Docs First

优先参考实时文档

The official Claude Code docs are the source of truth:

```
https://code.claude.com/docs/en/hooks
```

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

Use the two reading.sh articles only as secondary material for practical patterns and trade-off language:

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

If the official docs and the secondary articles disagree, follow the official docs and update the local references.

官方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

如果官方文档与次要文章存在分歧，以官方文档为准并更新本地参考资料。

Project Analysis Rules

项目分析规则

Before choosing any hook structure, inspect:

repo root and workspace shape
the exact absolute project path Claude Code will trust, because trust is keyed by path in
```
~/.claude.json
```
languages and package managers
build, test, lint, and format entry points
monorepo tools like Turborepo, Nx, pnpm workspaces, Bun workspaces, or custom task runners
existing Claude Code settings, rules, hooks, plugins, and skills
existing Git hooks, Husky, Lefthook, or CI gates
sensitive paths like
```
.env
```
, secrets, migrations, lockfiles, generated code, and infra directories
environment reload needs such as
```
direnv
```
,
```
.envrc
```
, or per-directory tooling

Run

scripts/audit_project.sh

first, then read

references/project-analysis.md

when you need the full checklist.

在选择任何钩子结构之前，检查以下内容：

仓库根目录和工作区结构
Claude Code将信任的精确绝对项目路径，因为信任在
```
~/.claude.json
```
中是通过路径关联的
编程语言和包管理器
构建、测试、代码检查和格式化入口
单体仓库工具如Turborepo、Nx、pnpm workspaces、Bun workspaces或自定义任务运行器
现有Claude Code设置、规则、钩子、插件和技能
现有Git钩子、Husky、Lefthook或CI网关
敏感路径如
```
.env
```
、密钥、迁移文件、锁文件、生成代码和基础设施目录
环境重载需求如
```
direnv
```
、
```
.envrc
```
或按目录划分的工具

先运行

scripts/audit_project.sh

，当需要完整检查清单时，阅读

references/project-analysis.md

。

Deterministic vs Project-Specific Work

确定性工作与项目特定工作

Keep these parts deterministic:

managed hook root path
event stub filenames
generated settings fragment shape
merge behavior for previously managed hooks
hooks README generation
event manifest coverage for every current official hook event

Allow these parts to stay project-specific:

which events are enabled
event matchers
sync vs async choice
```
if
```
filters on tool events
timeouts
the actual logic inside enabled event scripts
whether the refresh is
```
additive
```
or
```
overhaul
```

以下部分需保持确定性：

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

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

启用哪些事件
事件匹配器
同步与异步选择
工具事件的
```
if
```
过滤器
超时设置
启用事件脚本内的实际逻辑
刷新模式为「增量式（additive）」还是「全面重构（overhaul）」

Repeat-Run Rules

重复运行规则

When the skill is invoked again against a project:

Re-run live docs verification before assuming the event set is unchanged.
Re-audit the project before assuming the current hook plan still fits.
If the user says hooks never fire, or the scaffold needs verification, re-check workspace trust for the exact project path before assuming the generated settings are wrong.
Preserve non-managed hooks by default.
Treat previously generated hooks under the managed root as replaceable in
```
overhaul
```
mode.
Treat previously generated hooks as append-only in
```
additive
```
mode unless a missing event or stale README requires a refresh.
If new official hook events exist, add new stubs and README entries even if the project keeps them disabled.

当针对同一项目再次调用此技能时：

在假设事件集未更改之前，重新运行实时文档验证。
在假设当前钩子方案仍然适用之前，重新审核项目。
如果用户反馈钩子从未触发，或需要验证脚手架，请先重新检查对应项目路径的工作区信任，再假设生成的设置存在问题。
默认保留非托管钩子。
在「全面重构（overhaul）」模式下，将托管根目录下先前生成的钩子视为可替换。
在「增量式（additive）」模式下，将先前生成的钩子视为仅可追加，除非缺少事件或README过时需要刷新。
如果存在新的官方钩子事件，即使项目保持禁用状态，也要添加新的存根和README条目。

Scaffold Rules

脚手架规则

Generate bash scripts, not Python, for the project hook runtime.
Comment the generated bash stubs in plain language.
Use
```
$CLAUDE_PROJECT_DIR
```
in generated command paths.
Default to a managed root of
```
.claude/hooks/generated
```
unless the project already has a stronger convention.
Default to
```
.claude/settings.json
```
when the hook setup should be shared. Use
```
.claude/settings.local.json
```
only when the project needs machine-local behavior or already uses that pattern.
Keep one managed script per event so the event map stays obvious.
Keep the merged settings deterministic: remove only previously managed handlers, never unrelated custom hooks.

为项目钩子运行时生成bash脚本，而非Python脚本。
用通俗易懂的语言为生成的bash存根添加注释。
在生成的命令路径中使用
```
$CLAUDE_PROJECT_DIR
```
。
除非项目已有更明确的约定，否则默认托管根目录为
```
.claude/hooks/generated
```
。
当钩子设置需要共享时，默认使用
```
.claude/settings.json
```
。仅当项目需要机器本地行为或已使用该模式时，才使用
```
.claude/settings.local.json
```
。
每个事件对应一个托管脚本，确保事件映射清晰可见。
保持合并设置的确定性：仅移除先前托管的处理程序，绝不删除无关的自定义钩子。

Reading Guide

阅读指南

Need	Read
Full audit checklist and what to inspect first	`references/project-analysis.md`
Current official event list and support matrix	`references/hook-events.md`
Managed folder layout and plan file shape	`references/scaffold-layout.md`
Additive versus overhaul behavior	`references/merge-strategy.md`
Async, `if` , shell, and settings pitfalls	`references/gotchas.md`

需求	阅读内容
完整审核清单及优先检查项	`references/project-analysis.md`
当前官方事件列表和支持矩阵	`references/hook-events.md`
托管文件夹布局和方案文件结构	`references/scaffold-layout.md`
增量式与全面重构模式的行为差异	`references/merge-strategy.md`
异步、 `if` 、shell和设置相关的陷阱	`references/gotchas.md`

Operational Scripts

操作脚本

```
scripts/audit_project.sh
```
builds a project profile from real repo signals.
```
scripts/check_workspace_trust.sh
```
checks or enables Claude Code workspace trust for an exact project path.
```
scripts/scaffold_hooks.sh
```
renders the managed hook tree, manifest, README, and settings fragment.
```
scripts/merge_settings.sh
```
preserves non-managed hooks while replacing previously managed handlers.

scripts/render_hooks_readme.sh

rebuilds

.claude/hooks/README.md

from the manifest and the current plan.

```
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

。

Gotchas

常见陷阱

```
async
```
only applies to command hooks, and async hooks cannot block or steer Claude after the triggering action is already done.
The
```
if
```
field only works on tool events and requires Claude Code v2.1.85 or later.
```
Stop
```
hooks can loop forever unless you honor
```
stop_hook_active
```
.
Hook shells are non-interactive. Shell profile noise can break JSON output.
```
PermissionRequest
```
does not fire in non-interactive
```
-p
```
mode.
Hooks do not fire in untrusted workspaces. Claude Code gates execution on
```
hasTrustDialogAccepted
```
in
```
~/.claude.json
```
under
```
.projects["/absolute/path/to/project"]
```
. When hooks look installed but never run, or after a real scaffold, check trust first with
```
scripts/check_workspace_trust.sh
```
before blaming the hook config. See
```
references/gotchas.md
```
gotcha 9 for the exact recovery flow.

```
async
```
仅适用于命令钩子，且异步钩子无法在触发操作完成后阻止或引导Claude。
```
if
```
字段仅适用于工具事件，且要求Claude Code版本为v2.1.85或更高。
```
Stop
```
钩子可能无限循环，除非你遵守
```
stop_hook_active
```
规则。
钩子shell是非交互式的。shell配置文件的冗余输出可能破坏JSON输出。
```
PermissionRequest
```
在非交互式
```
-p
```
模式下不会触发。
钩子在不受信任的工作区中不会触发。Claude Code会根据
```
~/.claude.json
```
中
```
.projects["/absolute/path/to/project"]
```
下的
```
hasTrustDialogAccepted
```
字段来控制执行。当钩子看似已安装但从未运行，或完成实际搭建后，请先使用
```
scripts/check_workspace_trust.sh
```
检查信任，再归咎于钩子配置。有关精确恢复流程，请查看
```
references/gotchas.md
```
中的第9个陷阱。