Implementation Local Optima Audit

Implementation Local Optima Audit

目的

対象実装が、その局所では合理的である一方、より広いシステム境界・組織境界・時間軸では、複雑性、変更コスト、運用負荷、障害リスク、機会損失を増加させていないかを調査する。

このスキルは、コードスメルを列挙するためのものではない。次を証拠化するために使う。

現在の実装は、狭い評価条件では優位だが、評価条件を広げると代替案との優劣が反転する。

既定では診断と順位付けまでを行う。ユーザーが求めていない限り、直ちにリファクタリング案へ飛ばない。

局所最適の操作的定義

実装 I を、次の四変数で評価する。

• B: 評価境界 — 関数、モジュール、機能、システム、組織、ライフサイクル
• M: 評価指標 — 実装量、応答時間、保守性、障害率、顧客価値など
• N: 変更可能範囲 — 一箇所だけか、複数コンポーネントを同時変更できるか
• T: 時間軸 — 今回の変更か、半年後・数年後の進化まで含むか

局所最適候補とは、概念的には次を満たす実装である。

現在の B, M, N, T では合理的
かつ
B, M, N, T のいずれかを広げると、実行可能な代替案が優位になる

「複雑である」「重複している」「古い」という理由だけでは、局所最適と判定しない。

使用する場面

次の依頼で使用する。

• 局所最適になっている実装を探したい
• リファクタリング候補を構造的に抽出したい
• 各チームやサービスは改善しているのに、エンドツーエンドの成果が改善しない
• 変更要求一つに対して、多数のファイル・サービス・テストが変わる
• アダプター、互換層、例外分岐、再試行、手動補正が増えている
• 障害がモジュール内部ではなく境界周辺に集中する
• 静的には独立したファイルがGit履歴上では頻繁に共変更される
• 暫定対応、二重書き込み、旧仕様互換が長期間残っている
• 局所KPIと顧客・事業・システム全体KPIが乖離している

単純なスタイル違反、明白なバグ、一つの関数だけで閉じた性能問題には、通常のコードレビューやデバッグを優先する。

必要な入力と証拠

利用可能な証拠を確認し、ない証拠を推測で補わない。

最小入力

• 対象リポジトリまたはコード範囲
• 調査対象の機能、変更、障害、性能問題のいずれか

追加すると精度が上がる入力

• Git履歴、PR、レビュー履歴
• トレース、メトリクス、プロファイル、ログ
• Issue、障害報告、ポストモーテム
• 仕様、ADR、データモデル、API契約
• チーム所有権、リリース境界、運用手順
• 顧客フローまたは事業KPI

コードしかない場合は、実行時コスト、組織コスト、変更履歴に関する主張を未検証仮説として扱う。

非交渉ルール

1. 先に局所的合理性を説明する。 対象実装を悪いものとして開始しない。
2. 観測・推論・仮説を分離する。 ファイル、行、コミット、トレース、Issueなどへ参照を付ける。
3. 単一シグナルで断定しない。 原則として異なる観測面から二つ以上の独立した証拠を求める。
4. コストの負担者を特定する。 「複雑である」ではなく、誰が、どこで、いつ負担するかを示す。
5. 反実仮想を藁人形にしない。 現実的な代替案と、その移行コスト・一時的悪化を含めて比較する。
6. グローバル最適を主張しない。 「調査した境界と証拠の範囲で優位」と表現する。
7. 候補数を絞る。 広域調査では原則3〜7件を深掘りし、残りは候補一覧に留める。
8. 改善案より診断を優先する。 原因構造が不明なまま、共通化、統合、キャッシュ削除、サービス統合などを提案しない。

調査フロー

Phase 0: 調査モードを決める

明示がなければ discovery を選ぶ。

• discovery: 広く候補を抽出し、証拠強度と影響で順位付けする
• deep-dive: 一つの候補について、補償構造と優位性反転を詳細分析する
• intervention: 診断済み候補について代替案、移行経路、検証計画まで作る

Phase 1: 評価条件を固定する

最初に次を記録する。

局所目的が説明できない場合、「局所最適」よりも、惰性、偶然、所有者不在、失効した制約を疑う。

Phase 2: 四つの観測面を走査する

2.1 構造面

調べる対象:

