CLAUDE.md をインシデントレポートとして使う — Claude Code チームメンバーが明かすベストプラクティス

CLAUDE.md をインシデントレポートとして使う

Claude Code チームメンバーの Boris が Hacker News で公開した実践的なティップスが注目されている。一言でいうと「Claude が繰り返し間違えることは CLAUDE.md に書け」。

課題：Claude は同じ間違いを繰り返す

Claude Code を使い続けると、毎回同じパターンで詰まることがある。例えば：

• テストを書くときに毎回 describe ブロックの構造を間違える
• 特定のフォルダ構成の慣例を無視する
• プロジェクト固有の命名規則を守らない

これを毎回プロンプトで「XXXに注意して」と書くのは消耗する。

解決策：CLAUDE.md をリビングドキュメントとして更新し続ける

CLAUDE.md はセッション開始時に Claude が自動で読み込む設定ファイル。これをインシデントの記録簿として使う：

Claude が間違えた → すぐに CLAUDE.md に追記する

例：

## 注意事項（実際に間違えたパターン）

- テストは `describe` + `it` 構成を使う。`test()` は使わない
- `src/lib/` と `src/utils/` を混在させない。共有ユーティリティは必ず `src/lib/`
- APIレスポンスの型は `types/api.ts` で定義する。インライン型は書かない

ポイントは「汎用的なベストプラクティス」ではなく、「このプロジェクトでこの Claude が実際に間違えた具体的なケース」を書くこと。

「生産性パニック」への対処

HN のスレッドでは別の問題も指摘されていた。Agentic セッションがあまりに高速で多くのアクションを打つため、開発者が「意思決定疲れ（decision fatigue）」に陥るというもの。

実用的な対処として挙がっていたのは：

実行前に計画を強制する

まず PLAN.md に実装計画を箇条書きで書いて。コードは書かなくていい。

計画を先に出させることで、実装が始まる前に方針を確認できる。Claude Code が動き始めてから「あれ、違う方向に進んでる」と気づくのを防ぐ。

スコープを明示する

今回はユーザー認証の POST /login エンドポイントだけを実装して。
他のエンドポイントには触れない。

Claude は「ついで」に関連する場所を修正しがちで、それが意図しない変更を生む。スコープを明確に絞ることで、差分が予測可能になる。

チェックポイントを活用する

v2.1.166 から安定している Esc×2 または /rewind でのチェックポイントに戻る機能。「あと少しでできそうだけど迷走してきた」と感じたタイミングで躊躇なく巻き戻せるようにしておくと、長いセッションの安心感が違う。

まとめ

CLAUDE.md の「間違いログ」化は、プロジェクト固有のコンテキストを蓄積するシンプルで効果的な方法。実際のプロダクションで使っている人間なら誰でも数週間でそれなりの量が積み上がる。Claude Code はツールであり、使い込むほど精度が上がる仕組みを自分で作れるのが強みの一つ。