cpp-core-guidelines-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

C++ Core Guidelines Review

C++ Core Guidelines 审查

Overview

概述

Review C++ code against the C++ Core Guidelines by launching parallel sub-agents, each analyzing code against a specific guideline section. This skill ensures comprehensive coverage while maintaining high confidence in violation identification.

通过启动并行的 sub-agent，依据 C++ Core Guidelines 审查 C++ 代码，每个 Agent 负责分析特定指南章节。此 skill 可确保全面覆盖，同时在识别违规项时保持较高置信度。

Workflow

工作流

Step 1: Understand Scope Clarification

第 1 步：明确审查范围

Before launching any sub-agents, clarify the review scope with the user:

Target files/directories: Which C++ source files or directories to review?
File patterns: What file extensions should be included? (e.g.,
```
.cpp
```
,
```
.h
```
,
```
.hpp
```
)
Exclusions: Any files or directories to exclude?

Important: Do not proceed until the scope is clearly defined and unambiguous.

在启动任何 sub-agent 之前，先与用户明确审查范围：

目标文件/目录：要审查哪些 C++ 源文件或目录？
文件模式：应包含哪些文件扩展名？（例如
```
.cpp
```
、
```
.h
```
、
```
.hpp
```
）
排除项：需要排除哪些文件或目录？

重要：在范围清晰且无歧义之前，不得继续。

Step 2: Launch Parallel Sub-Agents

第 2 步：启动并行 Sub-Agents

CRITICAL REQUIREMENTS:

You MUST launch one sub-agent for EVERY file in
```
references/Content/
```
. Do not skip any files. Each guideline section requires its own dedicated sub-agent.
Use the guideline-section-reviewer agent in
```
agents/guideline-section-reviewer.md
```
from this plugin for each sub-agent.

Parallel launch strategy: To maximize performance, launch all sub-agents in parallel by sending multiple Task tool calls in a single response message. The Task tool documentation explicitly states: "When the user specifies that they want you to run agents 'in parallel', you MUST send a single message with multiple Task tool use content blocks."

Launch one sub-agent per guideline section. Each sub-agent:

Reviews only against rules in its assigned guideline file

Outputs findings to

<current-working-directory>/review/<SectionName>.md

Reports violations with: file path, line numbers, code snippet, and specific rule(s) violated

Agent invocation process:

Read the agent template: Read the agent definition from
```
agents/guideline-section-reviewer.md
```
Substitute parameters: Replace the template variables in the agent file with actual values:
- ```
{{SECTION_NAME}}
```
  : The display name of the section (e.g., "Functions")
- ```
{{SECTION_FILE}}
```
  : The filename of the section in
```
references/Content/
```
  (e.g., "Functions.md")
- ```
{{TARGET_FILES_PATTERN}}
```
  : The files/directories to review (e.g., "src/**/*.cpp" or specific file paths)
- ```
{{OUTPUT_DIR}}
```
  : The output directory (typically
```
<current-working-directory>/review
```
  )
- ```
{{DATE}}
```
  : Current date in YYYY-MM-DD format
- ```
{{FILES_COUNT}}
```
  : Number of files being reviewed
- ```
{{VIOLATION_COUNT}}
```
  : Placeholder, will be filled by agent
Launch the agent: Use the Task tool with
```
subagent_type=general
```
and the substituted prompt as the agent's instruction

Example invocation:

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

The agent will:

Read the guideline section from the plugin's
```
references/Content/
```
directory
Review the target files against that section's rules
Output findings to
```
<OUTPUT_DIR>/<SECTION_NAME>.md
```
Report violations with file paths, line numbers, code snippets, and specific rule violations

关键要求：

必须为
```
references/Content/
```
中的每一个文件启动一个 sub-agent。不得跳过任何文件。每个指南章节都需要一个专门的 sub-agent。

对此 plugin 中的每个 sub-agent，使用

agents/guideline-section-reviewer.md

中的

guideline-section-reviewer

Agent。

并行启动策略：为最大化性能，应在单条响应消息中发送多个 Task tool 调用，同时启动所有 sub-agent。Task tool 文档明确规定：“当用户指定要并行运行 Agent 时，必须在单条消息中发送多个 Task tool 使用内容块。”

每个指南章节启动一个 sub-agent。每个 sub-agent：

仅依据其分配的指南文件中的规则进行审查

将发现输出到

<current-working-directory>/review/<SectionName>.md

