MISTAKES.md と Claude Code：繰り返す失敗をルールへ変える
簡潔な MISTAKES.md、ゼロシークレット、テストまたはルールへの昇格、Claude Code ガードレールの検証を解説します。
目次
MISTAKES.md と Claude Code：繰り返す失敗をルールへ変える
複雑なリポジトリで Claude Code を使うと、古い TypeScript 定義、隠れた実行時依存関係、bundler 固有の挙動など、分かりにくい環境の癖に必ず遭遇します。同じ失敗をチャットで何度も直すと文脈と時間を浪費します。逆に複数ページのセッション記録を指示へ入れると、prompt が雑然としモデルの注意力が落ちます。
実用的なのは、リポジトリ root に軽量な MISTAKES.md を置くことです。ここには再現可能なインシデント、確認済みの原因、予防策だけを記録します。後でそれらをプロジェクトのテスト、Linter ルール、永続設定に昇格させます。
1. MISTAKES.md とセッション記録
インシデントログを生の terminal transcript と混同しないでください。
| 観点 | セッション記録 | MISTAKES.md のインシデントログ |
|---|---|---|
| 量 | tool call と中間手順が数千行 | インシデント当たり構造化した 5–10 行 |
| 目的 | 一回限りのデバッグと監査 | 将来の再発を防ぐ参照ベース |
| シークレット | 生の環境変数や token を含む可能性 | 厳格に禁止：credential や secret はゼロ |
| 寿命 | 一時的な成果物 | 自動化されるまで残る文書 |
MISTAKES.md は、Claude Code がセッション開始時に過剰な context token を使わず読めるよう、簡潔に保つ必要があります。
2. インシデント記録の構成
各エントリには四つの必須フィールドがあります。
- Incident：何が、どの条件で壊れたか。error code、command、tool を含めます。
- Impact：壊れた build、破損した migration、停止した test suite など下流への影響。
- Root Cause：確認済みの技術的原因。未証明なら必ず
[Hypothesis]と明記します。 - Prevention：再発を防ぐ具体的な rule または check。
インシデント記録の例
### ERR-014: CASCADE なしの DROP COLUMN で PostgreSQL migration が失敗
- **Incident**: Claude Code が migration 0042 で `ALTER TABLE orders DROP COLUMN customer_ref;` を実行した。
- **Impact**: 依存 view `v_active_orders` のため staging deployment が失敗した。
- **Root Cause**: base table を参照する view には、明示的な cascade 再作成または事前の view 更新が必要である。
- **Prevention**: column を削除するすべての DDL migration は、実行前に `pg_depend` で依存 view を確認する。[!IMPORTANT] ゼロシークレット方針： 実際の database connection string、private key、token、
.envの断片をMISTAKES.mdに commit してはいけません。Claude Code API Key はローカル環境変数で管理します。
API provider と Claude Code を安全に構成するには、自分の API Key を使い、BetterToken の Claude Code 統合ガイドに従ってください。
3. 昇格のしきい値：ログからテストまたはルールへ
一度だけの typo すべてに永続ルールは不要です。明確なしきい値でエントリを自動 gate に昇格させます。
インシデント発生
│
├─> 初回：MISTAKES.md に 4 フィールドの記録
│
└─> 二回目（再発）：
│
├─> 機械的に検証できるか？
│ └─> はい：unit test、ESLint rule、pre-commit hook を追加
│
└─> いいえ：CLAUDE.md / AGENTS.md に厳格な否定指示を追加- 初回：
MISTAKES.mdに簡潔な記録を追加します。 - 二回目： 決定的に検出できる問題なら test または linter rule を書きます。自動 gate はテキスト prompt より強力です。
- 非機械的な確認：
CLAUDE.mdに明示的な否定ルールを作ります。例：「CI で —runInBand なしに jest を実行しない」。 - アーカイブ： test または hook を導入したら、ファイル肥大化を防ぐため
MISTAKES.mdのエントリを archive または削除します。
4. 次のタスクで検証する
新しい guardrail を確認する手順です。
- 新しい Claude Code session を開始する。
- 以前に失敗を引き起こした prompt を渡す。
- agent が新しい rule を守るか、pre-commit hook に止められるかを確認する。
- agent がテキスト指示を回避するなら、制約を厳格な command wrapper または自動 check に変換する。
この feedback loop はランダムな開発の失敗を、堅牢で自己改善する engineering foundation に変えます。
