| name | code-quality-review |
| description | 実装済みの差分、PR、コミット、指定ファイルを code quality report の観点でレビューし、実装者の前提や正常系中心の説明を鵜呑みにせず、将来の変更・テスト・運用で品質問題が表面化する条件について敵対的検証を行い、保守性、設計健全性、責務分離、複雑度、テスト容易性、変更容易性、技術的負債を観点別に評価するときに使う。cyclomatic complexity、cognitive complexity、coverage、重複率、関数長、lint/static analysis などの定量シグナルがある場合は補助証拠として必ず取り込む。ユーザーが「quality report」「コード品質」「保守性レビュー」「複雑度」「技術的負債」「設計品質」「品質スコア」「quality gate」などを求めたら必ず使う。仕様違反、セキュリティ、データ破壊など即時欠陥の検出が主目的なら code-review を優先し、次の開発者の迷いやすさが主目的なら code-next-developer-review を優先する。 |
Code Quality Review スキル
このスキルは、実装済みの差分を code quality report として評価するための判断基準と出力形式を定義する。
通常のレビューが「壊れるか」を優先するのに対し、このレビューは「このコードは継続的に変更、テスト、理解、運用できる品質か」を評価する。
基本姿勢
- 品質レビューは、実装者の説明やテスト結果が正しい前提であっても、将来の変更・テスト・運用で品質問題が表面化する条件について敵対的検証を行う
- metric や既存テストを鵜呑みにせず、保守性、変更容易性、テスト容易性、調査しやすさへの実際の影響で判断する
- 人格や意図ではなく、構造、責務、契約、依存、検証可能性、観測可能性を疑う
目的
- コード品質を観点別に可視化する
- 保守性、変更容易性、テスト容易性を下げる要因を特定する
- 技術的負債を、影響と改善優先度が分かる形で報告する
- 利用可能な定量シグナルを品質判断の補助証拠として取り込む
- 実装者やレビュアーが quality gate として使えるレポートを作る
適用範囲
対象は、実装済みの差分、PR、コミット、指定ファイル、またはユーザーが示したコード範囲とする。
主に見るもの:
- 責務分離、凝集度、結合度
- 複雑度、条件分岐、抽象化の粒度
- cyclomatic complexity、cognitive complexity、関数長、ネスト深さ、重複率、coverage、lint / static analysis 結果
- 型、インターフェース、公開契約の明確さ
- テスト容易性、テストの品質、検証しやすさ
- エラー処理、観測可能性、運用時の調査しやすさ
- 命名、構造、コメント、ドキュメントの整合性
主目的にしないもの:
- 仕様違反、回帰、セキュリティ、データ破壊などの即時欠陥検出
- パッチ作成やリファクタリング実装
- 好みのスタイルへの寄せ
即時欠陥を見つけた場合は、品質レポートに混ぜすぎず「通常レビューへ回すべきリスク」として分ける。
レビューの進め方
- 差分または指定範囲を読み、変更された責務、データ、依存関係、テストを把握する
- 変更の目的とコード品質上の評価対象を短く整理する
- ユーザーが metric や tool output を提示している場合は先に読む。提示がない場合は、手元で安全に実行できる範囲の既存コマンド、CI 出力、coverage、lint、static analysis の有無を確認する
references/quality-axes.md から関係する観点だけを使って評価する- 品質低下が将来どの作業で効くかを具体化する
- 指摘を quality signals、スコアカード、重要な発見、改善優先度に分けて出す
全観点を機械的に埋めるより、今回の差分で品質判断に効く観点を深く見る。
Quality Signals
定量指標は、品質判断の入口として扱う。数値は「どこを疑うか」を強く示すが、「なぜ問題か」「今直すべきか」はコードの文脈で判断する。
利用できる場合に見るシグナル:
- Cyclomatic Complexity: 分岐数と独立経路の多さ
- Cognitive Complexity: 人間が制御フローを理解する負荷
- Function / method length: 長すぎる処理、責務混在の候補
- Nesting depth: 条件分岐や例外処理の追跡しづらさ
- Duplication: 変更漏れや仕様分岐の温床
- Fan-in / fan-out: 変更影響の広がり、結合度
- Test coverage: 重要挙動を検証できているかの補助情報
- Lint / static analysis: 未使用コード、複雑度違反、危険 API、型の問題
扱い方:
- ツール出力や CI 結果がある場合は、
Signal, Result, Interpretation, Action に分けて報告する
- ツール出力がない場合は、無理に数値を作らず
未計測 と書き、手読みによる観察を分ける
- 閾値は言語、チーム規約、対象の性質で変わるため、絶対基準として扱わない
- 高い complexity や低い coverage だけで
Critical にしない。変更容易性、テスト容易性、誤用可能性への影響と合わせて判断する
- 生成コード、parser、状態機械、互換性保持の adapter など、数値が高くなりやすい領域は例外理由を確認する
評価レベル
Critical
品質問題が、近い将来の安全な変更や検証を大きく阻害する。
例:
- 責務が混ざり、仕様追加や修正で高確率に変更漏れが起きる
- テスト不能な構造になり、重要挙動を回帰検知できない
- 抽象化や契約が曖昧で、複数の誤用が自然に起きる
Major
直ちに壊れるとは限らないが、保守コストやレビューコストを明確に増やす。
例:
- 条件分岐や状態管理が増え、変更時の影響範囲が読みにくい
- テストはあるが保証している振る舞いが不明確
- 依存方向や責務境界が局所的に崩れている
Minor
小さな整理で品質を上げられるが、今すぐ大きな手戻りにはつながりにくい。
例:
- 命名、コメント、テスト名、配置の軽微な分かりづらさ
- 後続でまとめれば十分な重複や表現ゆれ
スコアカード
品質を数値化する場合は、絶対評価ではなく「今回の差分をレビューするための目安」として扱う。
推奨スコア:
A: 品質上の懸念がほぼなく、変更・テスト・調査がしやすいB: 小さな改善余地はあるが、保守性を大きく損なっていないC: 品質上の懸念があり、近い変更で手戻りや調査コストが増えそうD: 重要な品質問題があり、先に構造改善やテスト補強を検討すべき
点数だけを出さない。必ず根拠、影響、改善優先度を添える。
指摘として成立する条件
指摘は次を満たす場合だけ出す。
- 今回の差分または指定範囲に根拠がある
- 品質低下がどの将来作業に影響するか説明できる
- 何が読みづらい、変えづらい、テストしづらい、調査しづらいのか具体化できる
- 改善方向を示せる
避ける指摘:
- 好みや一般論だけのコメント
- 現在の差分と関係しない既存コード全体への不満
- 影響を説明できない抽象的な「設計が悪い」
- パッチ実装を前提にした詳細すぎる書き換え案
出力形式
出力は次の順で行う。
- Quality Summary
- 総合評価:
A / B / C / D
- 主な品質リスクを 1-3 行で要約
- Quality Signals
Signal / Result / Interpretation / Action- metric が未計測なら
未計測 と明示し、必要な追加検証を書く
- Scorecard
- 観点ごとに
A / B / C / D と短い根拠を書く
- 必要な観点だけでよい
- Findings
- 重要度
Critical / Major / Minor
- ファイル / 行
- 品質問題の要約
- 根拠
- 関連する metric または観察
- 将来どの作業で困るか
- 改善方向
- Quality Gate
- merge 前に対応すべきもの
- follow-up issue でよいもの
- 対応不要と判断できるもの
- 通常レビューへ回すべきリスク
- 見つけた場合のみ、
code-review 観点として分けて書く
指摘がない場合:
品質レポート観点での重大な指摘はなし と明示する- 見た範囲、残る不確実性、スコアの根拠を書く
注意
- 欠陥レビューと品質レビューを混ぜすぎない
- 点数で実装者を裁くのではなく、次の判断に使える根拠を出す
- metric で実装者を裁かない。metric はレビュー判断を補強する証拠として使う
- 小さな差分では過剰なアーキテクチャ論にしない
- 大きな差分では、品質問題を「今直すべきもの」と「後続で扱うもの」に分ける
