code-quality-scoring

コード品質スコアリング

アプリケーションおよびポートフォリオのレベルで、ソフトウェア品質を定量化して伝えるための、ベンダーに依存しないフレームワークです。多くの品質スキルは、個々の指摘事項を修正する方法を説明します。このスキルでは、コードベース全体をスコア化し、負債のコストを推定して、コードを読まない人にもその両方を説明します。

出典に関する注記： 以下のスコアリングフレームワークは、CAST Highlightのコード品質指標と方法論（https://doc.casthighlight.com/）に基づいています。ベンダーに依存しないモデルとして言い換え、再構成しています。しきい値の範囲と負債密度の数値は、CASTのAppMarqベンチマークデータセットに基づく独自の調整値です。これらは普遍的な基準ではなく、**出典を明記した参考範囲**として提示しています。CASTがオープンスタンダード（工数についてはCOCOMO II、ライセンスについてはSPDX/choosealicense、セキュリティについてはCWE/CVE）を参照している場合は、それらの一次情報源を引用してください。

このスキルを使う場面

**「このコードベースの健全性はどの程度で、最初に何をすべきか？」**という質問に答えるときに使います。たとえば、次のような場面です。

• 不慣れなコードベースについて、初期の健全性基準を把握する。
• アプリケーションをリファクタリングするか、書き直すか、廃止するかを判断する。
• 多数のアプリケーション（ポートフォリオ）にわたる修正の優先順位を付ける。
• 品質上の欠陥のバックログがどれだけの工数・コストに相当するかを推定する。
• 品質や負債の状況を、マネージャー、プロダクトオーナー、または経営幹部に伝える。

単一の欠陥を修正するためには使わないでください。その場合は、言語別の品質スキル（Python／Java／PHP／TSの品質アンチパターン）とcode-review-standardsを使ってください。

基本概念 1 — ソフトウェアの健全性は複合的なものです

コード全体の健全性は、それぞれ0～100点で評価される、独立した3つの側面の単純平均として扱います。この分解（CAST Highlightに基づく）が役立つのは、各側面が異なる修正の種類と、異なる関係者の関心事に対応するためです。

側面	別名	測定対象	対応するチェックリストの分類
回復力／堅牢性	ソフトウェアの回復力	本番環境で障害が起きる可能性はあるか？エラー処理、防御的なコーディング、信頼性	堅牢性、セキュリティ
俊敏性／変更容易性	ソフトウェアの俊敏性	チームはコードをすばやく理解し、変更できるか？ドキュメント、可読性、命名	変更容易性、引き継ぎ容易性
簡潔さ／効率性	ソフトウェアの簡潔さ	無駄がないか？複雑さ、デッドコード、アルゴリズムやデータアクセスの効率性	効率性

Software Health = avg(Resiliency, Agility, Elegance)

しきい値の範囲（CASTの調整値に基づくものです。絶対視せず、目安として使ってください。）

区分	健全性	俊敏性（側面ごとにしきい値が異なることに注意してください）
🔴 低／赤	約53未満	約54未満
🟠 中／オレンジ	約53～75	約54～69
🟢 高／緑	約75超	約69超

重要なのは正確な数値ではありません。各側面にはそれぞれ異なる分布と修正戦略があるため、単一の総合評価では実態が見えなくなるという点です。コードベースの回復力は緑（クラッシュはまれ）でも、俊敏性は赤（誰も安全に変更できない）ということがあります。詳しくは**software-health-framework.md**を参照してください。

基本概念 2 — 技術的負債は修正に必要な工数の推定値です

負債は、違反の密度に、言語ごとに異なるコード行あたりの負債係数を適用して算出した、修正に必要な推定工数として表します。高水準で冗長な言語（Java、JavaScript、PHP）は、簡潔なスクリプト言語（Python、shell）よりも、コード行あたりの負債が大きくなる傾向があります。数値をそのまま正確にコピーするのではなく、必ず出典を明記した範囲（「業界ベンチマークでは、Javaの負債密度の中央値は、行あたりでPythonのおよそ3～4倍です」など）として提示してください。また、明示した前提条件に基づく場合に限り、金額や時間に換算してください。CASTの保守工数モデルは、COCOMO IIを基盤としています。詳しくは**technical-debt-estimation.md**を参照してください。