• 同じ業務判断・条件式の分散
• データ表現と変換の連鎖
• アダプター、Facade、互換層、DTOの増殖
• 高いfan-out、循環依存、境界を越える内部型
• 呼び出し側へ押し出された検証、null処理、型判定
• 共有状態、二重書き込み、キャッシュと原本の二重管理
• 一見独立したモジュール間の暗黙契約

構造面だけで、実行時・組織・将来変更の影響を断定しない。

2.2 実行面

調べる対象:

• エンドツーエンドのp50/p95/p99と局所レイテンシの乖離
• 再試行、タイムアウト、フォールバック、サーキットブレーカーの発火
• 重複I/O、N+1、余分なシリアライズ、同期点
• キュー滞留、ロック競合、負荷増幅、障害伝播
• キャッシュヒット率と無効化・不整合コスト
• 局所成功率は高いが、ユーザーフロー完了率が低い箇所

2.3 進化面

調べる対象:

• Git共変更、ホットファイル、変更増幅
• 一つの意味変更に対する変更ファイル・サービス・テスト数
• 修正後の再修正、リバート、同種障害の再発
• PRの滞留、レビュー参加者数、チーム間待ち時間
• 暫定分岐、互換コード、移行タスクの残存期間
• 静的依存は弱いが、履歴上は常に一緒に変わる箇所

付属スクリプトを使える場合:

python scripts/git_local_optima_signals.py /path/to/repo --since "12 months ago" --format markdown

出力は候補抽出用であり、局所最適の判定そのものではない。

2.4 意味・組織面

調べる対象:

• 同じ概念が複数の名前・型・所有者で管理される
• 異なる概念が一つの汎用型・ステータス・フラグに押し込まれる
• 局所KPIとエンドツーエンドKPIが競合する
• 利益を得るチームとコストを負担するチームが異なる
• コード外の手作業、Runbook、問い合わせ対応、データ修正
• 誰もエンドツーエンドの整合性を所有していない境界

Phase 3: 候補ゲートを通す

次を満たすものを深掘り候補にする。

• 局所的な利益または合理性が説明できる
• 境界外へ押し出されたコストの負担者を特定できる
• 異なる観測面から二つ以上の証拠がある、または強い実測上の優位性反転が一つある
• 評価境界、指標、変更範囲、時間軸のいずれかを広げる余地がある
• 現状維持以外に、実行可能性を検討できる代替構造が少なくとも一つある

満たさないものは weak signal とし、断定しない。

Phase 4: 局所的合理性カードを作る

候補ごとに次を埋める。

• 対象と所有者
• 導入時期と当時の制約
• 最適化対象となった局所指標
• 直接の受益者
• 現在も有効な利益
• 失効した制約
• 局所変更だけでは改善しにくい理由

導入時に合理的だったか、現在も合理的かを分ける。

Phase 5: 補償ハローを追跡する

対象実装を維持するために、境界外で発生している補償を列挙する。

• 変換: mapper、adapter、serializer、DTO変換
• 条件: legacy、compat、special case、feature flag、例外分岐
• 信頼性: retry、timeout、fallback、reconciliation
• データ: 二重書き込み、修復ジョブ、再計算、キャッシュ無効化
• テスト: 大量モック、専用fixture、テスト専用分岐
• 運用: 手修正、再投入、監視、問い合わせ、承認作業
• 組織: チーム間依頼、複数リリース調整、所有権の空白

補償ごとに次を記録する。

原因となる局所判断 -> 境界外で生じる不整合 -> 補償手段 -> 負担者 -> 頻度/規模

相関しか確認できない場合は、因果として書かない。

Phase 6: 評価境界を段階的に広げる

次の順で同じ実装を再評価する。

1. 関数
2. モジュール
3. 機能・ユーザーフロー
4. システム
5. 運用・組織
6. ライフサイクル・将来変更

各境界で、現在案と代替案の利益・コストを比較する。

優位性が反転する境界を特定する。反転しない場合、局所最適という仮説を棄却または保留する。

Phase 7: 指標と時間軸を反転テストする

少なくとも次を確認する。

• 平均値だけでなくp95/p99、失敗率、再試行込みの値で比較したらどうなるか
• 実装コストだけでなく、統合・運用・変更・移行・リスクを含めたらどうなるか
• 今回の変更だけでなく、同種変更が3回、10回発生したらどうなるか
• 現行チーム境界を固定しない場合、優劣は変わるか
• 一箇所ずつしか変えられない制約を外し、複数箇所を同時変更したらどうなるか
• 一時的な二重化や移行期間を許せば、別の安定状態へ移れるか

