qt-qml-review

Qt QML コードレビュー

Qt6 QML コードを読み取り専用でレビューします。まず決定論的な Python リンターを実行し（利用可能な場合は qmllint も統合します）、次にエージェント主導で7つのルールドメインにわたる詳細な分析を行い、最後に統合レポートを1つ作成します。ユーザーが QML コードをコミットする前に、このレビューを提案してください。

スコープの検出

差分スコープ -- 「このコミット」「これらの変更」「差分」「変更した内容」「ステージ済みの変更」「コミットする前」などの表現がある場合です。範囲は HEAD（作業ツリーとインデックス）、ステージ済み変更のみの場合は --cached、「このコミット」の場合は HEAD~1..HEAD です。差分自体は読み込まないでください。リンターの --diff モード（フェーズ1）で、変更行数とともに変更ファイルを一覧表示し、変更行に関する指摘のみを報告します。

コードベーススコープ -- 「コードベースをレビュー」「src/ を監査」などの表現、またはコミットに関する表現を伴わない明示的なパスがある場合です。指定されたパス以下の *.qml を glob で検索します。

トークン予算のルール

これらのルールはレビューのコストを抑えるためにあります。必ず従ってください。

1. 参照ファイルをメインコンテキストに読み込まないでください。 エージェント自身が references/agent-rules.md を読み込みます。絶対パスとセクション ID を渡してください。インライン実行（フェーズ2）の場合に限り、メインコンテキストで読み込みます。リンターのメッセージはそれだけで意味が分かるため、チェックリストは人間向けです。
2. リンターの結果は --summary 形式で渡してください。 ルールごとにまとめ、ルートへの相対パスを一度だけ示します。行ごとの生の一覧や qmllint の JSON は渡さないでください。
3. 内容を貼り付けず、エージェントには参照先を示してください。 プロンプトに書き込むトークンはすべて、レビューで最も高コストなオーケストレーションモデル上で出力されます。プロンプトにはパス、コマンド、セクション ID を記載し、ルール、ファイル、差分はエージェントに読み込ませます。差分スコープでは、ハンクの代わりに git diff -U50 <range> -- <files> コマンドを渡し、特定のシンボルをたどる場合に限り、他のファイルを読み込ませます。
4. スコープに応じてエージェントの数を調整してください（フェーズ2を参照）。小さなスコープではエージェントを起動せず、大きなスコープでは行数がほぼ均等になるようにシャードに分割します。
5. ツールに専用のレビューエージェントがある場合は、それを使用してください。 このプラグインに qt-development-skills:qml-review-agent の定義が含まれている場合は、それを使ってエージェントを起動してください（読み取り専用、ツールは Read、Grep、Glob、読み取り専用 Bash に制限）。それ以外の場合は、そのツールの汎用エージェントを使用してください。

実行順序

フェーズを決して省略しないでください。

フェーズ1：リンティング（Python リンター + qmllint）

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

Python 3.7 以降が必要で、依存関係はありません。Python を利用できない場合は警告して続行してください（差分スコープでは git diff --stat <range> からファイル一覧を取得します）。リンターの結果を正とし、独自に再判断しないでください。ルールファミリー：IMP、ORD、BND、LAY、LDR、DEL、STA、IMG、PRF、STY、SIG、ERR、JS（48以上のチェック）。終了コード1は指摘があることを示すだけです。2は使用方法または git のエラーを示します。

--qmllint を指定すると qmllint も実行され、警告は QL:<id> の行として統合されます。QML モジュールを含むビルドディレクトリには --qmllint-args="-I <dir>" を追加してください。リンターは $QT_HOST_PATH/bin、PATH、qtpaths または qmake が報告するホストの bin ディレクトリ、および Qt オンラインインストーラーの ~/Qt、C:\Qt、/opt/Qt 以下にある最新の Qt 6 キット（<version>/<kit>/bin。キットは gcc_64、macos、msvc2022_64、mingw_64 など）を検索します。not available と報告されても、Qt が別の場所（カスタムインストーラーパス、またはプロジェクトの CMakeCache.txt にある CMAKE_PREFIX_PATH）にインストールされている場合は、--qmllint=<that kit>/bin を指定して一度だけ再実行してください。バイナリまたはその bin ディレクトリを指定できます。それ以上は検索しないでください。表示された qmllint: のステータスをレポートヘッダーにそのまま記載してください。型レベルの問題は qmllint の結果を正とし、スタイル、順序、パフォーマンスのパターンは Python リンターの結果を正とします。

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

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

