# Implementation Local Optima Audit > 実装・設計・運用に埋め込まれた局所最適を、評価境界・評価指標・変更可能範囲・時間軸を拡張して検出し、外部化された複雑性、変更増幅、境界障害、KPI乖離、移行ロックインを証拠付きで分析する。アーキテクチャレビュー、リファクタリング候補探索、性能調査、Git共変更分析、障害再発分析、レガシー互換層や手動運用の見直しに使用する。 - Skill: `caphtech/implementation-local-optima-audit` (Agent Skill, multi-file: 8 files) - Install (CLI): `npx skillmds@latest add caphtech/implementation-local-optima-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/caphtech/implementation-local-optima-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: CAPHTECH (https://skillmd.com/u/caphtech) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/caphtech/implementation-local-optima-audit --- # Implementation Local Optima Audit ## 目的 対象実装が、その局所では合理的である一方、より広いシステム境界・組織境界・時間軸では、複雑性、変更コスト、運用負荷、障害リスク、機会損失を増加させていないかを調査する。 このスキルは、コードスメルを列挙するためのものではない。次を証拠化するために使う。 > 現在の実装は、狭い評価条件では優位だが、評価条件を広げると代替案との優劣が反転する。 既定では**診断と順位付けまで**を行う。ユーザーが求めていない限り、直ちにリファクタリング案へ飛ばない。 --- ## 局所最適の操作的定義 実装 `I` を、次の四変数で評価する。 - `B`: 評価境界 — 関数、モジュール、機能、システム、組織、ライフサイクル - `M`: 評価指標 — 実装量、応答時間、保守性、障害率、顧客価値など - `N`: 変更可能範囲 — 一箇所だけか、複数コンポーネントを同時変更できるか - `T`: 時間軸 — 今回の変更か、半年後・数年後の進化まで含むか 局所最適候補とは、概念的には次を満たす実装である。 ```text 現在の 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: 評価条件を固定する 最初に次を記録する。 | 項目 | 記録内容 | |---|---| | 対象実装 | 関数、モジュール、サービス、データモデル、運用手順 | | システム成果 | 顧客・事業・運用上、最終的に良くしたい結果 | | 局所目的 | 対象実装が直接最適化しているもの | | `B` 評価境界 | 現在どこまでを内部と見なしているか | | `M` 評価指標 | 現在何を良さとして測っているか | | `N` 変更範囲 | 現実に同時変更できる範囲 | | `T` 時間軸 | リリース、四半期、製品寿命など | | 制約 | 互換性、組織、規制、性能、納期、所有権 | 局所目的が説明できない場合、「局所最適」よりも、惰性、偶然、所有者不在、失効した制約を疑う。 ### Phase 2: 四つの観測面を走査する #### 2.1 構造面 調べる対象: - 同じ業務判断・条件式の分散 - データ表現と変換の連鎖 - アダプター、Facade、互換層、DTOの増殖 - 高いfan-out、循環依存、境界を越える内部型 - 呼び出し側へ押し出された検証、null処理、型判定 - 共有状態、二重書き込み、キャッシュと原本の二重管理 - 一見独立したモジュール間の暗黙契約 構造面だけで、実行時・組織・将来変更の影響を断定しない。 #### 2.2 実行面 調べる対象: - エンドツーエンドのp50/p95/p99と局所レイテンシの乖離 - 再試行、タイムアウト、フォールバック、サーキットブレーカーの発火 - 重複I/O、N+1、余分なシリアライズ、同期点 - キュー滞留、ロック競合、負荷増幅、障害伝播 - キャッシュヒット率と無効化・不整合コスト - 局所成功率は高いが、ユーザーフロー完了率が低い箇所 #### 2.3 進化面 調べる対象: - Git共変更、ホットファイル、変更増幅 - 一つの意味変更に対する変更ファイル・サービス・テスト数 - 修正後の再修正、リバート、同種障害の再発 - PRの滞留、レビュー参加者数、チーム間待ち時間 - 暫定分岐、互換コード、移行タスクの残存期間 - 静的依存は弱いが、履歴上は常に一緒に変わる箇所 付属スクリプトを使える場合: ```bash 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、テスト専用分岐 - 運用: 手修正、再投入、監視、問い合わせ、承認作業 - 組織: チーム間依頼、複数リリース調整、所有権の空白 補償ごとに次を記録する。 ```text 原因となる局所判断 -> 境界外で生じる不整合 -> 補償手段 -> 負担者 -> 頻度/規模 ``` 相関しか確認できない場合は、因果として書かない。 ### Phase 6: 評価境界を段階的に広げる 次の順で同じ実装を再評価する。 1. 関数 2. モジュール 3. 機能・ユーザーフロー 4. システム 5. 運用・組織 6. ライフサイクル・将来変更 各境界で、現在案と代替案の利益・コストを比較する。 | 評価境界 | 現在案の利益 | 現在案のコスト | 代替案の利益 | 代替案のコスト | 優位性 | |---|---|---|---|---|---| | 関数 | | | | | | | モジュール | | | | | | | 機能 | | | | | | | システム | | | | | | | 運用・組織 | | | | | | | ライフサイクル | | | | | | 優位性が反転する境界を特定する。反転しない場合、局所最適という仮説を棄却または保留する。 ### Phase 7: 指標と時間軸を反転テストする 少なくとも次を確認する。 - 平均値だけでなくp95/p99、失敗率、再試行込みの値で比較したらどうなるか - 実装コストだけでなく、統合・運用・変更・移行・リスクを含めたらどうなるか - 今回の変更だけでなく、同種変更が3回、10回発生したらどうなるか - 現行チーム境界を固定しない場合、優劣は変わるか - 一箇所ずつしか変えられない制約を外し、複数箇所を同時変更したらどうなるか - 一時的な二重化や移行期間を許せば、別の安定状態へ移れるか ### Phase 8: 反実仮想を作る 最低でも次を比較する。 - `A`: 現状維持 - `B`: 最小限の局所改善 - `C`: 境界をまたぐ構造変更 必要なら二つ以上の構造変更案を置く。各案について次を含める。 - 成立条件 - 変更対象と所有者 - 定常状態の利益とコスト - 移行中の二重化、互換性、データ移行 - ロールバック可能性 - 一時的に悪化する指標 - 新たに発生する局所最適や結合 「理想的な全面刷新」と「現状」を比較してはならない。 ### Phase 9: 全体コストを評価する 定量値がある場合は使い、ない場合は序数評価に留める。 ```text 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 選択肢を大幅に喪失 ```text 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` を使う。 候補一覧の推奨列: | Rank | Candidate | Local benefit | Externalized cost | Inversion boundary | Severity | Confidence | Verdict | |---:|---|---|---|---|---:|---|---| --- ## 調査品質のチェック 完了前に確認する。 - [ ] 対象実装の局所的利益を説明した - [ ] 現在の `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