cpp-core-guidelines-review

C++ Core Guidelines のレビュー

概要

並列サブエージェントを起動し、それぞれが特定のガイドラインセクションに照らしてコードを分析することで、C++ Core Guidelines に基づいて C++ コードをレビューします。このスキルにより、違反の特定に高い信頼性を保ちながら、網羅的に確認できます。

ワークフロー

ステップ 1：レビュー範囲の確認

サブエージェントを起動する前に、レビュー範囲をユーザーに確認してください。

1. 対象のファイル／ディレクトリ：レビューする C++ ソースファイルまたはディレクトリはどれですか？
2. ファイルパターン：対象に含めるファイル拡張子は何ですか？（例：.cpp、.h、.hpp）
3. 除外対象：除外するファイルやディレクトリはありますか？

重要：範囲が明確に定義され、曖昧さがなくなるまで先に進まないでください。

ステップ 2：並列サブエージェントの起動

重要な要件：

• references/Content/ 内のすべてのファイルに対して、必ずサブエージェントを 1 つ起動してください。ファイルを省略しないでください。各ガイドラインセクションには、それぞれ専用のサブエージェントが必要です。
• このプラグインの agents/guideline-section-reviewer.md にある guideline-section-reviewer エージェントを、各サブエージェントに使用してください。

並列起動の戦略：パフォーマンスを最大化するため、1 回の応答メッセージで複数の Task ツール呼び出しを送信し、すべてのサブエージェントを並列で起動してください。Task ツールのドキュメントには、「ユーザーがエージェントを『並列で』実行するよう指定した場合、複数の Task ツール使用コンテンツブロックを含む単一のメッセージを必ず送信する」と明記されています。

ガイドラインセクションごとに、サブエージェントを 1 つ起動します。各サブエージェントは、次の処理を行います。

• 割り当てられたガイドラインファイルのルールのみに照らしてレビューします。
• <current-working-directory>/review/<SectionName>.md に指摘事項を出力します。
• 違反について、ファイルパス、行番号、コードスニペット、および違反した具体的なルールを報告します。

エージェントの呼び出し手順：

1. エージェントのテンプレートを読む：agents/guideline-section-reviewer.md からエージェント定義を読み取ります。
2. パラメーターを置換する：エージェントファイル内のテンプレート変数を、次の実値に置き換えます。
   • {{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}}：プレースホルダー。エージェントが値を入力します。
3. エージェントを起動する：subagent_type=general を指定して 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

エージェントは次の処理を行います。

1. プラグインの references/Content/ ディレクトリからガイドラインセクションを読み取ります。
2. そのセクションのルールに照らして対象ファイルをレビューします。
3. 指摘事項を <OUTPUT_DIR>/<SECTION_NAME>.md に出力します。
4. ファイルパス、行番号、コードスニペット、および違反した具体的なルールを報告します。

ステップ 3：すべてのサブエージェントを待機する

すべてのサブエージェントを起動した後、それぞれのタスク ID を収集して、完了を待ちます。

待機プロセス：

1. タスク ID を記録する：各 Task ツールの呼び出しで返されたタスク ID を保存します
2. 完了を待つ：各タスク ID に対して、次の値を指定して TaskOutput を使用します：
   • task_id：サブエージェントの起動時に返されたタスク ID
   • block=true：サブエージェントが完了するまで待機します
   • timeout=600000（10 分）：エージェントごとの最大待機時間
3. 成功を確認する：各サブエージェントについて、次の点を確認します：
   • エラーなく完了したこと
   • <current-working-directory>/review/<SectionName>.md に出力ファイルを作成したこと
   • ソースファイルを変更していないこと

エラー処理：

• サブエージェントが失敗した場合：ユーザーにエラーを報告し、他のエージェントの処理を続行します
• タイムアウトが発生した場合：タイムアウトしたエージェントを記録し、ユーザーに報告します
• 出力ファイルが見つからない場合：レビューが完了していないセクションを示します

確認チェックリスト：

• すべてのサブエージェントを起動した
• すべてのサブエージェントが完了した（または失敗を報告した）
• 完了した各セクションの出力ファイルが存在する
• ソースファイルが変更されていない

ステップ 4：概要を作成する

すべてのサブエージェントが完了したら、すべての指摘事項を包括的に分析した <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. 変更禁止：このスキルおよびすべてのサブエージェントは、レビュー対象ファイルを変更してはなりません。書き込み可能な場所は <current-working-directory>/review/ ディレクトリのみです。
2. メインセッションの不関与：メインの会話でコードレビューを行ってはなりません。サブエージェントの調整のみを行います。
3. セクションごとの適用：各サブエージェントは、割り当てられたセクションの規則に対してのみレビューします。セクションをまたぐ違反は報告しません。
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"

→ 対象範囲を確認してから、それらのファイル用にサブエージェントを起動します。

例 2：ディレクトリをレビューする

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

→ ファイルのパターンと除外対象を確認してから、サブエージェントを起動します。

例 3：特定のセクションに照らしてレビューする

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

→ その 2 つのサブエージェントのみを起動します。