报告以下信息：文件路径、行号、代码片段和违反的具体规则

Agent 调用流程：

读取 Agent 模板：从
```
agents/guideline-section-reviewer.md
```
读取 Agent 定义
替换参数：将 Agent 文件中的模板变量替换为实际值：
- ```
{{SECTION_NAME}}
```
  ：章节显示名称（例如，“Functions”）
- ```
{{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 填写
启动 Agent：使用 Task tool，令
```
subagent_type=general
```
，并将替换后的 prompt 作为 Agent 指令

调用示例：

对于“Functions”章节：
- 从 `agents/guideline-section-reviewer.md` 读取 Agent 模板
- 替换：SECTION_NAME="Functions", SECTION_FILE="Functions.md" 等
- 使用替换后的 prompt 启动 guideline-section-reviewer Agent

Agent 将执行以下操作：

从此 plugin 的
```
references/Content/
```
目录读取指南章节
依据该章节的规则审查目标文件
将发现输出到
```
<OUTPUT_DIR>/<SECTION_NAME>.md
```
报告文件路径、行号、代码片段和具体的规则违规项

Step 3: Wait for All Sub-Agents

第 3 步：等待所有 Sub-Agents 完成

After launching all sub-agents, collect their task IDs and wait for completion:

Waiting process:

Track task IDs: Store the task ID returned by each Task tool invocation
Wait for completion: For each task ID, use
```
TaskOutput
```
with:
- ```
task_id
```
  : The task ID from the sub-agent launch
- ```
block=true
```
  : Wait until the sub-agent completes
- ```
timeout=600000
```
  (10 minutes): Maximum wait time per agent
Verify success: Check that each sub-agent:
- Completed without errors
- Created its output file in
```
<current-working-directory>/review/<SectionName>.md
```
- Did not modify any source files

Error handling:

If a sub-agent fails: Report the error to the user and continue with other agents
If timeout occurs: Note which agents timed out and report to user
If output file missing: Indicate which section's review is incomplete

Verification checklist:

All sub-agents have been launched
All sub-agents have completed (or reported failures)
Output files exist for each completed section
No source files were modified

启动所有 sub-agent 后，收集其 task ID 并等待完成：

等待流程：

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

错误处理：

如果某个 sub-agent 失败：向用户报告错误，并继续执行其他 Agent
如果发生超时：注明哪些 Agent 超时，并向用户报告
如果输出文件缺失：指出哪个章节的审查未完成

验证清单：

已启动所有 sub-agent
所有 sub-agent 均已完成（或已报告失败）
每个已完成章节均存在输出文件
未修改任何源文件

Step 4: Generate Summary

第 4 步：生成摘要

After all sub-agents complete, create

<current-working-directory>/review/Summary.md

with a comprehensive analysis of all findings.

Process:

Read all section review files from
```
<current-working-directory>/review/*.md
```
(excluding Summary.md itself)
Aggregate violation counts, affected files, and rule violations
Generate summary using the template below

Summary.md template:

markdown

undefined

所有 sub-agent 完成后，创建

<current-working-directory>/review/Summary.md

，并对所有发现进行综合分析。

流程：

读取
```
<current-working-directory>/review/*.md
```
中的所有章节审查文件（排除 Summary.md 本身）
汇总违规项数量、受影响文件和规则违规项
使用以下模板生成摘要

Summary.md 模板：

markdown

undefined

C++ Core Guidelines Review Summary

C++ Core Guidelines 审查摘要

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>

日期: YYYY-MM-DD 审查范围: <审查的文件/目录> 已完成审查的章节总数: <完成的章节数量> 发现的违规项总数: <所有章节中的总数>

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]

章节	违规项数	最常违反的规则
Functions	N	F.15, ...
Classes and Class Hierarchies	N	C.7, ...
Resource Management	N	R.1, ...
[继续处理所有章节]

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]

文件	违规项总数	主要违规类别
path/to/file1.cpp	N	资源管理、错误处理
path/to/file2.h	M	const 正确性、接口
[继续处理所有受影响文件]

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]

排名	规则 ID	规则摘要	数量
1	F.15	优先采用简单且默认的构造方式	N
2	R.3	不应使用原始指针	M
[继续处理]

Critical Findings

关键发现

High-Priority Issues

高优先级问题

<列出影响严重或涉及安全问题的违规项>

Most Common Patterns

最常见模式

<识别代码库中反复出现的违规模式>

Detailed Section Breakdown

详细章节拆分

Functions (N violations)

Functions（N 项违规）

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

<简要总结该章节的关键违规项> 参见：Functions.md

Classes and Class Hierarchies (N violations)

Classes and Class Hierarchies（N 项违规）

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

<简要总结该章节的关键违规项> 参见：Classes and Class Hierarchies.md

[Continue for all sections with violations]

[对所有存在违规项的章节继续处理]

Recommendations

建议

Immediate Actions: <Critical violations that should be addressed soon>
Process Improvements: <Suggestions to avoid common violations>
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>


**Key requirements for summary**:
- Include exact violation counts aggregated from all section reports
- Sort tables by violation count (descending) where applicable
- Link to individual section reports for detailed findings
- Highlight patterns and systemic issues
- Provide actionable recommendations based on findings

已完成章节：<已完成的章节列表>
已跳过/失败的章节：<存在问题的章节列表>
审查文件总数：<数量>
已审查代码行数：<如果可用>


**摘要关键要求**：
- 包含从所有章节报告汇总得到的准确违规项数量
- 在适用情况下，按违规项数量降序排列表格
- 链接到各个章节报告以查看详细发现
- 突出显示反复出现的模式和系统性问题
- 根据发现提供可执行的建议

Critical Constraints (Highest Priority)

关键约束（最高优先级）

No modifications: This skill and all sub-agents MUST NOT modify reviewed files. Write operations ONLY to
```
<current-working-directory>/review/
```
directory.
Main session non-involvement: Main conversation MUST NOT perform code review. Only coordinate sub-agents.
Section-specific enforcement: Each sub-agent reviews ONLY against its assigned section. Cross-section violations are not reported.
Rule correspondence: Every reported violation MUST map to a specific guideline rule. Unmappable findings are invalid.
High confidence threshold: Only report violations with high confidence. Uncertain cases must be omitted.
Violations only: Report ONLY guideline violations. Do NOT report code that follows guidelines correctly. Positive/conforming code must NOT appear in findings.

禁止修改：此 skill 及所有 sub-agent 绝不能修改被审查的文件。写入操作仅限
```
<current-working-directory>/review/
```
目录。
主会话不得参与审查：主对话绝不能执行代码审查，只能协调 sub-agent。
章节专项约束：每个 sub-agent 仅依据其分配的章节进行审查。不得报告跨章节违规项。
规则对应关系：每项报告的违规项都必须映射到具体指南规则。无法映射的发现均无效。
高置信度阈值：仅报告高置信度的违规项。必须省略不确定的情况。
仅报告违规项：只报告指南违规项。不得报告符合指南的代码。符合规范的代码不得出现在发现中。

C++ Core Guidelines Structure

C++ Core Guidelines 结构

The C++ Core Guidelines reference files are bundled in this skill's

references/

directory:

```
Introduction.md
```
- Overview and glossary
```
Content/
```
- Individual guideline sections

Each section contains multiple rules with:

Rule identifier (e.g., "C.7", "F.15")
Rule statement
Rationale (Reason)
Examples (positive/negative)
Exceptions (if applicable)
Enforcement suggestions

C++ Core Guidelines 参考文件打包在此 skill 的

references/

目录中：

```
Introduction.md
```
- 概述和术语表
```
Content/
```
- 各个指南章节

每个章节包含多条规则，每条规则具有：

规则标识符（例如，“C.7”、“F.15”）
规则陈述
理由（Reason）
示例（正例/反例）
例外（如适用）
强制性检查建议

User Interaction Patterns

用户交互模式

Example 1: Review specific files

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

→ Clarify scope, then launch sub-agents for those files.

Example 2: Review directory

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

→ Clarify file patterns and exclusions, then launch sub-agents.

Example 3: Review against specific sections

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

→ Launch only those two sub-agents.

示例 1：审查特定文件

用户：“根据 C++ Core Guidelines 审查 src/transaction.cpp 和 src/account.h”

→ 明确范围后，为这些文件启动 sub-agent。

示例 2：审查目录

用户：“审查 services/ 目录中的所有 C++ 文件”

→ 明确文件模式和排除项，然后为这些文件启动 sub-agent。

示例 3：依据特定章节审查

用户：“仅依据 Resource Management 和 Error Handling 指南进行审查”

→ 仅启动这两个章节对应的 sub-agent。