majiayu000 ELD Debug - 法則駆動デバッグ手法
バグ = 法則（Law）からの逸脱として捉え、証拠ループで系統的に解決する手法。
核心思想
| 観点 | 従来のデバッグ | ELD的デバッグ |
|---|---|---|
| 視点 | 「なぜ壊れた？」 | 「どの法則が破られた？」 |
| 証拠 | ログ・スタックトレース | 法則違反の論理的証明 |
| 修正 | 症状の除去 | 法則の復元 |
| 検証 | 「動いた」 | 「法則が満たされた」（L0-L4） |
| 蓄積 | バグ票 | Law/Term Card + パターン |
デバッグループ
Sense → Model → Predict → Change → Ground → Record
↑ ↓
└──────────── 法則復元まで循環 ←──────────────┘
フェーズ詳細
Phase 1: Sense（症状の観測）
目的: 症状を観測し、関連する法則候補を列挙する
観測手段
| 種類 | 手段 | 目的 |
|---|---|---|
| ログ・トレース | 構造化ログ、分散トレース | イベント・状態変化の収集 |
| メトリクス | APM、プロファイリング | 性能・リソース状態 |
| デバッガ | ステップ実行、ブレークポイント | 実行時状態の詳細観測 |
| ユーザー報告 | エラーレポート、再現手順 | 外部視点の症状 |
| 履歴・差分 | git bisect、デプロイ履歴 | 変更との相関 |
成果物
症状記録:
現象: <何が起きているか>
再現条件: <いつ、どのような状況で発生するか>
影響範囲: <どのユーザー/機能に影響するか>
観測した変数:
- 変数名: <値と期待値>
法則候補:
- Law名: <この症状に関連しそうな法則>
カテゴリ: [Invariant | Pre | Post | Policy]
詳細は references/evidence-collection.md 参照。
Phase 2: Model（法則違反の仮説形成）
目的: 破られた法則を特定し、論理式として表現する
仮説形成プロセス
- 法則の明示化: 暗黙の法則を言語化
- 論理式化: 自然言語を論理式に変換
- 違反箇所の特定: どこで法則が破られているか
成果物
破られた法則:
Law名: <名前>
カテゴリ: [Invariant | Pre | Post | Policy]
論理式: <∀x. P(x) → Q(x) 形式>
自然言語: <平易な説明>
仮説:
原因推測: <なぜ法則が破られたか>
根拠: <仮説を支持する観測事実>
反証可能性: <この仮説が間違っていたら何が観測されるか>
Phase 3: Predict（影響予測）
目的: 法則違反の影響範囲と、修正による副作用を予測する
予測内容
- 伝播範囲: 法則違反がどこまで影響しているか
- 副作用: 修正による意図しない変更
- 失敗モード: 修正がうまくいかなかった場合の兆候
成果物
影響予測:
直接影響: <法則違反の直接的影響>
間接影響: <伝播による二次的影響>
修正予測:
期待効果: <修正で何が改善されるか>
副作用リスク: <意図しない変更のリスク>
停止条件:
- <このサインが出たら修正アプローチを見直す>
Phase 4: Change（法則復元）
目的: 最小限の変更で法則を復元する
変更原則
- 最小変更: 法則復元に必要な最小の変更
- Pure優先: 副作用のない変更を優先
- 可逆性確保: ロールバック可能な状態を維持
成果物
変更内容:
ファイル: <変更対象>
差分: <変更内容>
意図: <なぜこの変更で法則が復元されるか>
検証ポイント:
- <変更後に確認すべきこと>
Phase 5: Ground（証拠による検証）
目的: 法則が復元されたことを証拠で確認する
証拠の梯子（Evidence Ladder）
| Level | 手段 | 検証内容 |
|---|---|---|
| L0 | 型チェック・静的解析 | 法則が「書ける」か |
| L1 | ユニットテスト・Property-based test | 法則が単体で成立するか |
| L2 | 統合テスト・E2Eテスト | 法則が連携で成立するか |
| L3 | 失敗注入・Fuzz testing | 法則が異常時も守られるか |
| L4 | 本番Telemetry・監視 | 法則が実運用で成立しているか |
成果物
達成レベル: L[0-4]
証拠一覧:
- 証拠種別: <テスト/ログ/メトリクス>
内容: <何を検証したか>
結果: <Pass/Fail>
法則復元確認:
論理式: <検証した法則>
検証方法: <どう検証したか>
結果: [復元された | 部分的 | 未達成]
詳細は references/evidence-collection.md 参照。
Phase 6: Record（知識の蓄積）
目的: バグパターンと解決策を将来のために記録する
記録内容
- バグパターン: 法則違反のパターンとして抽象化
- 根本原因: なぜ法則が破られたかの分析
- 検出方法: このパターンを早期発見する方法
- 防止策: 再発を防ぐための施策
成果物
バグパターン:
パターン名: <識別しやすい名前>
法則違反タイプ: [Invariant | Pre | Post | Policy]
症状: <典型的な現れ方>
根本原因:
原因カテゴリ: [設計/実装/環境/運用]
詳細: <なぜ発生したか>
検出・防止:
早期検出方法: <テスト/監視/レビュー>
防止策: <設計/プロセス/ツール>
関連Law/Term:
- Law: <更新/新規作成したLaw>
- Term: <関連するTerm>
証拠収集方法の体系
詳細は references/evidence-collection.md 参照。
分類軸
| 軸 | 区分 |
|---|---|
| タイミング | 静的（実行前）/ 動的（実行中）/ 事後（実行後） |
| レイヤー | コード / ランタイム / インフラ / ユーザー |
| 目的 | 観測（発見）/ 検証（確認） |
証拠の梯子との対応
| Level | 主な収集方法 |
|---|---|
| L0 | 型チェック、Lint、静的解析、形式検証 |
| L1 | ユニットテスト、Property-based test、アサーション |
| L2 | 統合テスト、E2Eテスト、契約テスト |
| L3 | Chaos testing、Fuzz testing、サニタイザ |
| L4 | APM、分散トレース、メトリクス、エラーレポート |
完了条件
- 破られた法則が特定されている
- 法則が復元されたことが証拠で確認されている（L1以上）
- バグパターンが記録されている
- 必要に応じてLaw/Term Cardが更新されている
使用例
例1: 在庫計算の不整合
# Sense
症状: 在庫数が負の値になることがある
観測: stock = -5, available = 10, reserved = 15
法則候補: 保存則（stock = available + reserved）
# Model
破られた法則:
Law名: 在庫保存則
論理式: ∀t. stock(t) = available(t) + reserved(t)
仮説: 並行処理で予約済みが二重加算
# Predict
影響: 決済処理、在庫表示、レポート
副作用リスク: ロック導入による性能劣化
# Change
変更: トランザクション境界の修正
意図: 予約操作を原子的に実行
# Ground
L1: Property-based testで保存則を検証
L2: 並行予約の統合テスト
L3: タイムアウト時の保存則維持テスト
# Record
パターン: 並行処理での二重計上
防止策: STM使用 or 明示的ロック
例2: API認証エラー
# Sense
症状: 特定ユーザーだけ認証が通らない
観測: token有効期限内、権限正常
法則候補: 認証トークン検証法則
# Model
破られた法則:
Law名: トークン有効性法則
論理式: valid(token) ∧ ¬expired(token) → authenticated
仮説: タイムゾーン差異で有効期限判定が不正
# Ground
L1: タイムゾーン跨ぎのユニットテスト
L2: 実際のトークンでの統合テスト
# Record
パターン: タイムゾーン依存のバグ
検出方法: 異なるTZでのテスト追加
リファレンス
references/evidence-collection.md- 証拠収集方法の体系references/debug-phases.md- 各フェーズの詳細手順
関連スキル
/eld-sense-activation- Senseフェーズの詳細/eld-model-law-discovery- 法則発見/eld-ground-check- 接地検証/eld-record-collection- 知識蓄積