ECC 规则体系中的 Rust Hooks 实战:用 cargo fmt / clippy / check 搭建 Claude Code 自动化质量门禁
ECC 规则体系中的 Rust Hooks 实战:用 cargo fmt / clippy / check 搭建 Claude Code 自动化质量门禁
在 Claude Code 的日常协作中,Rust 开发者最常遇到的问题是:Agent 每次编辑完 .rs 文件后,缩进、lint 警告和编译错误常常被留到下一次手动检查。本文以 ECC(Everything Claude Code)开源仓库中的 Rust Hooks 规则 为核心,系统讲解如何利用 PostToolUse 钩子在编辑器保存 .rs 文件后自动执行 cargo fmt、cargo clippy 与 cargo check,并结合仓库内真实的 hooks 配置与源码实现,帮助你搭建一套"编辑即校验、写错即反馈"的 Rust 自动化质量门禁。读完本文,你将掌握 Hook 的匹配器机制、配置语法、运行时控制方式,以及如何将这些钩子与 ECC 的 hooks 运行时、规则分层体系无缝集成。
一、规则文件的定位:Rust 专用扩展层
在 ECC 仓库中,规则按语言分目录组织,rules/rust/ 下包含 hooks.md、coding-style.md、patterns.md、security.md、testing.md 五个维度。日语本地化版本位于 docs/ja-JP/rules/rust/,其中 hooks.md 的开头就声明了它的定位:
このファイルは common/hooks.md を Rust 固有のコンテンツで拡張します。(本文件以 Rust 特有内容扩展 common/hooks.md)
也就是说,ECC 采用"通用基座 + 语言扩展"的分层规则设计:
- 通用层 rules/common/hooks.md 定义所有语言共用的 Hook 类型、权限策略与 TodoWrite 最佳实践;
- 语言层 rules/rust/hooks.md 只补充 Rust 特有的 Hook 建议;
- 本地化层 docs/ja-JP/rules/common/hooks.md 与 docs/ja-JP/rules/rust/hooks.md 提供日语翻译,方便非英语开发者引用。
这种分层意味着:阅读 Rust Hooks 规则时,必须同时理解通用 Hooks 系统的行为约定,否则容易把"该在哪一层配置"搞混。规则文件顶部的 frontmatter 也值得注意:
---
paths:
- "**/*.rs"
- "**/Cargo.toml"
---
paths 声明了该规则的作用域——只对 .rs 源文件与 Cargo.toml 清单文件生效。这与 Hook 配置中的 matcher 参数相辅相成:规则文件划定"管哪些文件",Hook 的 matcher 划定"在哪些工具事件上触发"。
二、Hooks 系统基础:理解 PreToolUse / PostToolUse / Stop
在进入 Rust 配置之前,先掌握 ECC 通用 Hooks 规则中的三类核心事件(见 rules/common/hooks.md):
| Hook 类型 | 触发时机 | 能力边界 |
|---|---|---|
| PreToolUse | 工具执行前 | 可校验、可修改参数;stderr 输出警告,退出码 2 可阻断工具调用 |
| PostToolUse | 工具执行后 | 可自动格式化、运行检查、分析输出;不能阻断,只能反馈 |
| Stop | 每轮 Agent 响应结束时 | 最终校验(如全量格式化、类型检查、会话状态持久化) |
ECC 仓库的 hooks/hooks.json 是这套机制的完整生产级示例,它把 Hook 事件扩展到了 7 类:PreToolUse、PreCompact、SessionStart、PostToolUse、PostToolUseFailure、Stop、SessionEnd。其中 PreToolUse 注册了 Bash 前置分发器(pre:bash:dispatcher)、文档文件警告(pre:write:doc-file-warning)、配置保护(pre:config-protection)、MCP 健康检查(pre:mcp-health-check)等钩子;Stop 阶段则批量执行格式化与类型检查(stop:format-typecheck)、会话成本统计(stop:cost-tracker)、桌面通知(stop:desktop-notify)等。
这套真实配置印证了一个重要设计思路:轻量检查放在 PostToolUse 逐次执行,重量级全量校验放在 Stop 批次执行——与 Rust 规则中"编辑后跑 cargo check、提交前跑完整构建"的分层策略完全一致。
三、核心配置:Rust 的 PostToolUse 三件套
Rust Hooks 规则(docs/ja-JP/rules/rust/hooks.md)给出的核心建议是在 ~/.claude/settings.json 中配置三个 PostToolUse 钩子:
- cargo fmt — 编辑
.rs文件后自动格式化; - cargo clippy — 编辑 Rust 文件后执行 lint 检查;
- cargo check — 变更后验证编译(比
cargo build更快)。
其背后是 Rust 官方工具链的标准分工:rustfmt 负责风格统一,clippy 负责代码质量 lint,cargo check 只做元数据解析与类型检查、不生成完整二进制,因此能以远低于 cargo build 的成本提前暴露编译错误。ECC 的 rules/rust/coding-style.md 进一步强化了这一分工:格式强制使用 cargo fmt,lint 使用 cargo clippy -- -D warnings(把警告升级为错误),最大行宽 100 字符。
将这三个工具落成可直接复制到 ~/.claude/settings.json 的配置:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "cargo fmt --all",
"description": "Auto-format Rust files with rustfmt after edits",
"timeout": 30
}
]
},
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "cargo clippy --all-targets --all-features -- -D warnings",
"description": "Run clippy lints with warnings-as-errors after editing Rust files",
"timeout": 120
}
]
},
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "cargo check --all-targets",
"description": "Verify compilation after changes (faster than cargo build)",
"timeout": 120
}
]
}
]
}
}
配置要点逐条拆解:
- matcher 选型:
Edit|Write覆盖了"修改已有.rs文件"和"新建.rs文件"两个场景。若只想在修改时触发,可收窄为Edit;若想连MultiEdit批量编辑也纳入,则写Edit|Write|MultiEdit(ECC 自身的 hooks/hooks.json 中大量使用"matcher": "Edit|Write|MultiEdit"组合)。 - 命令选择:
cargo fmt --all会格式化当前工作区所有包,保证多 crate 工作区风格一致;cargo check --all-targets覆盖 lib、bin、test、example 等全部目标,比裸cargo check更彻底。 - timeout 兜底:PostToolUse 钩子理论上不阻断流程,但卡死的命令仍会拖慢 Agent 响应,务必给出合理超时。ECC 的钩子中 PostToolUse 分发器的超时被设为 30 秒(同步)与 45 秒(异步,见 hooks/hooks.json 的
post:dispatcher:sync/post:dispatcher:async),可作为参考基线。
四、把配置放进真实环境:ECC 的 Hook 运行时机制
上面是"裸配置"写法。在 ECC 生态中,Hook 并不是简单粘贴到 settings.json 就完事——hooks/README.md 明确警告:不要直接把仓库里的 hooks.json 原样粘贴到 ~/.claude/settings.json 或复制到 ~/.claude/hooks/hooks.json,因为仓库内文件面向插件/仓库安装,命令路径需要按你的实际 Claude 根目录重写。正确做法是使用 ECC 安装器:
bash ./install.sh --target claude --modules hooks-runtime --enable-hooks
pwsh -File .\install.ps1 --target claude --modules hooks-runtime --enable-hooks
安装后 hooks 会解析到 ~/.claude/hooks/hooks.json(Windows 上为 %USERPROFILE%\.claude)。理解这一层后,Rust 三件套可以有两种落地方案:
- 方案 A(独立配置):把第三节的 JSON 合并进
~/.claude/settings.json的hooks.PostToolUse数组——适合只想给 Rust 项目加门禁、不引入完整 ECC 运行时的用户; - 方案 B(融入 ECC):通过 ECC 运行时环境变量控制钩子行为,与仓库内置钩子共存。运行时控制参见 hooks/README.md 的 "Runtime Hook Controls" 一节:
# 主开关:显式环境变量覆盖插件偏好
export ECC_HOOKS_ENABLED=true
# 钩子配置档位:minimal | standard | strict(默认 standard)
export ECC_HOOK_PROFILE=standard
# 按 ID 禁用特定钩子(逗号分隔)
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"
# 只关闭 GateGuard(如安装或恢复期间)
export ECC_GATEGUARD=off
minimal 只保留必要的生命周期与安全钩子,standard 是均衡档,strict 会开启更多提醒与更严格的护栏。Rust 三件套属于"质量检查"型钩子,按档位语义建议放在 standard 及以上。
五、编写自己的 Rust Hook:协议与退出码
如果默认配置满足不了需求(例如希望"新写测试文件才允许创建源文件"、"超过 N 行就阻断"),可以按 ECC 的 Hook 协议自研。根据 hooks/README.md 的定义,Hook 本质是从 stdin 读取 JSON、向 stdout 输出 JSON 的 shell 命令:
// my-rust-hook.js
let data = '';
process.stdin.on('data', chunk => data += chunk);
process.stdin.on('end', () => {
const input = JSON.parse(data);
const toolName = input.tool_name; // "Edit", "Write", "Bash" ...
const toolInput = input.tool_input; // { file_path, old_string, new_string, ... }
// 非阻断警告:写 stderr
console.error('[Hook] Rust file edited — run cargo fmt before commit');
// 阻断(仅 PreToolUse 有效):退出码 2
// process.exit(2);
// 必须把原始数据回写到 stdout
console.log(data);
});
退出码语义:0 表示成功继续;2 表示阻断工具调用(仅 PreToolUse 生效);其他非零值视为错误但只记录、不阻断。Hook 输入结构(tool_name / tool_input.file_path / tool_input.new_string / PostToolUse 独有的 tool_output)在 hooks/README.md 的 "Hook Input Schema" 一节有 TypeScript 接口定义。
结合 Rust 场景,一个实用的自定义钩子示例——编辑 .rs 文件后自动运行 rustfmt 并提醒 clippy:
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{const i=JSON.parse(d);const p=i.tool_input?.file_path||'';if(/\\.rs$/.test(p)){const{execFileSync}=require('child_process');try{execFileSync('cargo',['fmt','--all'],{stdio:'pipe'})}catch(e){console.error('[Hook] cargo fmt failed: '+e.message)}console.log(d)})\"",
"description": "Auto-format .rs files with rustfmt after edits",
"timeout": 30
}
]
}
对长耗时检查(例如大型 crate 的 cargo check),还可以声明为异步钩子避免拖慢主流程:
{
"type": "command",
"command": "node my-slow-rust-check.js",
"async": true,
"timeout": 300
}
异步钩子在后台运行,不能阻断工具执行——适合"通知类"检查,不适合"必须通过才能继续"的门禁。
六、与测试、风格规则配合:形成完整 Rust 工作流
Rust Hooks 不是孤立存在的。ECC 的 Rust 规则体系把"格式化 / lint / 编译 / 测试 / 提交"串成了完整闭环:
- 编辑后:PostToolUse 三件套兜底(
fmt→clippy→check); - 提交前:完整跑一遍 rules/rust/testing.md 定义的测试命令矩阵:
cargo test # 运行全部测试
cargo test -- --nocapture # 显示 println 输出
cargo test test_name # 按名称模式运行
cargo test --lib # 仅单元测试
cargo test --test api_test # 指定集成测试(tests/api_test.rs)
cargo test --doc # 仅文档测试
- 覆盖率门禁:
cargo llvm-cov --fail-under-lines 80强制行覆盖率不低于 80%(rules/rust/testing.md 明确目标为 80%+); - 风格门禁:
cargo clippy -- -D warnings把警告当错误处理(rules/rust/coding-style.md)。
ECC 自身也遵守同样的心智模型——它在 scripts/hooks/pre-bash-tmux-reminder.js 的正则中把 cargo build 列为典型的长时运行命令,建议放进 tmux 以便查看日志;而 cargo check 作为轻量验证则适合放在每次编辑后的 PostToolUse 里。这种"长时命令进 tmux、轻量检查进钩子"的取舍,正是 Rust 三件套设计中"用 check 代替 build"的原因所在。
七、注意事项与故障排查
- 不要在非 Rust 项目里保留三件套:
cargo命令在无 Cargo.toml 的目录会立即失败。配合规则 frontmatter 的**/*.rs/**/Cargo.toml作用域理解,建议用 matcher 精确限定,或只在 Rust 仓库中启用对应配置。 - 性能开销意识:每次
Edit|Write都跑cargo check,在大型 crate 上会显著拖慢 Agent。可以降级为只跑cargo check -q静默模式、提高 timeout、或把 clippy 移到 Stop 阶段批处理(ECC 的stop:format-typecheck正是"每次编辑不跑、每轮响应末统一跑"的代表)。 - 权限与自动接受:通用规则(rules/common/hooks.md)提醒,自动接受权限只在"可信、定义明确"的计划下开启,探索性工作应关闭,且永远不要使用
dangerously-skip-permissions标志,改用~/.claude.json中的allowedTools精确授权。Rust 钩子会触发 cargo 子进程,务必确保这些命令在授权范围内。 - 钩子被 ECC 覆盖:若通过 ECC 插件安装且发现自定义钩子不生效,检查 hooks/README.md 的禁用/覆盖方法——在
~/.claude/settings.json中对同名 matcher 声明空数组"hooks": []即可屏蔽插件钩子,或用ECC_DISABLED_HOOKS按 ID 关闭。
八、小结
Rust Hooks 规则(docs/ja-JP/rules/rust/hooks.md)虽然只有短短几行,却精准点出了 Claude Code + Rust 协作中最有价值的三道自动化关卡:cargo fmt 统一风格、cargo clippy 拦截坏味道、cargo check 快速验证编译。结合 ECC 仓库 hooks/hooks.json 的生产级配置、hooks/README.md 的协议定义与运行时控制,以及 rules/rust/coding-style.md、rules/rust/testing.md 的配套规范,你可以把这三道关卡嵌入 Agent 的每一次文件编辑,让"写完即校验、问题即反馈"成为 Rust 开发的默认体验——这正是 Agent 辅助编程时代,规则驱动开发最务实的落地方式。