Phase 8: 反実仮想を作る

最低でも次を比較する。

• A: 現状維持
• B: 最小限の局所改善
• C: 境界をまたぐ構造変更

必要なら二つ以上の構造変更案を置く。各案について次を含める。

• 成立条件
• 変更対象と所有者
• 定常状態の利益とコスト
• 移行中の二重化、互換性、データ移行
• ロールバック可能性
• 一時的に悪化する指標
• 新たに発生する局所最適や結合

「理想的な全面刷新」と「現状」を比較してはならない。

Phase 9: 全体コストを評価する

定量値がある場合は使い、ない場合は序数評価に留める。

C_total =
  implementation
+ integration
+ coordination
+ runtime
+ operation
+ change
+ migration
+ risk
+ opportunity_loss

局所利益が大きくても、外部化コストと将来後悔が上回るかを確認する。

0〜3の序数スコア

• E 外部化コスト: 0 なし / 1 小 / 2 複数利用者へ継続負担 / 3 システム横断・重大
• A 変更増幅: 0 閉じる / 1 数箇所 / 2 複数境界 / 3 複数チーム・反復的
• F 境界障害: 0 なし / 1 稀 / 2 再発 / 3 顧客・SLOへ重大影響
• K KPI乖離: 0 一致 / 1 軽微 / 2 明確 / 3 局所改善が全体悪化を誘発
• T 時間ロックイン: 0 低 / 1 移行容易 / 2 暫定構造が固定化 / 3 選択肢を大幅に喪失

Severity = E + A + F + K + T  # 0〜15

証拠確度は別軸で示す。

• C0: 推測のみ
• C1: 静的証拠のみ
• C2: 異なる観測面の証拠が一致
• C3: 実測、履歴、障害、利用者影響で反転を確認

重大度と確度を混ぜて一つの精密な数値にしない。

Phase 10: 判定する

次のいずれかに分類する。

• harmless-locality: 境界内に閉じた、許容可能な局所最適
• externalization: 利益とコストの負担者が分離している
• time-delayed: 現在の利益と将来の変更・移行コストが反転する
• organizational: チーム境界、所有権、KPIが実装へ局所最適を再生産する
• mixed: 上記が複合する
• not-local-optimum: 反転が確認できず、別の問題として説明できる
• insufficient-evidence: 候補ではあるが証拠不足

誤検出しやすい設計

次は局所最適に見えても、全体として合理的な可能性がある。

• 境界づけられたコンテキストごとの異なるモデル
• 意図的重複による不要な共有結合の回避
• 障害分離や可用性のためのデータ複製
• ホットパスに限定した特殊化
• チーム自律性のために許容した局所的非効率
• 期限と撤去条件が明確な移行用互換層
• 法規制、セキュリティ、監査要件による冗長処理

これらを問題と判定するには、目的に対して実際に不利益が上回る証拠が必要である。

出力

既定では、次の順で報告する。

1. 調査範囲と利用できた証拠
2. システム成果と現在の評価条件 B/M/N/T
3. 候補一覧と順位
4. 上位候補の詳細カード
5. 補償ハロー
6. 優位性反転表
7. 反実仮想と移行の谷
8. 判定、重大度、証拠確度
9. 未検証事項と次に取得すべき証拠

templates/audit-report.md と templates/candidate-card.md を使う。

候補一覧の推奨列:

調査品質のチェック

完了前に確認する。

• 対象実装の局所的利益を説明した
• 現在の B/M/N/T を明示した
• コストの負担者と発生地点を特定した
• 異なる観測面から証拠を集めた
• 観測・推論・仮説を分離した
• 境界を広げた比較表を作った
• 現状維持を含む現実的な反実仮想を比較した
• 移行コストと一時的悪化を含めた
• 誤検出候補を検討した
• 反転が確認できない候補を無理に局所最適と呼んでいない
• 重大度と証拠確度を別々に示した

参照資料

必要なときだけ読む。

• 詳細な証拠ヒューリスティクス: references/evidence-and-heuristics.md
• 調査報告テンプレート: templates/audit-report.md
• 候補詳細カード: templates/candidate-card.md
• 記入例: examples/typed-api-example.md
• Git履歴候補抽出: scripts/git_local_optima_signals.py