qt-cpp-review

Qt Code Review

Qt6 C++ コードの読み取り専用レビューです。まず決定論的な Python リンターを実行し、次にエージェント主導で 6 つのルールドメインを詳細に分析して、最後に統合レポートを作成します。

このスキルを使用するタイミング

• レビューに関する依頼：「review」、「check」、「audit」、「look over」、「code review」、「sanity check」
• コードをコミットする前に提案してください

引数

• /qt-cpp-review — 汎用的な Qt6 C++ ルール
• /qt-cpp-review framework — Qt フレームワーク／モジュールのルールも適用します （バイナリー互換性、エクスポート、d-pointer、qdoc、QML のバージョン管理）

フレームワークモード

$ARGUMENTS に "framework" が含まれる場合は有効にします。それ以外の場合、リンターの実行結果または簡単な Grep で次のシグナルが2 つ以上見つかったら、フレームワークモードをユーザーに提案します。ただし、自分で有効にはしません。 QT_BEGIN_NAMESPACE、任意の Q_*_EXPORT マクロ、<QtModule/private/*_p.h> のインクルード、Q_DECLARE_PRIVATE／Q_D()／Q_Q()、CMakeLists.txt 内の qt_internal_add_module、リポジトリのルートにある sync.profile または .qmake.conf。

有効にした場合：リンターに --framework を渡し、A2 または A4 を担当するエージェントのプロンプトで references/qt-framework-checklist.md を指定します（エージェントは agent-rules.md の末尾にある対応表に従って適用します）。差分スコープでは、FW-CMT ルールに照らしてコミットメッセージも自分で確認します。sed -n '/^## Commit Message/,$p' references/qt-framework-checklist.md で該当セクションのみ読み込みます。

スコープの検出

差分スコープ — 「this commit」、「these changes」、「the diff」、「what I changed」、「staged changes」、「before I commit」。範囲は HEAD（作業ツリーとインデックス）、ステージ済みの変更のみを対象とする --cached、または「this commit」に対する HEAD~1..HEAD です。差分そのものは読み込まないでください。リンターの --diff モード（フェーズ 1）は、変更行数とともに変更ファイルを一覧表示し、変更行上の指摘のみを報告します。

コードベーススコープ — 「review the codebase」、「audit src/」、またはコミットに関する表現を含まない明示的なパス。指定されたパスの下にある *.cpp、*.h、*.hpp を Glob で検索します。

トークン予算のルール

これらのルールはレビューのコストを抑えるためのものです。必ず守ってください。

1. 参照ファイルをメインコンテキストに読み込まないでください。 エージェントは references/agent-rules.md を自分で読み込みます。絶対パスとセクション ID を渡してください。インライン実行（フェーズ 2）の場合に限り、メインコンテキストに読み込みます。リンターのメッセージはそれだけで内容が分かります。チェックリストは人間向けです。
2. リンターの結果は --summary 形式で渡してください（ルールごとにグループ化し、ルートからの相対パスを表示するのは一度のみ）。行ごとの生の一覧は渡さないでください。
3. 内容を貼り付けず、エージェントにはその場所を示してください。 プロンプトに書くトークンはすべて、レビューで最もコストの高い、オーケストレーションを行うモデルの出力になります。プロンプトにはパス、コマンド、セクション ID を記載し、エージェント自身がルール、ファイル、差分を読み込みます。差分スコープでは、ハンクの代わりに git diff -U50 <range> -- <files> コマンドをエージェントに渡します。ほかのファイルを読むのは、特定のシンボルを追跡する場合に限ります。
4. スコープに応じてエージェント数を調整してください（フェーズ 2 を参照）。スコープが小さい場合はエージェントを起動せず、大きい場合はおおむね同じ行数になるように分割します。
5. ハーネスに専用のレビューエージェントがある場合は、それを使用してください。 cpp-review-agent の定義（プラグインと一緒にインストールされている場合は qt-development-skills:cpp-review-agent、手動でコピーした場合は cpp-review-agent として一覧表示されます）が利用可能なら、それを使ってエージェントを起動します（読み取り専用で、ツールは Read、Grep、Glob、読み取り専用 Bash に限定）。利用できない場合は、ハーネスの汎用エージェントを使用してください。この定義はスキルの外にあるプラグインの agents/ ディレクトリにあるため、スキル単独でコピーした場合や、ハーネスに agents/ がインストールされていない場合は存在しません。その場合は各プロンプトに次の 1 行を追加してください：読み取り専用（Bash は cat、grep、awk、git diff、git show のみ）；表示された行番号から file:line を取得する；差分スコープではファイルを再読しない；シンボル追跡の場合に限り、ほかのファイルを Grep または Read する；推測を多数挙げるより、確認できた指摘を少数に絞る。

実行順序

フェーズを省略してはいけません。

フェーズ 1：決定論的なリント

# codebase scope
python3 <skill>/references/lint-scripts/qt_review_lint.py --summary [--framework] <files...>
# diff scope, run inside the repository; no file arguments
python3 <skill>/references/lint-scripts/qt_review_lint.py --summary [--framework] --diff=<range>
# fall back to `python` if python3 is not found

Python 3.7 以降が必要で、依存関係はありません。Python を利用できない場合は警告して続行してください（差分スコープでは、git diff --stat <range> からファイル一覧を取得します）。リント結果を最終的な判断として扱い、その出力を疑ってはいけません。ルールファミリー：INC、DEP、PAT、MDL、ERR、LCY、API、ENM、TMO、CND、VAL、HDR、TRN、VAR（60 以上のチェック）。終了コード 1 は単に指摘事項があることを意味し、2 は使い方または git のエラーを意味します。

フェーズ 2：詳細分析（インライン、またはシャードごとに 1 エージェント）

分析内容は references/agent-rules.md の 6 つのセクションです。 エージェントは自分でこれを読みます。インラインで実行する場合に限り、自分で読んでください。

セクション	ミッション
A1	モデルの契約
A2	所有権とライフサイクル
A3	スレッドセーフティ
A4	API、命名、C++ の正確性
A5	エラー処理と検証
A6	パフォーマンスとコード品質

スコープのサイズに応じて、並列化の規模を選択してください。対象ファイルの行数（差分スコープでは変更行数）を、リントの概要または wc -l から取得します。1 ブロックは約 2,500 行です。分割は行数だけで決め、ファイル数は考慮しません。

スコープ	エージェント
2,500 行以下	0（インライン）
2,500 行を超える	シャードごとに 1 つ、ceil(lines / 2500) シャード

インライン。 小さなスコープでは、エージェントを使うコストに見合いません。エージェントはそれぞれコンテキストを再構築するため、同じ指摘事項に対するレビューのトークンコストがおよそ 2 倍になります。自分で分析してください。下記のエージェントプロンプトに示す 1 回の Bash 呼び出しで references/agent-rules.md とファイル（または差分）を読み、同じルール、信頼度のしきい値、出力形式に従って A1～A6 を一度に適用します。リント結果の行を再度報告してはいけません。また、コードが単純に見えるからといって、上限を超えた範囲をインラインで実行してはいけません。Agents: 0 (inline) と報告してください。

シャード。 ファイルをディレクトリ順に並べ、n = ceil(lines / 2500) 個のシャードに、それぞれ約 lines / n 行となるように分割します。シャード内のファイル数は問いません。可能であればディレクトリ単位でまとめ、クラスのヘッダーとソース、相互参照するモデルとビューが同じシャードに含まれるようにします。大きなディレクトリはファイル単位で分割してください。シャードより大きいファイルは、単独のシャードにします。各シャードのエージェントは、そのシャードだけに対して 6 つのセクションすべてを適用します。また、シンボルを追跡するためにスコープ全体を Grep してもかまいません。一度に最大 6 つのシャードエージェントを実行し、残りは第 2 波で実行します。シャードをまたぐチェック（所有権、モデルの契約、重複したロジック）は可能な範囲で行い、その旨をレポートのヘッダーに記載してください。

エージェントは並列に起動し、シャードにちなんだ名前を付けます（例：「Review shard 2/6: src/models」）。各プロンプトは短くし、次の項目だけを含めます。

1. references/agent-rules.md の絶対パスと適用するセクション ID（A1～A6）。フレームワークモードの A2 および A4 エージェントには、references/qt-framework-checklist.md の絶対パスも含めます。

2. リントの概要にあるルートディレクトリ、ルートからの相対パスで示した対象ファイル、および差分スコープの場合は、それらに対する git diff -U50 <range> -- <files> コマンド

3. そのエージェントが担当するファイルだけのリント概要行（シャードエージェントに他のシャードの行は不要です）。「do not re-report these lines」という指示も含めます。

4. 分析前に 1 回の Bash 呼び出しですべてを読み込む指示と、ルールファイル冒頭の形式で指摘事項を返す指示。各ツール呼び出しではエージェントのコンテキスト全体が再送信されるため、大きなスコープでは、ファイルごとに 1 回 Read する代わりに、まとめて 1 回読み込むのが最大の節約になります。どちらの形式も、file:line の場所に必要なファイルごとの行番号を出力します（複数ファイルへの cat -n は通し番号を振り、git diff には行番号がありません）。

   # codebase scope
   cd <root> && cat <rules> && for f in <files...>; do echo "== $f"; cat -n "$f"; done
   # diff scope; numbers context and added lines with the new-file line
   cd <root> && cat <rules> && git diff -U50 <range> -- <files> | awk '/^@@/{split($3,a,/[+,]/);n=a[2];h=1;print;next} /^diff /{h=0} h&&/^[ +]/{printf "%5d %s\n",n++,$0;next} {print}'
   

エージェントは読み取り専用であり、ファイルを編集してはいけません。エージェントを利用できないツールでは、そのツールがサポートするプロンプトチェーンまたはサブプロセスを使って各ミッションを実行してください。要件は同じです。

フェーズ 3：統合

Lint の指摘とエージェントの指摘を統合します。ファイル・行・問題の組み合わせで重複を排除します。重複する指摘の信頼度が異なる場合は、スコアが最も高いブロックとそのトレースを採用し、スコアを平均しないでください。以下の形式でレポートを作成します。

信頼度スコア

信頼度	意味	アクション
80-100	シンボルトレースでルール違反を確認済み	指摘
60-79	可能性は高いものの、完全には検証できない（例：プログラム全体の解析が必要な noexcept、外部から呼び出される可能性のあるデッドコード）	調査対象（最大 10 件）
<60	疑いのみ	抑制

出力形式

この構造を厳密に使用してください。Lint の指摘はルールごとにまとめ、それぞれに緩和策を 1 つ付けます。完全なブロックを記載するのは詳細分析の指摘のみです。

## Qt Code Review Report

**Scope**: [diff: `git diff HEAD~1..HEAD` | files: <paths>]
**Files reviewed**: N
**Issues found**: N (M from lint, K from deep analysis)
**Agents**: N (shards ... | inline)
**Framework mode**: [on / off]

---

### Lint findings

| Rule | Count | Locations | Mitigation |
|---|---|---|---|
| LCY-2 QObject created with new but no parent | 3 | `main.cpp:12,40`, `widget.cpp:88` | Pass a parent or hold in a smart pointer. |
| ... | | | |

---

### Deep analysis findings

#### [D-NNN] <Short title>
- **File**: `path/to/file.cpp:42`
- **Category**: <A1-A6 mission name>
- **Confidence**: NN/100
- **Finding**: <what is wrong>
- **Trace**: <symbols followed, what was checked>
- **Mitigation**: <what to do, in prose — no code patches>

---

### Investigation targets (human verification needed)

#### [I-NNN] <Short title>
- **File**: `path/to/file.cpp:42`
- **Category**: <A1-A6 mission name>
- **Confidence**: NN/100
- **Finding**: <what is suspected>
- **Unverified because**: <what could not be confirmed>
- **How to verify**: <specific action for the reviewer>

---

### Summary

| Category | Lint | Deep | Investigate | Total |
|---|---|---|---|---|
| ... | N | N | N | N |
| **Total** | **M** | **K** | **I** | **N** |

Findings below confidence 60 are suppressed.

参考資料

• references/agent-rules.md — エージェントのミッション A1-A6 とエージェントの出力形式（エージェントが読み込み、オーケストレーターは読み込みません）
• references/qt-review-checklist.md — 共通のルール ID と根拠（人間向けの参考資料で、レビュー中には読み込まれません）
• references/qt-framework-checklist.md — フレームワークのルール（フレームワークモードで A2 および A4 エージェントが読み込みます）
• references/qt-deprecated-classes.md — DEP lint ルールの背景情報（人間向けの参考資料）
• references/lint-scripts/qt_review_lint.py — 1 回のパスで実行するリンター。--summary はグループ化された出力、--diff=<range> は変更行のみ、--framework はモジュールのルールに使用します