cpp-core-guidelines-review

C++ Core Guidelines 审查

概述

通过启动并行子 Agent，让每个子 Agent 按照特定指南章节分析代码，从而依据 C++ Core Guidelines 审查 C++ 代码。此技能可确保全面覆盖，同时高置信度地识别违规项。

工作流

步骤 1：明确审查范围

启动任何子 Agent 之前，先与用户确认审查范围：

1. 目标文件/目录：要审查哪些 C++ 源文件或目录？
2. 文件模式：要包含哪些文件扩展名？（例如，.cpp、.h、.hpp）
3. 排除项：是否要排除任何文件或目录？

重要：只有在范围清晰明确后才能继续。

步骤 2：启动并行子 Agent

关键要求：

• 对于 references/Content/ 中的每个文件，必须启动一个子 Agent。不得跳过任何文件。每个指南章节都必须有专属的子 Agent。
• 对每个子 Agent，使用此插件中的 agents/guideline-section-reviewer.md 内定义的 guideline-section-reviewer Agent。

并行启动策略：为最大限度地提升效率，请在一条响应消息中发送多个 Task 工具调用，以并行启动所有子 Agent。Task 工具文档明确指出：“当用户要求你并行运行 Agent 时，必须在一条消息中发送多个 Task 工具调用内容块。”

每个指南章节启动一个子 Agent。每个子 Agent 都会：

• 仅依据分配给它的指南文件中的规则进行审查
• 将审查结果输出到 <current-working-directory>/review/<SectionName>.md
• 报告违规项，并包含文件路径、行号、代码片段和违反的具体规则

Agent 调用流程：

1. 读取 Agent 模板：读取 agents/guideline-section-reviewer.md 中的 Agent 定义
2. 替换参数：将 Agent 文件中的模板变量替换为实际值：
   • {{SECTION_NAME}}：章节的显示名称（例如，“函数”）
   • {{SECTION_FILE}}：references/Content/ 中章节文件的文件名（例如，Functions.md）
   • {{TARGET_FILES_PATTERN}}：要审查的文件/目录（例如，src/**/*.cpp 或特定文件路径）
   • {{OUTPUT_DIR}}：输出目录（通常为 <current-working-directory>/review）
   • {{DATE}}：当前日期，格式为 YYYY-MM-DD
   • {{FILES_COUNT}}：正在审查的文件数
   • {{VIOLATION_COUNT}}：占位符，将由 Agent 填写
3. 启动 Agent：使用 subagent_type=general，并将替换后的提示词作为 Agent 的指令，通过 Task 工具启动

调用示例：

For section "Functions":
- Read agent template from agents/guideline-section-reviewer.md
- Substitute: SECTION_NAME="Functions", SECTION_FILE="Functions.md", etc.
- Launch guideline-section-reviewer agent with substituted prompt

Agent 将：

1. 从插件的 references/Content/ 目录读取指南章节
2. 按照该章节的规则审查目标文件
3. 将审查结果输出到 <OUTPUT_DIR>/<SECTION_NAME>.md
4. 报告违规项，并提供文件路径、行号、代码片段和具体违反的规则

步骤 3：等待所有子 Agent

启动所有子 Agent 后，收集其任务 ID 并等待完成：

等待流程：

1. 跟踪任务 ID：保存每次调用 Task 工具时返回的任务 ID
2. 等待完成：针对每个任务 ID，使用 TaskOutput 并设置：
   • task_id：子 Agent 启动时返回的任务 ID
   • block=true：等待子 Agent 完成
   • timeout=600000（10 分钟）：每个 Agent 的最长等待时间
3. 验证成功：检查每个子 Agent 是否：
   • 已完成且未出错
   • 已在 <current-working-directory>/review/<SectionName>.md 中创建输出文件
   • 未修改任何源文件

错误处理：

• 如果子 Agent 失败：向用户报告错误，并继续处理其他 Agent
• 如果发生超时：注明超时的 Agent，并向用户报告
• 如果输出文件缺失：指出哪个部分的审查尚未完成

验证清单：

• 已启动所有子 Agent
• 所有子 Agent 均已完成（或已报告失败）
• 每个已完成部分都有对应的输出文件
• 未修改任何源文件

步骤 4：生成摘要

