AI コーディング

MISTAKES.md と Claude Code：繰り返す失敗をルールへ変える

簡潔な MISTAKES.md、ゼロシークレット、テストまたはルールへの昇格、Claude Code ガードレールの検証を解説します。

BT

BetterToken

編集チーム
2 分で読めます

複雑なリポジトリで 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. インシデント記録の構成

各エントリには四つの必須フィールドがあります。

  1. Incident：何が、どの条件で壊れたか。error code、command、tool を含めます。
  2. Impact：壊れた build、破損した migration、停止した test suite など下流への影響。
  3. Root Cause：確認済みの技術的原因。未証明なら必ず [Hypothesis] と明記します。
  4. 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 統合ガイド](https://docs.bettertoken.ai/ai-tools/claude-code)に従ってください。

---

3. 昇格のしきい値：ログからテストまたはルールへ

一度だけの typo すべてに永続ルールは不要です。明確なしきい値でエントリを自動 gate に昇格させます。

インシデント発生
  │
  ├─> 初回：MISTAKES.md に 4 フィールドの記録
  │
  └─> 二回目（再発）：
        │
        ├─> 機械的に検証できるか？
        │     └─> はい：unit test、ESLint rule、pre-commit hook を追加
        │
        └─> いいえ：CLAUDE.md / AGENTS.md に厳格な否定指示を追加
  1. 初回： MISTAKES.md に簡潔な記録を追加します。
  2. 二回目： 決定的に検出できる問題なら test または linter rule を書きます。自動 gate はテキスト prompt より強力です。
  3. 非機械的な確認： CLAUDE.md に明示的な否定ルールを作ります。例：「CI で --runInBand なしに jest を実行しない」。
  4. アーカイブ： test または hook を導入したら、ファイル肥大化を防ぐため MISTAKES.md のエントリを archive または削除します。

4. 次のタスクで検証する

新しい guardrail を確認する手順です。

  1. 新しい Claude Code session を開始する。
  2. 以前に失敗を引き起こした prompt を渡す。
  3. agent が新しい rule を守るか、pre-commit hook に止められるかを確認する。
  4. agent がテキスト指示を回避するなら、制約を厳格な command wrapper または自動 check に変換する。

この feedback loop はランダムな開発の失敗を、堅牢で自己改善する engineering foundation に変えます。

LLM ワークフローを最適化しませんか？

単一 API でモデルを接続し、キーと AI コストを管理できます。