design-principles

設計原則の監査

コードベースを広く知られている設計原則に照らして監査します。優先順位を付けた改善アクションを含む、スコア付きの DESIGN_AUDIT.md を作成してください。

基本原則： パターンに当てはめず、調査してください。実際のコードを読み、違反が本物なのか、意図的なものなのか、誤検出なのかを判断してください。具体的なファイルと行番号の根拠がある指摘のみを挙げてください。

前提条件の確認

git --version 2>/dev/null && git rev-parse --is-inside-work-tree 2>/dev/null

Git リポジトリでない場合は警告を出して続行してください。Git の履歴は利用できませんが、ファイルの分析は引き続き可能です。

ステップ 1：コンテキストの検出

言語、フレームワーク、パラダイムを特定してください。これらによって、どの原則が適用されるか、また違反がどのように現れるかが決まります。

ls go.mod package.json pyproject.toml Cargo.toml *.csproj 2>/dev/null

README.md と CONTEXT.md（存在する場合）を読み、アーキテクチャ上の意図を確認してください。

入力から監査範囲を判断してください。

• 全体監査（デフォルト） — vendor/、node_modules/、生成ファイルを除くコードベース全体
• モジュール監査 — 特定のディレクトリまたはパッケージ
• 委任モード — tech-debt から呼び出された場合、変更されたファイルに注目し、スコアカード用の指摘を提示する

原則ごとの言語固有の違反パターンについては、references/principles-guide.md を参照してください。

ステップ 2：違反のスキャン

該当する原則ごとに、実際のコードを読み、違反を特定してください。キーワードを grep するのではなく、呼び出し経路と責任をたどってください。

SOLID

• S — 単一責任の原則：変更理由が複数あるファイル、クラス、関数を探します。兆候：300 行を超え、複数の関心事が混在するファイル、I/O とビジネスロジックとフォーマット処理を行う関数。
• O — 開放／閉鎖の原則：新しい振る舞いを追加する際、拡張ではなく変更が必要なコードを探します。兆候：型タグに基づく長い switch／if-else チェーン、拡張ポイントにインターフェースや抽象化がないこと。
• L — リスコフの置換原則：事前条件を弱める、事後条件を強める、または予期しないエラーを発生させるサブタイプを探します。兆候：何もしないオーバーライド、有効な入力での panic、使用前の型アサーション。
• I — インターフェース分離の原則：利用しないメソッドの実装を強いる、広範なインターフェースを探します。兆候：メソッドが 5 個を超えるインターフェース、スタブや何もしない実装。
• D — 依存関係逆転の原則：高水準モジュールが具体的な低水準型をインポートしている箇所を探します。兆候：依存関係の直接的なインスタンス化、パッケージ境界でのインターフェースの欠如、テスト不可能なコード。

DRY

単一の抽象化によって保守上のリスクを減らせる、2 か所以上に重複したロジック、構造、データを探します。本当の重複と偶然の類似を区別してください。似ている関数でも、それぞれ独立して進化するのであれば DRY 違反ではありません。

YAGNI

現在のユースケースがないのに追加された抽象化、設定オプション、汎用性を探します。兆候：未使用のパラメーター、デッドコードの経路、実装が 1 つしかないインターフェース、一度も読み取られない設定キー。

KISS

不必要に複雑な解決策を探します。兆候：価値を加えない間接化、コードベースに存在しない問題を解決する抽象化、単純な操作に対する多層の委譲。

デメテルの法則

内部構造を露呈する呼び出しチェーンを探します：a.GetB().GetC().Do()。各ユニットは、直接の協力相手とのみやり取りするべきです。

関心事の分離

異なるレイヤーが混在している箇所を探します：ドメインモデル内の HTTP ロジック、ハンドラー内の SQL、ビジネスルール内のプレゼンテーション処理。エントリーポイントからデータフローをたどってください。

継承よりコンポジション

深い継承階層（2 レベル超）、サブクラスに対応するために変更された基底クラス、または継承による密結合を探します。注：Go や関数型言語では、継承の誤用ではなく、インターフェースが使われていない箇所を指摘してください。

12-Factor（コードに関連する項目）

• 設定：環境変数から取得すべきハードコードされた値（URL、認証情報、機能フラグ、しきい値）。
• ログ：構造化ログライブラリの代わりに使われている fmt.Println、print()、または場当たり的な文字列連結。
• ステートレスプロセス：水平スケーリングを妨げるインメモリ状態（パッケージレベルの可変グローバル、ユーザー固有データのローカルファイルキャッシュ）。

ステップ 3：調査結果のスコアリング

各調査結果に、references/report-template.md のフレームワークを使って影響度、工数、優先度を割り当てます。

• 影響度：CRITICAL / HIGH / MEDIUM / LOW
• 工数：S（1 日未満） / M（1～5 日） / L（1～2 週間） / XL
• 優先度：P1（影響度が高く工数が少ない）から P4（影響度が低く、工数は問わない）まで

サマリーのスコアカード用に、各原則領域を 0～10 で採点します。

ステップ 4：敵対的ディベート

違反について実際に意見が分かれる（妥当なエンジニア同士でも意見が異なる可能性がある）調査結果から、影響度 × 工数の合計スコアが最も高い上位 3 件を特定します。明白な調査結果は除外します。

議論する調査結果ごとに、次の内容を示します。

• レッド（リファクタリング）：違反を修正すべきだと主張します。具体的な差分またはリファクタリングの方法を提案する必要があります。現行の設計が妥当かどうかを問い直します。
• ブルー（維持）：現状の設計が文脈に照らして正しいと主張します。「動作するから」以外の具体的な理由を示す必要があります。提案された変更のリスクを指摘します。
• ホワイト（判定）：根拠に基づいて評価し、リファクタリング、維持、または根拠をコメントに追加のいずれかを決定します。

ディベートのルール

• レッドとブルーは、一般論ではなく具体的なコードを根拠として示す必要があります
• レッドは問題点を指摘するだけでなく、具体的な変更を提案する必要があります
• ブルーは、理由を示さずに現状を擁護することはできません
• ホワイトの判定は最終決定であり、レポートに反映する必要があります

ステップ 5：DESIGN_AUDIT.md を生成

references/report-template.md のテンプレートを使ってレポートを作成します。 エグゼクティブサマリー、原則のスコアカード、根拠を示した詳細な調査結果、ディベートの判定、優先度順の改善ロードマップを含めます。

生成したファイルに対して markdownlint を実行します。

markdownlint DESIGN_AUDIT.md 2>/dev/null || \
  npx markdownlint-cli DESIGN_AUDIT.md 2>/dev/null

問題があれば、提示する前に修正します。

ステップ 6：サマリーを提示

ユーザーに次の内容を示します。

1. 原則のスコアカード（名前、0～10 のスコア、主な調査結果）
2. 設計全体の健全性スコア（原則スコアの合計 / 最大スコア）
3. 意見が分かれた調査結果に対するディベートの判定
4. 早急な対応が必要な P1 項目
5. 優先度の高い改善項目トップ 5（推定工数付き）
6. どの項目から対応するかユーザーに確認する