9uiLe quality-review
既存コード、差分、PR、リポジトリを ISO/IEC 25010:2023 の 9 特性・40 副特性でレビューする。測れるものは先に静的解析ツールへ委譲し、LLM の判断は数値化できない残余に閉じ込める。各指摘には重大度、層、箇所、根拠リファレンスを付ける。
$PLUGIN_ROOT は、Claude Code では ${CLAUDE_PLUGIN_ROOT}、Codex ではこの SKILL.md の 2 階層上（quality-architect ディレクトリ）を指す。
必ず $PLUGIN_ROOT/references/00-overview.md §5.1 と $PLUGIN_ROOT/references/static-evaluation.md を読む。矛盾があれば 00-overview.md §5.1 を優先する。指摘に使う特性だけ $PLUGIN_ROOT/references/0N-*.md を読む。設定とプロファイルは $PLUGIN_ROOT/quality-gates.yml を読む。
0. 入口と資産検出
新規アーキテクチャ、非機能要件、ADR、まだ存在しない設計案の比較は quality-architecture へハンドオフする。既存コードの設計妥当性レビューはこのスキルで扱う。design-level 指摘が支配的で局所修正では解けない場合だけ、置換設計の検討として quality-architecture への前方ハンドオフを報告に書く。
レビュー対象が指定されなければ現在の差分を既定にする。大規模なら重点特性を提案する。trivial diff なら §2.1 の軽量フォーマットを使える。
最初に対象リポジトリで資産を検出し、出力冒頭へ転記する。チャット貼り付けのみで対象パスが無い場合は 対象パス未指定（チャット入力のみ） と書く。
{
test -f quality-gate-result.json && echo "HAS quality-gate-result.json";
test -f coupling-gate-result.json && echo "HAS coupling-gate-result.json";
find . -maxdepth 2 -type f \( -name 'quality-gate-*.sh' -o -name 'coupling-gate-*.sh' \) 2>/dev/null | sed 's/^/HAS script: /';
find .github/workflows -maxdepth 1 -type f 2>/dev/null | grep -Ei 'quality|lint|coverage|security|coupling' | sed 's/^/HAS workflow: /';
for f in Package.swift .swiftlint.yml .periphery.yml Mintfile package.json pnpm-workspace.yaml tsconfig.json pyproject.toml requirements.txt go.mod Cargo.toml pom.xml build.gradle build.gradle.kts; do
test -f "$f" && echo "HAS manifest/config: $f";
done
} 2>&1 | sort -u
1. 手順
範囲と言語を確定する
git diff、対象ファイル、PR、ディレクトリ、リポジトリ全体のどれかを明記する。- 対象言語を特定し、
quality-gates.ymlに該当 profile があるか確認する。profile が無い言語はprofile: noneとし、step 3 のフォールバックを使う。 - 版は原則
ISO/IEC 25010:2023。ユーザーが 2011 版を明示した場合だけ2011と書く。
設計妥当性を先に見る
- 個別欠陥の前に、採用されている設計判断、境界、依存方向、失敗モード、制約との整合をトップダウンに評価する。
- この所見は考察パートとして扱い、決定論パートで確定した measured / threshold / verdict を上書きしない。
- design-level / implementation-level は重大度と直交するラベルとして全指摘に付ける。
決定論パートの source を選ぶ
- 検出したプロジェクト側の lint / coverage / build 設定がしきい値を持つ場合は、プラグイン同梱
quality-gates.ymlの既定値より優先する。 ci-artifact: 既存quality-gate-result.jsonを最優先で読む。mtime が 24 時間以内か、commit_shaがあればgit rev-parse HEADと一致するか、targetが対象範囲と矛盾しないかを確認する。不一致なら使わずartifact mismatchと書いて次へ進む。メタデータが無い場合はartifact-integrity: unknownと明記して採否理由を書く。wrapper: profile があり$PLUGIN_ROOT/scripts/quality-gate-<profile>.shが存在する場合、ユーザー確認または事前許可の上で実行する。individual: wrapper が無い場合、quality-gates.ymlの profile 内runを個別に実行する。profile が無い言語では lizard、jscpd、Trivy、Semgrep など言語横断ツールが利用できればmeasured-onlyとして実測値だけ載せ、threshold 未定義の PASS/FAIL を作らない。none: いずれも不可なら全行未実行 (skipped: <理由>)とし、総合inconclusiveを宣言する。
- 検出したプロジェクト側の lint / coverage / build 設定がしきい値を持つ場合は、プラグイン同梱
実行確認と非対話フォールバック
- ビルド、テスト、ネットワーク、依存インストール、長時間実行を伴うコマンドは事前確認を取る。ただしユーザーが既に実行許可を明言している場合は確認を省ける。
- 質問できない環境では、検証済み artifact を採用し、次に副作用の小さいローカル静的ツールだけを試し、最後は
noneに落とす。確認なしにビルド、テスト、ネットワーク実行へ進まない。
差分帰属を付ける
- 差分/PR レビューで repo-wide 計測を使う場合、各 FAIL に
diff-caused/pre-existing/unknownを付ける。 path:lineが差分 hunks に含まれる、または base/head の両方を測って head だけ悪化した場合はdiff-caused。差分外の既存箇所ならpre-existing。判定材料が無ければunknown。pre-existingは品質リスクとして報告してよいが、その PR の回帰として断定しない。
- 差分/PR レビューで repo-wide 計測を使う場合、各 FAIL に
9 特性トリアージを行う
00-overview.mdの特性一覧だけを使い、9 特性それぞれを精査対象/該当薄に分類する。各行に 1 行根拠を書く。- 精査対象の特性ファイルだけ読む。該当薄もスコアカードには残し、「見ていない」のではなく「低リスク判断」として可視化する。
指摘を構造化する
- 必須項目: 特性/副特性、層、重大度、箇所
path:line、問題、推奨、根拠リファレンス、数値根拠、差分帰属。 - 重大度: Critical / High / Medium / Low。Critical はデータ漏洩、認証回避、全断、データ破壊、安全上の重大危険など即時対応が必要な欠陥。High は本番障害、重要経路のセキュリティ/契約破壊、局所修正不能な設計境界誤り。Medium は局所的な不具合、劣化、将来リスク。Low は可読性、軽微な規約、低確率リスク。保守性では、変更不能、局所修正不能な境界誤り、広範な障害誘発、修正コストの非線形増大を High 以上の根拠にできる。単なる閾値超過だけで Critical にしない。
- 結合、凝集、複雑度、モジュール境界の指摘では
$PLUGIN_ROOT/references/07a-coupling-deep-dive.md§6.3.1 の catalog を読み、下げる軸と具体手順を 1〜2 行で書く。
- 必須項目: 特性/副特性、層、重大度、箇所
07a 結合シグナルは必要時だけ読む
coupling-gate-result.jsonを採用する、または coupling wrapper を明示的に実行する場合だけ$PLUGIN_ROOT/references/07a-review-integration.mdを読む。- 未検出/未選択なら 07a merge contract は読まず、報告に
07a: 未適用とだけ書く。
報告する
- 最重要指摘 3〜5 件と全体評価を要約する。
--commentなどで PR 投稿を指示された場合は、path:lineがある指摘を inline comment 候補として重複に注意して投稿する。
2. 出力フォーマット
通常レビューでは以下を省略しない。
## 品質レビュー（ISO/IEC 25010）
0. プロジェクト資産インベントリ
<§0 の検出結果。無ければ「該当資産なし」>
サマリ
- 対象 / 範囲 / 版(2011|2023) / 言語・適用 profile
- 決定論パート source: ci-artifact | wrapper | individual | none
- artifact-integrity: verified | mismatch | unknown | not-used
- 設計妥当性: 妥当 | 要再考（design-level 指摘 N 件）
- 07a: 未適用 | artifact | wrapper
- 総合: pass | fail | inconclusive | review-only
### 決定論パート（静的解析ツール由来・再現可能）
| 指標 | ツール | measured | threshold | 判定 | scope | attribution | source |
| --- | --- | --- | --- | --- | --- | --- | --- |
| cyclomatic-complexity | lizard | 23 | >20=fail | fail | repo-wide | diff-caused | wrapper |
| dependency-vulnerabilities | Trivy | 未実行 (skipped: tool missing) | HIGH,CRITICAL=0 | skipped | repo-wide | unknown | individual |
| generic-complexity | lizard | 12 | threshold未定義(profileなし) | measured-only | target-only | unknown | individual |
### 9 特性トリアージ
| 特性 | 判定 | 根拠 |
| --- | --- | --- |
| 機能適合性 | 精査対象 | API 契約変更あり |
| 性能効率性 | 該当薄 | 実行経路変更なし |
| ...9 特性すべて... | | |
### スコアカード（考察パート）
| 特性 | 評価 | 根拠種別 | 所見 |
| --- | --- | --- | --- |
| 保守性 | △ | deterministic+LLM(推測) | 最大 CCN 超過、境界責務が不明瞭 |
### 指摘
1. [High][design-level][保守性/モジュール性] path/to/file.swift:42
- 問題:
- 推奨:
- 削減アクション:
- 根拠:
- 数値根拠:
- 差分帰属:
measured は空欄禁止。数値または 未実行 (skipped: <理由>) のどちらかを書く。profile が無く閾値未定義の場合は、measured に実測値を書き、判定 を measured-only にする。全行 skipped ならサマリで inconclusive を宣言する。本文でしきい値を引用する場合、その指標は決定論パートに同じ measured/threshold/source で存在していなければならない。
2.1 trivial diff fast-path
typo、コメント、ドキュメント、非実行メタデータのみの差分で、依存、設定、API、権限、ビルド、テスト、セキュリティ境界に影響しない場合は軽量フォーマットを使える。
- 資産インベントリ、サマリ、決定論パート source、設計妥当性は残す。
- 決定論パートは
review-onlyまたはnone(全 skipped)でよい。 - 9 特性は「精査対象」と「その他 8 特性: 該当薄（trivial diff のため）」のように圧縮してよい。
- High 以上の懸念が見つかった時点で通常フォーマットへ戻す。
3. 引用規律
全指摘に学術論文、規格、公式文書、または本プラグインの参照ファイルを引用する。参照ファイルに無い指摘は 根拠リファレンスなし（推測） と明記し、断定を弱める。セキュリティは OWASP/NIST 等の一次情報を優先する。ISO/IEC 25010 の特性名だけを根拠にせず、可能なら該当副特性と品質測度も書く。
4. 成功基準
最終応答前に確認する。
- 決定論パートの数値は artifact または実行結果由来で、捏造が無い。
- 考察パートが決定論パートの measured / threshold / verdict を上書きしていない。
- skipped / measured-only / inconclusive が正しく表示されている。
- 9 特性の可視化があり、精査対象と該当薄の根拠がある。
- 各指摘に層、重大度、箇所、引用、数値根拠、差分帰属がある。
- 既存コードレビューと新規設計検討のルーティングが混ざっていない。
5. 禁止事項
- 決定論パートを試さずに LLM 単独で数値を出す。
- profile 未定義の言語で Swift 固有ツールや Swift しきい値を既定扱いする。
- repo-wide FAIL を差分起因と断定する。
- freshness/commit/target が不一致の artifact を verified として使う。
- 確認なしにビルド、テスト、ネットワーク実行へ進む。
- 07a シグナルで verdict を反転する、または severity を上方修正する。