ECC InfiSense

一款面向企业级 C/C++ 开发的综合性 Claude Code 插件。提供智能体 (Agent)、技能 (Skill)、 钩子 (Hook)、命令 (Command)、规则 (Rule) 以及 MCP 服务器配置，覆盖专业 C++ 工作流中的 构建、测试、代码审查、静态分析、消毒器 (Sanitizer) 集成和 CI/CD 自动化等环节。

本插件为 Claude Code 带来了什么

Claude Code 是一款通用型 AI 编程助手。本插件将其打造为 C++ 开发的强大引擎， 新增以下能力：

| 能力 | 原生 Claude Code | 搭配 ECC InfiSense | |------|-------------------|------------------------| | 构建系统感知 | 通用文件编辑 | 自动检测 CMake/Make/Meson/Bazel，了解构建命令 | | TDD 工作流 | 手动编写测试 | /tdd 严格执行红-绿-重构 (RED-GREEN-REFACTOR) 流程，支持 GTest/Catch2 | | 内存安全 | 通用代码审查 | /sanitize 运行 ASan/UBSan/TSan 并解读结果 | | 静态分析 | 手动调用工具 | /static-analysis 运行 clang-tidy + cppcheck，自动解析结果 | | 代码审查 | 通用建议 | 基于 C++ Core Guidelines、MISRA 标准，关注 ABI 稳定性和安全性 | | 构建错误处理 | 通用调试 | 专用 build-error-resolver 智能体，解决 CMake/编译器/链接器错误 | | 性能分析 | 通用建议 | /benchmark 集成 Google Benchmark、Valgrind、perf | | CI/CD | 手动搭建流水线 | CI 技能生成含矩阵构建 + 消毒器的 GitHub Actions 配置 | | 嵌入式 C++ | 无相关支持 | 交叉编译、中断安全 (ISR Safety)、栈用量分析、零动态分配规则 | | 会话连续性 | 无持久化 | 会话钩子在压缩 (Compaction) 和重启时自动保存/恢复上下文 | | 质量门禁 | 无 | 编辑后自动运行 clang-format、编译检查、clang-tidy |

功能概览

| 组件 | 数量 | 说明 | |------|------|------| | 智能体 (Agent) | 12 | 专注于架构设计、代码审查、测试、调试和性能分析的 C++ 子智能体 | | 技能 (Skill) | 24 | 涵盖 CMake、测试、消毒器、静态分析和工具链的 C++ 工作流技能 | | 命令 (Command) | 20 | 用于构建配置、验证、审查、消毒器和性能分析的斜杠命令 | | 钩子匹配器 (Hook Matcher) | 13 | 覆盖 PreToolUse、PostToolUse、会话生命周期和压缩事件的自动化 | | 规则 (Rule) | 20 | 位于 common/ 和 cpp/ 目录下的常驻准则 | | MCP 服务器 | 7 | GitHub、文档、搜索、文件系统和记忆存储等外部集成 | | 示例 (Example) | 8 | 适用于常见 C++ 项目类型的 CLAUDE.md 模板 | | 指南 (Guide) | 2 | C++ 开发和现代 CMake 的详尽指南 |

安装

前置条件

• Node.js 18+ -- 钩子脚本和验证所需
• Claude Code -- Anthropic 的 Claude 命令行工具（需已安装并完成认证）
• C++ 工具链 -- GCC 12+ 或 Clang 15+（用于实际 C++ 项目开发）

验证前置条件

# 检查 Node.js 版本
node --version
# 预期输出: v18.x.x 或更高

# 检查 Claude Code
claude --version
# 预期输出: 显示版本信息

# 检查 C++ 编译器
g++ --version     # GCC
clang++ --version # Clang

# 检查 CMake（推荐）
cmake --version
# 预期输出: 3.20+

方式 1: 通过 npm 安装（推荐）

# 全局安装
npm install -g ecc-infisense

# 运行安装脚本
ecc-infisense-install cpp

方式 2: 从源码安装

git clone [email protected]:sunchaoyue/ecc-infisense.git
cd ecc-infisense
./install.sh cpp

此命令会将以下组件安装到 ~/.claude/ 目录：