所有子 Agent 完成后，在 <current-working-directory>/review/Summary.md 中创建一份涵盖所有发现的综合分析。

流程：

1. 读取 <current-working-directory>/review/*.md 中所有部分审查文件（不包括 Summary.md 本身）
2. 汇总违规数量、受影响文件和违反的规则
3. 使用以下模板生成摘要

Summary.md 模板：

# C++ Core Guidelines Review Summary

## Overview

**Date**: YYYY-MM-DD
**Review Scope**: <Files/directories reviewed>
**Total Sections Reviewed**: <Number of sections completed>
**Total Violations Found**: <Total count across all sections>

## Summary by Section

| Section | Violations | Most Violated Rule |
|---------|------------|-------------------|
| Functions | N | F.15, ... |
| Classes and Class Hierarchies | N | C.7, ... |
| Resource Management | N | R.1, ... |
| [Continue for all sections] | | |

## Summary by File

| File | Total Violations | Top Violation Categories |
|------|------------------|--------------------------|
| path/to/file1.cpp | N | Resource Management, Error Handling |
| path/to/file2.h | M | Const Correctness, Interfaces |
| [Continue for affected files] | | |

## Top Violations by Frequency

| Rank | Rule ID | Rule Summary | Count |
|------|---------|--------------|-------|
| 1 | F.15 | Prefer simple and default constructs | N |
| 2 | R.3 | Raw pointers should not be used | M |
| [Continue] | | | |

## Critical Findings

### High-Priority Issues
<List violations with high impact or security implications>

### Most Common Patterns
<Identify recurring violation patterns across the codebase>

## Detailed Section Breakdown

### Functions (N violations)
<Brief summary of key violations in this section>
See: [Functions.md](Functions.md)

### Classes and Class Hierarchies (N violations)
<Brief summary of key violations in this section>
See: [Classes and Class Hierarchies.md](Classes%20and%20Class%20Hierarchies.md)

### [Continue for all sections with violations]

## Recommendations

1. **Immediate Actions**: <Critical violations that should be addressed soon>
2. **Process Improvements**: <Suggestions to avoid common violations>
3. **Training Topics**: <Areas where team education may help>

## Review Metadata

- **Sections Completed**: <List of sections that completed>
- **Sections Skipped/Failed**: <List of sections that had issues>
- **Total Files Reviewed**: <Count>
- **Lines of Code Reviewed**: <If available>

摘要的关键要求：

• 汇总所有部分报告中的准确违规数量
• 在适用时按违规数量降序排列表格
• 链接到各部分报告，方便查看详细发现
• 指出规律和系统性问题
• 根据发现提供可执行的建议

关键约束（最高优先级）

1. 不得修改：此技能及所有子 Agent 都不得修改受审查的文件。只能向 <current-working-directory>/review/ 目录写入内容。
2. 主会话不得参与：主对话不得执行代码审查。只能协调子 Agent。
3. 按部分强制执行：每个子 Agent 只能依据分配给自己的部分进行审查。不得报告跨部分违规。
4. 规则对应关系：每项报告的违规都必须对应到特定准则规则。无法对应的发现无效。
5. 高置信度门槛：只报告高度确信的违规。不确定的情况必须省略。
6. 仅报告违规：只报告违反准则的情况。不得报告符合准则的代码。不得在发现中提及正面或合规的代码。

C++ Core Guidelines 结构

C++ Core Guidelines 参考文件打包在此技能的 references/ 目录中：

• Introduction.md - 概述和术语表
• Content/ - 各个准则部分

每个部分包含多条规则，包括：

• 规则标识符（例如，“C.7”“F.15”）
• 规则陈述
• 理由（Reason）
• 示例（正面／负面）
• 例外情况（如适用）
• 执行建议

用户交互模式

示例 1：审查指定文件

User: "Review src/transaction.cpp and src/account.h against C++ Core Guidelines"

→ 澄清范围，然后为这些文件启动子 Agent。

示例 2：审查目录

User: "Review all C++ files in the services/ directory"

→ 澄清文件匹配模式和排除项，然后启动子 Agent。

示例 3：依据指定部分进行审查

User: "Review using only Resource Management and Error Handling guidelines"

→ 仅启动对应的两个子 Agent。