コアコンセプト 3 — クラウド対応度はスキャン＋アンケートで評価します

クラウド成熟度は、コードスキャンスコア（ソースコードで検出された阻害要因と促進要因 — たとえば、ハードコードされたファイルパスやホスト名は阻害要因、ステートレス性や外部化された設定は促進要因）と、アンケートスコア（コードからは明らかにならないチーム／運用上の要因）の平均です。cloud-maturity.md を参照してください。

コアコンセプト 4 — オープンソースの安全性は3要素の指標です

サードパーティのリスクは、セキュリティ（重大度で重み付けしたCVE件数）、ライセンスコンプライアンス（低・中・高リスクのライセンスの割合）、陳腐化（最新バージョンとの差）の平均です。これはPhase 1のOSS安全性の作業と相互参照しているため、重複させないでください。open-source-safety.md を参照してください。是正の仕組みについては、ライセンスリスクの段階とCVEの重み付けの考え方をすでに含む universal/security/security-scanning と toolchains/universal/dependency/dependency-audit を使用してください。

コアコンセプト 5 — ビジネスへの影響に基づいて優先順位を付けます

誰も依存していない欠陥の多いアプリケーションよりも、収益に直結する重要なアプリケーションで、中程度の欠陥があるもののほうが優先度は高くなります。技術的リスクスコアとビジネスへの影響スコア（障害の結果、対象ユーザーの規模、リリース／保守にかかる労力）を組み合わせ、未加工の欠陥件数ではなく、ビジネスに対するリスクに基づいて是正の優先順位を決めます。CASTでは、これをビジネスへの影響でリスクを重み付けしたROAR形式の指標として定式化しています。quality-communication-guide.md を参照してください。

適用方法（簡単なワークフロー）

1. 既存のリンター／スキャナーを使って3つの健全性の側面を評価します — 各ツールの検出結果をResiliency／Agility／Eleganceに割り当て、平均して健全性スコアを算出し、赤／オレンジ／緑の区分に当てはめます。
2. 負債を見積もります — 違反密度に言語ごとの負債係数を掛けます（出典を明記した範囲として）。前提を明示したうえで、作業量（時間／FTE）として表します。
3. 判断に関係する場合は、OSSの安全性とクラウド対応度を評価します。
4. ビジネスへの影響で重み付けし、アプリケーション／モジュールの優先順位を決めます。
5. ステークホルダー向けの説明の仕方で伝えます — ルール名ではなく、リスクと費用を最初に示します。

アンチパターン

• 単一の総合評価を報告し、実際に赤信号の側面を隠してしまう。
• LOC、時間単価、密度の前提を示さずに負債を正確な金額で表す — 範囲と前提を提示します。
• CASTのしきい値を普遍的な基準として扱う — これらは特定ベンダーによる基準値です。参考情報として引用してください。
• ビジネスへの影響で重み付けしたリスクではなく、欠陥件数で是正の優先順位を決める。
• OSSライセンスの段階をここで重複して説明する — Phase 1の参照資料を相互参照してください。

ナビゲーション

• Software Health Framework — Resiliency／Agility／Eleganceへの分解、区分、リンターの出力を対応付ける方法。
• Technical Debt Estimation — 修正工数モデル、言語ごとの負債密度の範囲（出典明記）、COCOMO IIとの関連、計算例。
• Cloud Maturity — スキャンとアンケートの違い、コード上の阻害要因と促進要因、クラウド対応度スコアの読み方。
• Open Source Safety — セキュリティ／ライセンス／陳腐化の指標、dependency-auditおよびsecurity-scanningスキルへの相互参照。
• Quality Communication Guide — ビジネスへの影響に基づく説明、ROAR形式の優先順位付け、技術者以外のステークホルダーへのスコアの提示方法。

関連スキル

• code-review-standards — 効率性と移転可能性の側面を含む検出事項ごとのチェックリスト（Phase 1）。このスキルはそれらの項目群をスコアに集約します。
• security-scanning / dependency-audit — OSS安全性の是正の仕組み。
• software-patterns — Elegance／Agilityのスコアが低い場合に示される、アーキテクチャ上の兆候。