Observation Minimum Set（最小セット統合観測）

目的

観測は"バグを見つける手段"というより、失敗モードごとに、間違いが露出する場所を作る技術。このスキルは、6つの失敗モードを継続可能なコストで薄くカバーする。

観測の強さの評価基準

| 基準 | 説明 | |------|------| | 独立性 | 実装と同じ前提に依存しない観測 | | 露出性 | 失敗時に確実に"壊れる形"で信号が出る | | 再現性 | 問題が再現でき、修正効果が観測できる | | コスト | 毎回回る（継続可能）こと |

6つの失敗モード

| # | 失敗モード | 典型的な症状 | 関連スキル | |---|-----------|-------------|-----------| | 1 | 仕様誤解 | 型もテストも通るのに"違うもの" | spec-observation | | 2 | 境界条件漏れ | 例は通るが端で壊れる | boundary-observation | | 3 | 依存取り違え | ローカルでは動くのに本番で死ぬ | dependency-observation | | 4 | セキュリティ | 認可漏れ、機密漏えい | security-observation | | 5 | 並行性 | 通常テストが通るのに本番で死ぬ | concurrency-observation | | 6 | 運用不能 | 原因不明、ログがない、復旧できない | operability-observation |

最小セット（普遍：5つ）

継続可能な"最小セット"として、以下の5つを必須とする：

1. 実行可能仕様＋仮定ログ（仕様誤解対策）

[ ] 仕様の例（少数）＋否定例をテスト化
[ ] 仮定ログを成果物として残し、差分レビュー対象にする

2. クリーンビルド＋型/コンパイル＋ lint（基本品質）

[ ] lockfile固定＋CIで固定破り即fail
[ ] クリーン環境でのビルドがCIで回る
[ ] 型チェック/コンパイルが通る
[ ] lint（静的解析）がエラー0

3. 境界値テスト＋性質テスト（境界条件対策）

[ ] 外部境界ごとに最小・最大・空・異常のテスト
[ ] 重要箇所に性質テスト1本

4. 依存固定＋脆弱性スキャン＋ Secret scan（供給網対策）

[ ] lockfile固定
[ ] 依存脆弱性スキャン（npm audit / pip-audit等）
[ ] Secret scan（gitleaks等）

5. 運用観測性の最小（運用不能対策）

[ ] 起動時設定検証（fail fast）
[ ] ヘルスチェック（liveness/readiness）
[ ] 構造化ログ＋相関ID＋エラー分類
[ ] 最低限メトリクス（エラー率・レイテンシの2つでも）

最小セット（条件付き：+1）

6. 並行性観測（並行性がある領域のみ）

[ ] レース検出/サニタイザをCIで回す
[ ] ストレステスト1本
[ ] タイムアウト＋飽和メトリクス

カバレッジ行列

各最小セットがどの失敗モードに効くか：

| 失敗モード | 1.仕様 | 2.ビルド | 3.境界 | 4.供給網 | 5.運用 | 6.並行 | |-----------|--------|---------|--------|---------|--------|--------| | 仕様誤解 | ◎ | △ | ○ | △ | ○ | - | | 境界条件 | ○ | ○ | ◎ | △ | ○ | △ | | 依存取違 | △ | ○ | △ | ◎ | ○ | - | | セキュリティ | △ | ○ | ○ | ◎ | ○ | △ | | 並行性 | - | △ | △ | - | ○ | ◎ | | 運用不能 | ○ | △ | △ | ○ | ◎ | ○ |

凡例：◎強い ○中程度 △限定的 -効果なし

Procedure

Step 1: 現状診断

assets/observation-checklist.md を使って、現在の観測状況を診断する。

Step 2: ギャップの特定

最小セットと現状の差分を特定し、優先順位を付ける。

優先順位の基準：

仕様誤解（A1/A2）→ 最も早期に効果が出る
供給網（C1/D1/D2）→ セキュリティに直結
運用観測性（F1-F4）→ MTTRに直結
境界条件（B1/B2）→ 品質向上
並行性（E1-E3）→ 該当領域のみ

Step 3: 段階的導入計画

一度にすべてを導入せず、段階的に進める：

Week 1: A1/A2（仮定ログ + 受入テスト）
Week 2: C1/D1/D2（lockfile + secret scan + 脆弱性スキャン）
Week 3: F1-F3（設定検証 + ヘルス + 構造化ログ）
Week 4: B1/B2（境界値テスト + 性質テスト）
以降: 必要に応じて E1-E3（並行性）、F4（メトリクス）

Step 4: 継続的モニタリング

導入した観測が継続的に機能しているか定期的に確認する。

最小セットを強くするコツ

テストのオラクル（期待値）の独立性を守る
- 実装と同じ誤解で生成したテストは危険
- 受入テストの期待値は"仕様の例"から
失敗時のログが"次の修正の入力"になるようにする
- 例外にID・分類・境界情報がないと改善に繋がらない
重い観測は条件付きにするが、"条件"を観測で決める
- 並行性領域→race必須
- 外部入力あり→fuzz検討

Outputs

observation-checklist.md: 現状診断チェックリスト
observation-gap-report.md: ギャップレポート
observation-roadmap.md: 段階的導入計画

Examples

現状診断の例

## 観測現状診断 (2024-01-15)

### 1. 実行可能仕様 ＋ 仮定ログ
- [x] 受入テストあり（ただし否定例が不足）
- [ ] 仮定ログなし

### 2. ビルド ＋ 型 ＋ lint
- [x] lockfile固定
- [x] 型チェック
- [x] lint

### 3. 境界値 ＋ 性質テスト
- [ ] 境界値テスト（API入力のみ、DB境界なし）
- [ ] 性質テストなし

### 4. 供給網
- [x] lockfile固定
- [ ] 脆弱性スキャンなし
- [ ] secret scanなし

### 5. 運用観測性
- [x] ヘルスチェックあり
- [ ] 設定検証なし（起動後にクラッシュする可能性）
- [ ] 構造化ログなし
- [ ] メトリクスなし

### 優先対応
1. secret scan導入（即日）
2. 仮定ログの運用開始（今週）
3. 設定検証の実装（来週）