企业官网建设流程全解析

ECC C++ 钩子体系实战指南：构建提交前质量闸门与 CI 流水线

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC

本指南以 ECC（Everything Claude Code）仓库中 docs/ja-JP/rules/cpp/hooks.md 为骨架，系统讲解如何在 C++ 项目中落地"提交前检查 + CI 质量流水线"的钩子机制。你将掌握 clang-format / clang-tidy / cppcheck / CMake / CTest 五件套的完整命令与编排顺序，理解 ECC 的通用钩子类型（PreToolUse / PostToolUse / Stop）如何在真实的 hooks/hooks.json 与 rules/cpp 规则体系中生效，并能直接复制一套可运行的质量闸门方案。

文档定位与适用范围

该文档是 ECC 规则体系中 C++ 语言子规则的一部分，位于 docs/ja-JP/rules/cpp/hooks.md，属于对通用规则 rules/common/hooks.md 的 C++ 专属扩展。文档头部通过paths字段声明了规则的适用文件范围：

paths: - "**/*.cpp" - "**/*.hpp" - "**/*.cc" - "**/*.hh" - "**/*.cxx" - "**/*.h" - "**/CMakeLists.txt"

这七个 glob 模式覆盖了 C++ 常见的源码扩展名（.cpp、.cc、.cxx）与头文件扩展名（.hpp、.hh、.h），并额外包含构建脚本CMakeLists.txt。这意味着：任何涉及这些文件的改动，都应触发本钩子规则中的质量检查，而不只是针对某一种特定的编译器方言。

在 ECC 的规则体系里，同目录还配套了 rules/cpp/coding-style.md（编码风格）、rules/cpp/patterns.md（设计模式）、rules/cpp/security.md（安全规范）、rules/cpp/testing.md（测试规范），钩子规则与它们共同构成完整的 C++ 开发约束闭环——钩子负责"何时检查"，其余规则负责"检查什么"。

通用钩子系统：三种核心钩子类型

在深入 C++ 具体命令之前，先明确 ECC 所基于的钩子模型。根据 rules/common/hooks.md，钩子系统包含三种核心类型：

• PreToolUse：工具执行之前触发，用于参数校验、输入验证、权限拦截；
• PostToolUse：工具执行之后触发，用于自动格式化、结果检查；
• Stop：会话（一次 Agent 响应）结束时触发，用于最终验证。

从 hooks/hooks.json 可以看到这套模型在 ECC 仓库中的真实落地：PreToolUse阶段注册了 Bash 预检分发器（pre:bash:dispatcher）、文档文件警告、配置保护（pre:config-protection）、事实强制门（pre:edit-write:gateguard-fact-force）等钩子；PostToolUse阶段通过posttooluse-dispatcher.js同步/异步分发器执行检查；Stop阶段则批量执行格式化与类型检查（stop:format-typecheck）、会话状态持久化（stop:session-end）、成本追踪（stop:cost-tracker）等。

把这一模型映射到 C++ 开发场景，可以这样理解：

这种"分阶段检查"的设计目的是把反馈前移：越早发现问题，修复成本越低。C++ 钩子文档建议把检查放在"提交之前"（commit 前），本质上是把 PostToolUse/Stop 阶段的质量闸门前移到版本控制边界上。

提交前钩子：四条命令构建本地质量闸门

文档给出的核心实操是四条在提交 C++ 改动前必须运行的检查命令：

# 格式检查 clang-format --dry-run --Werror src/*.cpp src/*.hpp # 静态分析 clang-tidy src/*.cpp -- -std=c++17 # 构建 cmake --build build # 测试 ctest --test-dir build --output-on-failure

逐条拆解各命令的语义与关键参数：