| 组件 | 安装路径 | 数量 | |------|---------|------| | 规则 (Rules) | ~/.claude/rules/common/ + ~/.claude/rules/cpp/ | 20 | | 命令 (Commands) | ~/.claude/commands/ | 20 | | 智能体 (Agents) | ~/.claude/agents/ | 12 | | 技能 (Skills) | ~/.claude/skills/ | 24 | | 钩子 (Hooks) | ~/.claude/settings.json (合并) | 13 |

部分安装

如果只需要部分组件，可以手动复制：

# 仅安装规则
cp -r rules/common/* ~/.claude/rules/common/
cp -r rules/cpp/* ~/.claude/rules/cpp/

# 仅安装智能体
cp agents/* ~/.claude/agents/

# 仅安装技能
cp -r skills/* ~/.claude/skills/

# 仅安装命令
cp commands/*.md ~/.claude/commands/

自定义安装路径

将规则安装到自定义目录：

CLAUDE_RULES_DIR=/path/to/custom/rules ./install.sh cpp

验证安装

安装完成后，检查各组件是否就位：

# 检查规则
ls ~/.claude/rules/common/ ~/.claude/rules/cpp/

# 检查智能体
ls ~/.claude/agents/

# 检查技能
ls ~/.claude/skills/

# 检查命令
ls ~/.claude/commands/

# 检查钩子
grep -c '"hooks"' ~/.claude/settings.json

然后在 C++ 项目中启动 Claude Code 会话并运行：

> /verify

如果插件已激活，你将看到验证流水线尝试构建、测试和分析你的项目。

安装问题排查

问题： ./install.sh cpp 报错 "Permission denied"。 解决方案： 添加可执行权限后重试：chmod +x install.sh && ./install.sh cpp。

问题： ./install.sh cpp 报错 "rules/cpp/ does not exist"。 解决方案： 确保从仓库根目录运行脚本，而非从子目录。

问题： 钩子执行时提示找不到 clang-format。 解决方案： 安装 clang-format：

# Ubuntu/Debian
sudo apt install clang-format

# macOS
brew install clang-format

# 或安装特定版本
sudo apt install clang-format-18

问题： 钩子脚本报错 "Permission denied"。 解决方案： 钩子脚本需要可执行权限：

chmod +x scripts/hooks/*.js

问题： Claude Code 会话中规则未生效。 解决方案： 检查规则是否已复制到正确位置：

ls ~/.claude/rules/common/
ls ~/.claude/rules/cpp/

问题： Node.js 版本过低，无法运行钩子脚本。 解决方案： 将 Node.js 升级到 18+：

# 使用 nvm
nvm install 18
nvm use 18

# 使用 apt (Ubuntu)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs

快速上手指南

本指南带你在 5 分钟内完成从安装到第一次 TDD 会话的全过程。

第 1 步：安装插件

git clone [email protected]:sunchaoyue/ecc-infisense.git
cd ecc-infisense
./install.sh cpp

第 2 步：打开你的 C++ 项目

cd /path/to/your/cpp/project
claude

第 3 步：配置构建系统

> /setup-build

Claude Code 会检测你的构建系统（CMake、Make、Meson 或 Bazel），并配置测试、 消毒器和代码格式化支持。

第 4 步：编写 CLAUDE.md

复制一个示例模板并根据项目进行定制：

> Create a CLAUDE.md for this project based on the cmake-library template

第 5 步：开始 TDD 会话

> /tdd StringUtils::trim removes leading and trailing whitespace

Claude Code 将执行以下步骤：

1. 编写一个失败的测试（红灯 RED）
2. 编写最小化实现使测试通过（绿灯 GREEN）
3. 重构以提升代码清晰度（重构 REFACTOR）
4. 运行完整测试套件以确保无回归

第 6 步：验证质量

> /verify

完整验证流水线将依次运行：编译、测试、消毒器检查、静态分析和覆盖率统计。

使用示例：Top 5 命令

/tdd -- 测试驱动开发

> /tdd Parser::parse handles nested JSON objects

Claude Code 进入红-绿-重构循环:
  RED:      编写一个调用 Parser::parse 处理嵌套 JSON 的测试
  GREEN:    编写最小化代码使测试通过
  REFACTOR: 清理实现并重新运行所有测试

/verify -- 完整验证流水线

> /verify

流水线阶段:
  1. 编译: cmake --build build
  2. 测试: ctest --test-dir build --output-on-failure
  3. 消毒器检查: 使用 ASan + UBSan 构建并测试
  4. 静态分析: clang-tidy + cppcheck
  5. 覆盖率: lcov 报告并检查阈值

/code-review -- 全面 C++ 代码审查

> /code-review src/parser.cpp

审查内容:
  - 内存安全（所有权、生命周期、边界检查）
  - 安全性（CWE 模式、输入验证）
  - 性能（不必要的拷贝、算法复杂度）
  - 可维护性（命名、结构、文档）
  - C++ Core Guidelines 合规性

/setup-build -- 构建系统配置

> /setup-build

交互式配置:
  1. 检测或选择构建系统 (CMake, Make, Meson, Bazel)
  2. 配置编译器和 C++ 标准
  3. 设置测试框架 (GoogleTest, Catch2)
  4. 启用消毒器配置
  5. 配置 clang-format 和 clang-tidy
  6. 生成 CMakePresets.json

/sanitize -- 内存安全验证

> /sanitize

在三种消毒器下分别运行测试（各自独立构建）:
  - 地址消毒器 (AddressSanitizer): 缓冲区溢出、释放后使用、内存泄漏
  - 未定义行为消毒器 (UndefinedBehaviorSanitizer): 有符号溢出、空指针解引用等
  - 线程消毒器 (ThreadSanitizer): 数据竞争、死锁

报告包含源码位置和修复建议。

架构

ecc-infisense/
  agents/                    # 12 个专用 C++ 子智能体
  commands/                  # 20 个斜杠命令
  contexts/                  # 可复用的上下文片段
  docs/                      # 详尽指南
    the-cpp-guide.md         # 全面的 C++ 开发指南
    the-cmake-guide.md       # 现代 CMake 指南
  examples/                  # C++ 项目的 CLAUDE.md 模板
  hooks/                     # 事件驱动的自动化
  mcp-configs/               # MCP 服务器配置
  rules/                     # 常驻准则
    common/                  # 语言无关的规则（12 个文件）
    cpp/                     # C++ 专属规则（8 个文件）
  schemas/                   # 用于验证的 JSON Schema
  scripts/                   # Node.js 工具脚本
    ci/                      # CI 验证脚本
    hooks/                   # 钩子运行器实现
    lib/                     # 共享库代码
  skills/                    # 24 个 C++ 工作流技能
  tests/                     # 测试套件
  .claude-plugin/            # 插件元数据
    plugin.json
  install.sh                 # 安装脚本
  package.json               # Node.js 包配置

智能体 (Agent)

智能体是 Claude Code 可以委派执行特定 C++ 任务的专用子智能体。每个智能体拥有定义好的 工具集、目标模型和领域专长。

| 智能体 | 说明 | |--------|------| | architect | C/C++ 系统架构专家，擅长可扩展、可维护的设计，具备 ABI 和构建系统意识 | | build-error-resolver | C++ 构建错误专家，处理 CMake、编译器、链接器、模板和符号相关问题 | | code-reviewer | 全面的 C++ 审查者，关注质量、安全、内存安全和可维护性 | | cpp-reviewer | C++ Core Guidelines 和 MISRA/AUTOSAR 合规性审查者 | | doc-updater | C++ 项目的 Doxygen 文档生成与更新专家 | | e2e-runner | C++ 集成测试和端到端测试专家 | | memory-debugger | 内存调试专家，使用 Valgrind 和消毒器 | | performance-profiler | 性能分析专家，使用 perf、cachegrind 和基准测试 | | planner | C++ 实现规划专家，覆盖新功能开发、重构和迁移 | | refactor-cleaner | 重构和死代码清理专家，面向遗留 C++ 代码库 | | security-reviewer | C/C++ 安全专家，进行 CWE 风格的漏洞分析 | | tdd-guide | C++ TDD 专家，严格执行红-绿-重构流程，支持 GTest/Catch2 |

智能体格式

智能体是带有 YAML 前置信息 (Frontmatter) 的 Markdown 文件：

---
name: agent-name
description: What this agent does
tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
model: claude-sonnet-4-20250514
---

技能 (Skill)

技能为特定 C++ 工作流提供深度领域知识。每个技能是 skills/ 下命名目录中的一个 SKILL.md 文件。

| 技能 | 说明 | |------|------| | api-design-cpp | ABI 稳定的 C++ API 设计，包含版本化命名空间和导出宏 | | benchmark-patterns | 用于 C++ 微基准测试的 Google Benchmark 模式 | | catch2-patterns | Catch2 v3 测试框架模式和 BDD 风格测试 | | ci-cd-cpp | C++ 的 GitHub Actions CI/CD 配置，含矩阵构建、缓存和消毒器 | | clang-format-setup | clang-format 代码格式化配置与集成 | | cmake-patterns | 现代 CMake 3.20+ 模式，涵盖目标、包和预设 | | conan-vcpkg-management | C++ 包管理器集成，支持 Conan 2.x 和 vcpkg | | configure-infisense | ECC InfiSense 插件配置向导 | | cpp-coding-standards | C++ Core Guidelines、MISRA C++ 和 AUTOSAR 编码标准合规 | | cpp-concurrency | 现代 C++ 并发编程，包含 jthread、原子操作、屏障和协程 | | cpp-design-patterns | 现代 C++ 设计模式，包括 RAII、Pimpl、CRTP 和类型擦除 | | cpp-migration | 迁移指南：C 到 C++、C++11 到 C++17、C++17 到 C++20/23 | | cpp-security-hardening | C++ 构建的编译器和链接器安全加固选项 | | cpp-testing | 全面的 C++ 测试方案，使用 GoogleTest、GoogleMock 和 CTest | | cross-compilation | ARM、嵌入式和多平台构建的交叉编译工具链 | | docker-cpp | C++ 应用程序的多阶段 Docker 构建 | | embedded-cpp | 嵌入式 C++ 模式，面向静态分配和裸机/RTOS 目标 | | fuzzing-workflow | 使用 libFuzzer、AFL++ 的模糊测试和语料库管理 | | sanitizer-workflow | 地址消毒器、未定义行为消毒器、线程消毒器和内存消毒器工作流 | | static-analysis-workflow | clang-tidy 和 cppcheck 持续静态分析集成 | | tdd-workflow-cpp | 基于 GTest 和 CMake 的 C++ TDD 红-绿-重构工作流 | | template-metaprogramming | C++20 概念 (Concepts)、constexpr if、折叠表达式和 SFINAE 替代方案 | | valgrind-debugging | Valgrind memcheck、callgrind、massif 和 helgrind 工作流 | | verification-loop-cpp | 完整验证流水线：编译 -> 测试 -> 消毒器 -> 静态分析 -> 覆盖率 |

命令 (Command)

斜杠命令为常见 C++ 开发任务提供一键式工作流。

| 命令 | 说明 | |------|------| | /benchmark | 运行 Google Benchmark 测试并分析性能回归 | | /build-fix | 以最小安全变更逐步修复 CMake、编译和链接错误 | | /checkpoint | 保存当前会话状态以便后续恢复 | | /code-review | 针对内存安全、安全性和质量的全面 C++ 代码审查 | | /cpp-review | C++ Core Guidelines 及 MISRA/AUTOSAR 合规性审查 | | /evolve | 从新发现的模式中改进现有 C++ 技能 | | /learn | 从当前会话中提取可复用的 C++ 模式和经验 | | /orchestrate | 协调多个智能体完成复杂 C++ 工作流 | | /plan | 在编写代码前生成分步 C++ 实现计划 | | /refactor-clean | 移除死代码并现代化遗留 C++ 模式 | | /sanitize | 运行 ASan、UBSan、TSan 和 MSan 工作流并解读结果 | | /sessions | 列出、加载和管理已保存的 C++ 开发会话 | | /setup-build | 交互式构建系统配置（CMake、编译器、包管理器、测试） | | /skill-create | 从 git 历史或会话模式生成新的 C++ 技能 | | /static-analysis | 运行 clang-tidy 和 cppcheck 静态分析 | | /tdd | 使用 GTest/Catch2 严格执行 C++ 红-绿-重构流程 | | /test-coverage | 生成并分析覆盖率报告 (gcov/lcov/llvm-cov) | | /update-docs | 为变更的 C++ 文件生成或更新 Doxygen 文档 | | /valgrind-check | 运行 Valgrind memcheck/callgrind/massif 分析 | | /verify | 完整流水线验证：编译、测试、消毒器检查、静态分析、覆盖率 |

钩子系统

钩子在 Claude Code 事件触发时自动运行，用于保障质量和维持会话连续性，无需手动调用。

| 事件 | 匹配器 | 钩子脚本 | 用途 | |------|--------|----------|------| | PreToolUse | Bash | block-long-builds.js | 阻止超时构建 | | PreToolUse | Bash | warn-unsafe-commands.js | 执行危险命令前发出警告 | | PreToolUse | Edit\|Write | suggest-compact.js | 上下文过大时建议压缩 | | PostToolUse | Edit | post-edit-clang-format.js | 自动格式化编辑过的 C++ 文件 | | PostToolUse | Edit | post-edit-compile-check.js | 编辑后进行编译检查 | | PostToolUse | Edit | post-edit-clang-tidy.js | 对编辑过的文件运行 clang-tidy | | PostToolUse | Edit | check-debug-code.js | 检测遗留的调试代码 | | PostToolUse | Bash | post-build-analysis.js | 分析构建输出中的问题 | | PreCompact | * | pre-compact.js | 压缩前保存上下文 | | SessionStart | * | session-start.js | 恢复上一次会话上下文 | | Stop | * | check-debug-code.js | 最终的调试代码检查 | | SessionEnd | * | session-end.js | 保存会话状态 | | SessionEnd | * | evaluate-session.js | 记录会话质量指标 |

自定义钩子

钩子配置位于 hooks/hooks.json。自定义方式如下：

1. 禁用钩子： 从 hooks 数组中移除对应条目
2. 修改超时时间： 在钩子条目中设置 "timeout"（单位：毫秒）
3. 添加新钩子： 新增条目，指定 "type": "command" 和脚本路径

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/post-edit-clang-format.js\"",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

编写自定义钩子

钩子脚本通过 stdin 接收事件数据（JSON 格式），可以：

• 输出到 stdout（显示给 Claude Code）
• 以退出码 0 结束（允许操作）
• 以非零退出码结束（阻止操作，仅对 PreToolUse 钩子有效）

// my-custom-hook.js
const input = JSON.parse(await readStdin());
const { event, tool_name, tool_input } = input;

if (shouldBlock(tool_input)) {
    console.log("Blocked: reason...");
    process.exit(1);
}

process.exit(0);

构建系统检测

插件通过扫描项目根目录下的特征文件来自动检测构建系统：

| 文件 | 构建系统 | 使用的命令 | |------|----------|-----------| | CMakeLists.txt | CMake | cmake -B build, cmake --build build, ctest --test-dir build | | Makefile / GNUmakefile | Make | make, make test | | meson.build | Meson | meson setup build, meson compile -C build, meson test -C build | | BUILD / WORKSPACE / MODULE.bazel | Bazel | bazel build //..., bazel test //... |

通过环境变量覆盖自动检测：

export CLAUDE_BUILD_SYSTEM=cmake

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | CLAUDE_BUILD_SYSTEM | 强制指定构建系统类型 | 自动检测 | | CLAUDE_BUILD_DIR | 构建输出目录 | build/ | | CLAUDE_CXX_STANDARD | C++ 标准版本 | 20 | | CLAUDE_COMPILER | 首选编译器 | 系统默认 | | CLAUDE_SANITIZERS | 默认消毒器集合 | address,undefined | | CLAUDE_RULES_DIR | 自定义规则安装路径 | ~/.claude/rules/ |

规则 (Rule)

规则是 Claude Code 在每次交互中始终遵循的准则，涵盖 C++ 最佳实践、编码标准和项目约定。

通用规则（语言无关）

| 规则 | 说明 | |------|------| | agents | 智能体委派和职责边界 | | ci | CI/CD 流水线要求：构建、测试、消毒器、格式化 | | coding-style | 一致的格式化、命名规范和结构 | | dependencies | 依赖管理：版本锁定、包管理器、许可证追踪 | | development-workflow | 规划、执行和验证的工作流规则 | | documentation | Doxygen、README、ADR 和变更日志要求 | | git-workflow | 分支策略、提交规范和审查实践 | | hooks | 钩子执行和安全防护 | | patterns | 可复用的实现和架构模式 | | performance | 构建性能、ccache、PCH、LTO 和性能分析 | | security | 安全默认值、输入验证和密钥管理 | | testing | 测试策略、覆盖率预期和可靠性检查 |

C++ 规则

| 规则 | 说明 | |------|------| | abi | ABI 稳定性：Pimpl、内联命名空间、导出宏、SO 版本 | | coding-style | C++ Core Guidelines、命名规范、RAII、const 正确性 | | embedded | 嵌入式 C++ 约束：禁止动态分配、禁止异常、中断安全、volatile | | hooks | 编辑/构建周期中的 C++ 专属钩子预期 | | modules | C++20 模块：命名、导入顺序、迁移策略 | | patterns | 现代 C++ 模式和反模式指导 | | security | 缓冲区溢出、整数溢出、释放后使用、CWE 映射 | | testing | 基于 GTest/Catch2 的 C++ 测试、消毒器、模糊测试、基于属性的测试 |

MCP 服务器

MCP (Model Context Protocol) 服务器为 Claude Code 扩展外部工具访问能力。

| 服务器 | 用途 | |--------|------| | github | GitHub PR、Issue 和代码审查集成 | | filesystem | 项目文件系统访问 | | memory | 跨会话的持久化上下文存储 | | sequential-thinking | 针对复杂 C++ 问题的逐步推理 | | context7 | C++ 库的文档上下文 | | brave-search | 搜索 cppreference、Stack Overflow 和文档 | | cpp-reference | 直接获取 C++ 参考文档 |

配置

export GITHUB_TOKEN=ghp_...
export BRAVE_API_KEY=BSA...
export PROJECT_ROOT=/path/to/your/project

CLAUDE.md 示例模板

examples/ 目录包含适用于常见 C++ 项目类型的即用型 CLAUDE.md 模板。 将合适的模板复制到项目根目录并进行定制。

| 模板 | 适用场景 | |------|----------| | CLAUDE.md | 使用 CMake 和 GoogleTest 的通用 C++ 项目 | | cmake-library-CLAUDE.md | 带安装规则和包配置的 CMake 库 | | embedded-cpp-CLAUDE.md | 嵌入式 C++ 项目，支持交叉编译和裸机/RTOS | | qt-application-CLAUDE.md | Qt 6 桌面应用程序，使用 QML 和 Qt Widgets | | grpc-service-CLAUDE.md | gRPC 微服务，使用 protobuf 和 Docker 部署 | | bazel-project-CLAUDE.md | 使用 Bzlmod 和 Starlark BUILD 文件的 Bazel C++ 项目 | | ros2-package-CLAUDE.md | ROS 2 C++ 包，使用 colcon、ament_cmake 和 rclcpp | | game-engine-CLAUDE.md | 游戏引擎，包含 ECS、Vulkan 渲染和物理子系统 |

cp examples/cmake-library-CLAUDE.md /path/to/your/project/CLAUDE.md
# 根据项目实际情况进行编辑

文档

详尽指南

| 指南 | 说明 | |------|------| | docs/the-cpp-guide.md | 使用 Claude Code 进行 C++ 开发的全面指南：TDD、消毒器、静态分析、性能分析、CI/CD、嵌入式、库开发 | | docs/the-cmake-guide.md | 现代 CMake 指南：基于目标的配置、FetchContent、预设 (Presets)、CTest、安装/导出、CPack、工具链文件 |

已实现功能

以下功能已完整实现并经过测试：

• 12 个专用 C++ 智能体，具备 YAML 前置信息和工具规格定义
• 24 个 C++ 工作流技能，覆盖完整开发生命周期
• 20 个斜杠命令，面向常见 C++ 任务
• 13 个钩子匹配器，实现自动化质量保障
• 20 条规则（12 条通用 + 8 条 C++ 专属），附带代码示例
• 8 个 CLAUDE.md 示例模板，适用于不同项目类型
• 2 份详尽指南（C++ 指南、CMake 指南）
• JSON Schema 用于验证所有组件
• CI 验证脚本，覆盖智能体、命令、规则、技能和钩子
• 安装脚本，支持多语言
• 7 个外部集成的 MCP 服务器配置
• 构建系统自动检测（CMake、Make、Meson、Bazel）
• 会话管理，支持跨压缩的保存/恢复

路线图

未来版本计划实现的功能：

• Conan 2.x 集成技能 -- 完整的 Conan Profile 和 Lockfile 管理
• CMake 模块支持 -- C++20 模块依赖扫描配置
• MISRA C++ 2023 检查器 -- 通过 clang-tidy 实现自动化 MISRA 合规检查
• 基于 Clang 的代码覆盖率 -- llvm-cov 和基于源码的覆盖率集成
• 包发布 -- 自动化的 Conan/vcpkg 包创建和发布
• Visual Studio 集成 -- 在 CMake 之外支持 MSBuild 和 .vcxproj
• Xcode 项目支持 -- CMake Xcode 生成器配置
• 远程构建支持 -- 基于 SSH 的远程编译和测试
• Docker DevContainer -- 预配置的开发容器，包含所有工具
• 性能回归 CI -- 跨提交的自动化基准测试对比
• 多仓库支持 -- 跨仓库的依赖和构建管理
• 自定义规则创作工具 -- 从模式中创建项目专属规则

常见问题 (FAQ)

问：是否需要安装所有 MCP 服务器？

不需要。MCP 服务器是可选的。插件的核心功能（规则、命令、智能体、技能、钩子）无需任何 MCP 服务器即可运行。只需安装你需要的服务器，例如用于 PR 集成的 github 或用于文档 查询的 brave-search。

问：能否用于基于 Makefile 的项目（没有 CMake）？

可以。插件会自动检测 Makefile 并相应调整构建命令。但部分功能（消毒器集成、 CMakePresets、FetchContent）是 CMake 专属的。为获得最佳体验，建议迁移到 CMake 或添加一个封装 Makefile 的 CMakeLists.txt。

问：如何禁用某个过于频繁的钩子？

编辑 hooks/hooks.json，移除你想禁用的钩子条目。例如，若要禁用编辑后的 clang-tidy 检查（对大文件可能较慢），从 PostToolUse / Edit 匹配器数组中移除对应条目即可。

问：插件是否支持 C（而非 C++）？

部分支持。通用规则、构建系统检测、消毒器集成和许多智能体都适用于 C 代码。C++ 专属规则 （模块、ABI、模板）则不适用。可以使用覆盖 C 和 C++ 的 security 规则（CWE 映射） 和 testing 规则。

问：如何添加自定义规则？

在 rules/common/（语言无关规则）或 rules/cpp/（C++ 专属规则）中创建一个 Markdown 文件。文件名即为规则名称。请参照现有规则的格式：标题、说明、代码示例和 执行说明。

问：支持哪些 C++ 标准？

插件支持 C++11 到 C++23。默认为 C++20。可通过 CLAUDE_CXX_STANDARD 环境变量或在 CLAUDE.md 中配置标准版本。规则和技能涵盖现代 C++ 特性（概念、范围、协程、模块）， 同时也支持从旧标准的迁移。

问：能否使用 Catch2 代替 GoogleTest？

可以。/tdd 命令和测试技能同时支持 GoogleTest 和 Catch2。在 CLAUDE.md 中设置 首选框架：

## Testing
- **Framework:** Catch2 v3

TDD 智能体将生成 Catch2 风格的测试（TEST_CASE、SECTION、REQUIRE）， 而非 GoogleTest 风格的测试（TEST、EXPECT_EQ）。

问：如何在包含多个 C++ 项目的单体仓库 (Monorepo) 中使用？

在每个项目子目录中放置一个 CLAUDE.md，包含项目特定的构建命令和架构说明。插件会在打开 会话时读取最近的 CLAUDE.md。~/.claude/rules/ 中的通用规则在所有项目中全局生效。

开发

前置条件

• Node.js 18+
• npm 或 bun

运行测试

npm test

此命令运行所有验证脚本和测试套件：

1. scripts/ci/validate-agents.js -- 验证智能体的前置信息和结构
2. scripts/ci/validate-commands.js -- 验证命令格式
3. scripts/ci/validate-rules.js -- 验证规则组织结构
4. scripts/ci/validate-skills.js -- 验证技能目录结构
5. scripts/ci/validate-hooks.js -- 验证钩子配置
6. tests/run-all.js -- 运行功能测试

代码检查

npm run lint

-对 JavaScript 文件运行 ESLint，对 Markdown 文件运行 markdownlint。

贡献

详细指南请参阅 CONTRIBUTING.md，包括：

• 添加新的智能体、技能、命令、钩子和规则
• 文件格式规范
• 测试要求
• 提交信息约定
• Pull Request 流程

许可证

MIT 许可证。详见 LICENSE。