ECC 规则体系中的 Rust Hooks 实战:用 cargo fmt / clippy / check 搭建 Claude Code 自动化质量门禁

原创2026-09-09 19:09:371,946 阅读
文章标签:人工智能AI 技能AI 插件AI 评测提示工程MCP ClientsAgent 记忆开发工具

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 采用"通用基座 + 语言扩展"的分层规则设计:

这种分层意味着:阅读 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 钩子:

  1. cargo fmt — 编辑 .rs 文件后自动格式化;
  2. cargo clippy — 编辑 Rust 文件后执行 lint 检查;
  3. 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 辅助编程时代,规则驱动开发最务实的落地方式。

登录后查看全文
ECC