1. 格式检查：clang-format --dry-run --Werror src/*.cpp src/*.hpp

• --dry-run：只输出需要格式化的差异，不实际改写文件，属于"检查模式"；
• --Werror：将格式问题视为错误，使命令以非零退出码结束，从而让钩子/CI 能够拦截；
• 参数src/*.cpp src/*.hpp：明确检查范围。实际项目中建议改用仓库根目录下的.clang-format配置文件驱动风格，这样所有开发者使用同一套格式标准，避免"风格争论"。

对照 rules/cpp/coding-style.md 的格式规范："使用 clang-format，不要争论风格，提交前运行clang-format -i <file>"——-i是就地改写模式，用于"修复"；--dry-run --Werror是"校验"模式，用于门禁。两者一修一验，配合使用。

2. 静态分析：clang-tidy src/*.cpp -- -std=c++17

• clang-tidy是 LLVM 官方的 C++ 静态分析工具，能检测现代 C++ 的错误、性能问题与风格问题；
• --之后的部分是传给编译器的参数，-std=c++17声明以 C++17 标准解析代码。若项目使用 C++20/23，应相应调整（详见 rules/cpp/coding-style.md 中的 "Modern C++ (C++17/20/23)" 说明）；
• 更严格的用法可以显式指定检查集，例如 agents/cpp-reviewer.md 中给出的clang-tidy --checks='*,-llvmlibc-*' src/*.cpp -- -std=c++17（启用全部检查并排除 LLVM libc 相关规则）。

3. 构建：cmake --build build

• 前提是已用cmake -B build（或传统写法cmake ..）完成配置生成build目录；
• cmake --build build是跨平台、跨生成器的构建入口，无论底层是 Makefile 还是 Ninja 都无需关心具体工具链命令。

4. 测试：ctest --test-dir build --output-on-failure

• ctest是 CMake 自带的测试驱动，--test-dir build指定测试目录；
• --output-on-failure让失败的测试输出详细诊断信息，便于定位问题。

这四条命令的编排顺序是有讲究的：先做零成本的格式与静态分析（秒级），再编译（分钟级），最后跑测试。按照 rules/cpp/testing.md 的规范，C++ 测试框架采用 GoogleTest（gtest/gmock）配合 CMake/CTest，因此ctest是这套框架的标准测试入口。

推荐 CI 流水线：五阶段检查

文档给出了推荐的 CI 流水线编排，将本地钩子扩展为持续集成中的固定阶段：

1. clang-format— 格式检查
2. clang-tidy— 静态分析
3. cppcheck— 追加分析
4. cmake 构建— 编译
5. ctest— 使用 sanitizer 运行测试

前四阶段与本地钩子一一对应，新增的cppcheck是第三个工具：它是一款独立的开源静态分析工具，擅长检测未定义行为、空指针解引用、内存泄漏等缺陷，与 clang-tidy 形成互补（clang-tidy 偏重 LLVM 生态与现代 C++ 规则，cppcheck 偏重跨编译器的通用缺陷模式）。

关于 cppcheck 的用法，rules/cpp/security.md 提供了参考命令：

cppcheck --enable=all src/

--enable=all会开启包括性能、可移植性、风格在内的全部检查类别。而 agents/cpp-reviewer.md 给出的实战变体是：

cppcheck --enable=all --suppress=missingIncludeSystem src/

增加了--suppress=missingIncludeSystem来抑制系统头文件缺失导致的误报，更适合在 CI 中无噪声运行。

最后一步"使用 sanitizer 运行测试"（运行 sanitizer 的 ctest）是 CI 流水线与本地钩子最大的差异点，其配置方式在下一节展开。

深入 C++ 测试与 sanitizer 配置

流水线第五步要求"用 sanitizer 运行测试"，这需要在 CMake 配置阶段注入编译/链接标志。根据 rules/cpp/testing.md，标准做法是：

cmake -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined" ..

这条命令同时启用了AddressSanitizer（检测越界访问、use-after-free、内存泄漏）和UndefinedBehaviorSanitizer（检测有符号整数溢出、空指针解引用、未定义行为），与 rules/cpp/security.md 中"Always initialize variables / Avoid signed integer overflow / Never dereference null or dangling pointers"的安全规范一一对应——sanitizer 正是把这些规范从"纸面约定"变成"机器可判定的失败"。

如果把 sanitizer 与覆盖率结合起来，rules/cpp/testing.md 还给出了完整的覆盖率采集流程：

cmake -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_EXE_LINKER_FLAGS="--coverage" .. cmake --build . ctest --output-on-failure lcov --capture --directory . --output-file coverage.info

--coverage标志（等价于 gcc/g++ 的-fprofile-arcs -ftest-coverage）让编译器生成覆盖率数据，测试跑完后用lcov捕获并输出coverage.info，再配合genhtml即可生成可视化报告。

推荐在 CI 中分两个 job 并行执行：一个 job 跑普通构建 + ctest（快速反馈），另一个 job 跑 sanitizer 构建 + ctest（深度检查），避免 sanitizer 的运行时开销拖慢主流水线。

规则体系的源码级印证

上述钩子规则并非孤立文档，而是 ECC 仓库中可运行机制的一部分。以下证据链可以说明：

1. 钩子规则与 Agent 的联动：专用审查 Agent agents/cpp-reviewer.md 的职责定义中，明确要求在评审 C++ 改动时运行git diff -- '*.cpp' '*.hpp' '*.cc' '*.hh' '*.cxx' '*.h'查看变更、运行clang-tidy和cppcheck（若可用），并给出了与 rules/cpp/security.md 一致的诊断命令集。其"Approve / Warning / Block"三级审批标准（CRITICAL/HIGH 问题即 Block）正是把钩子检查结果转化为决策依据的体现。

2. 钩子配置文件真实存在：仓库根目录的 hooks/hooks.json 展示了 PreToolUse、PostToolUse、Stop、SessionStart、SessionEnd 等钩子生命周期的完整注册方式。C++ 钩子文档所倡导的"提交前检查"，可以在此基础上通过自定义 matcher（如*.cpp）注册为 PreToolUse 钩子，实现 Agent 每次触碰 C++ 文件前的自动校验。

3. 构建解析 Agent 支持：仓库还提供cpp-build-resolverAgent 与cpp-build命令（见 commands/cpp-build.md），与 CMake/CTest 构建链路配套，说明 C++ 支持是仓库中被工程化对待的一等公民。

4. 多语言文档一致性：docs/ja-JP/rules/cpp/hooks.md 与英文原版 rules/cpp/hooks.md 内容一一对应，规则在全球化文档体系（如 docs/zh-CN/rules/cpp/hooks.md）中同步维护，保证不同语言环境下的 Agent 行为一致。

落地建议与适用前提

将本指南落地到实际项目时，注意以下前提与边界：

• 工具链依赖：上述命令依赖 LLVM 工具链（clang-format、clang-tidy）、CMake（≥3.0 以支持--test-dir）、CTest 与可选的 cppcheck，需在开发机与 CI 环境中预先安装；若使用 GCC 工具链，clang 系工具仍可单独安装使用，但clang-tidy对部分 GCC 专属扩展的解析可能受限。
• 版本参数调整：-std=c++17需与项目实际标准匹配；若项目已用 C++20/23，请同步修改，否则 clang-tidy 可能误报或漏报。
• 本地钩子与 CI 的分工：本地钩子（提交前四命令）追求快速反馈，CI 流水线（五阶段 + sanitizer）追求完整覆盖，两者共用同一组命令，保证"本地能过、CI 必过"。
• sanitizer 的取舍：sanitizer 会显著增加运行时开销（通常 1.5～2 倍），且有内存占用放大，建议在 CI 独立 job 中运行，而非默认本地调试构建。
• 规则联动：钩子只管"何时执行"，检查标准由 rules/cpp/coding-style.md、rules/cpp/security.md、rules/cpp/patterns.md 定义，配置项目时建议四份规则一起导入，避免"有门禁无标准"。

通过以上配置，你将获得一条从"本地提交前校验"到"CI 五阶段质量流水线"的完整 C++ 质量防线：格式、静态分析、编译、测试、内存安全五个维度层层把关，且全部由可复制、可审计的命令驱动。

【免费下载链接】ECCThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.项目地址: https://gitcode.com/GitHub_Trending/ev/ECC