セクション	ミッション
A1	バインディングとプロパティ
A2	レイアウトとアンカリング
A3	コンポーネントの読み込みとライフサイクル
A4	ListView とデリゲート
A5	状態、遷移、移行
A6	パフォーマンスとコード品質
A7	ロジックと配線

スコープのサイズに応じて、分割数を選択します。スコープ内のファイルの行数（差分スコープでは変更された行数）を、lint のサマリーまたは wc -l から数えます。1ブロックは約1,500行です。分割は行数だけで決め、ファイル数は考慮しません。

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

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

シャード。 ファイルをディレクトリ順に並べ、n = ceil(lines / 1500) 個のシャードに、各シャードが約 lines / n 行になるよう分割します。シャードに含まれるファイル数は問いません。可能な場合はディレクトリを同じシャードにまとめ、コンポーネントと、それをインスタンス化するファイルが同じシャードに入るようにします。大きなディレクトリはファイル単位で分割します。シャードより大きなファイルは、単独で1つのシャードにします。各シャードのエージェントは、そのシャードだけに対して7つのセクションすべてを適用し、ID やモデルのロールを追跡するためにスコープ全体を Grep してもかまいません。シャードエージェントは一度に最大6つまで実行し、残りは2回目の実行で処理します。シャードをまたぐチェック（ID、モデルのロール）はベストエフォートとなるため、レポートのヘッダーにその旨を記載してください。

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

1. references/agent-rules.md の絶対パスと、適用するセクション ID（A1～A7）

2. lint サマリーに記載されたルートディレクトリ、そこからの相対パスで示したスコープ内のファイル、差分スコープの場合はそれらに対する git diff -U50 <range> -- <files> コマンド

3. そのエージェントが担当するファイルだけの lint サマリー行（QL: 行を含む）。シャードエージェントに他のシャードの行は不要です。「これらの行は再報告しない」という指示も含めます。

4. 分析前に1回の Bash 呼び出しですべてを読み込む指示と、ルールファイルの冒頭にある形式で指摘を返す指示。ツール呼び出しのたびにエージェントのコンテキスト全体が再送信されるため、複数のファイルを一括で読み込む方法は、大規模なスコープにおいて最も大きな節約になります。どちらの方法でも、file:line の位置を示すファイルごとの行番号が出力されます（複数ファイルに対する cat -n は1つの連続した番号を付け、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}'
   

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

Phase 3：統合

lint とエージェントの指摘を統合します。ファイル＋行＋問題が同じものは重複として扱います。信頼度が異なる重複については、スコアを平均せず、最も高いスコアのブロックとその根拠を残します。調査対象は最大10件までとし、エージェントの D-/I- ブロックには連続した番号を振り直します。信頼度が60未満の指摘は除外します。以下の形式でレポートを作成します。

出力形式

この構成を正確に使用してください。lint と qmllint の指摘はルールごとにまとめ、それぞれに軽減策を1つ記載します。完全なブロックを記載するのは詳細分析の指摘のみとし、エージェントの内容を一字一句そのままコピーします。

## QML 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)
**qmllint**: [ran / not available / failed]

---

### Lint findings

| Rule | Count | Locations | Mitigation |
|---|---|---|---|
| IMP-2 Versioned import | 3 | `Main.qml:1,2`, `Panel.qml:1` | Drop the version numbers. |
| ... | | | |

---

### Deep analysis findings

<[D-NNN] blocks from the agents>

---

### Investigation targets (human verification needed)

<[I-NNN] blocks from the agents, at most 10>

---

### 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-A7 とエージェントの 出力形式（エージェントが読み込むもので、オーケストレーターは読み込みません）
• references/qt-qml-review-checklist.md -- 各リンタールールの根拠 （人間向けの参考資料で、レビュー中には読み込まれません）
• references/lint-scripts/qt_qml_lint.py -- 1 回のパスで実行するリンター。 グループ化した出力には --summary、変更行のみには --diff=<range>、 qmllint の統合には --qmllint、ツール連携には --json を使用します

---

Copyright (C) 2026 The Qt Company.