Claude Codeにバグ調査をさせた時、"ソレっぽい作り話"をさせない
Claude Codeに丸投げ的にバグ解析を頼むと、たまに 「非常に筋が通った原因ストーリー」 が返ってきたりします。
読むと非常にそれっぽい事を言っているのに、実際に確認して見ると「そんな事実は無かった」というご経験、ありませんか?
これは「AIが悪い」というより、証拠が足りない“空白”を、もっともらしい仮説で補完する挙動がデバッグ領域で裏目に出やすいのが原因です。[1][2][3]
なので対策も、プロンプトで人格矯正するより “空白を埋める前に証拠を増やす仕組み” を作るほうが確実だったりします。
この記事では、Claude Codeの Hooks / Memory / /compact / Permissions を使って、作り話の余地をシステム的に潰す方法をまとめます。[4][5][6][7]
サマリ:作り話を減らすの策は「検証の強制」と「前提の固定」
効く順に列挙します。
- Hooksで“編集や実行のあとに必ず検証”を走らせる(推測より先にログを増やす)[4:1][8]
- Memory(CLAUDE.md / .claude/rules)で“デバッグの型”を常設 [5:1]
- /compactを“要約の設計”込みで使う [6:1]
- Permissionsで“危ない操作”や“拾い食い”を抑える(暴走と都合のいい前提を減らす)[7:1]
1) Hooks:推測より先に「必ず検証」を回す
Claude Code hooks は、ライフサイクルの特定タイミングで ユーザー定義のシェルコマンドを必ず実行できます。
「LLMがその気になって走らせる」ではなく、証拠を増やす仕組みです。[4:2]
設定ファイルの置き場所(チーム共有の基本)
プロジェクトで共有する場合の基本ファイルは下記の通りです。
-
.claude/settings.json(Git管理してチーム共有) -
.claude/settings.local.json(個人用・コミットしない) -
~/.claude/settings.json(全プロジェクトに効く個人設定)
公式にもこのスコープ構造が説明されています。[8:1]
例:Next.js/Reactで「編集したら lint/test/build を必ず回す」
PostToolUse で、Claudeがファイルを書き換えた直後に検証を回します。
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{ "type": "command", "command": "pnpm -s lint || true" },
{ "type": "command", "command": "pnpm -s test || true" },
{ "type": "command", "command": "pnpm -s build || true" }
]
}
]
}
}
ポイント
-
|| trueは「失敗ログ(=証拠)は欲しいが会話は止めたくない」ための保険。 - これで、Claudeがそれっぽい原因を語る前に 現実のlint/test/build結果が毎回積み上がります。
イベント名や matcher の例も公式リファレンスにあります(
PostToolUse等は大小文字も含めて正確に)。[8:2]
/compact前に「証拠をファイルへ退避」する(PreCompact Hook)
会話が長引くほど前提が混ざりがちなので、/compact の直前に その時点の差分・状況をファイルへ保存します。
{
"hooks": {
"PreCompact": [
{
"matcher": "manual",
"hooks": [
{
"type": "command",
"command": "bash -lc 'mkdir -p .claude/_evidence && (date; echo; git status --porcelain; echo; git diff --stat) > .claude/_evidence/precompact_manual.txt'"
}
]
}
]
}
}
これで /compact 後に「その時点の差分なんだっけ?」が起きても、.claude/_evidence/ に戻れます。
PreCompact が hooks イベントとして存在することも公式に明記されています。[8:3]
2) Memory:毎回の縛りを言わずに「型」を常設する
Claude Codeは、プロジェクトメモリをファイルで管理できます。特に重要なのが:
-
CLAUDE.md(プロジェクト共通の方針) -
.claude/rules/*.md(ルールを分割し、必要なときだけ適用)
.claude/rules は YAML frontmatter の paths で対象範囲を絞れます。[5:2]
例:CLAUDE.md(でっち上げ防止プロトコル)
# Project Memory
## Anti-hallucination (Debug protocol)
- 断定禁止。主張には必ず根拠を添える(ログ / ファイルパス+行番号 / コマンド結果)
- 根拠がないものは「推測」と明記
- 次にやることは「検証コマンド + 期待結果」で書く
- まず git diff / 再現手順 / 実ログ を集め、推測は後回し
例:.claude/rules/frontend-react.md(React/Nextだけに効かせる)
---
paths:
- "src/**/*.{ts,tsx}"
- "app/**/*.{ts,tsx}"
---
# Frontend rules (React/Next)
- React/Nextの挙動を推測で断定しない。まず再現コマンドとログを根拠にする
- 変更は最小化。関連のないファイルに触れない
- 修正後は lint/build を通す(Hooksで自動化されている前提)
3) /compact:要約を「デバッグ継続に耐える形」に設計する
/compact は会話を要約してコンテキストを圧縮します。
さらに重要なのが、CLAUDE.md に # Summary instructions を書くことで、compact時の要約方針をカスタムできる点です。[6:2]
例:CLAUDE.md に “Summary instructions” を追加
/compact 実行時の要約ルール:
- 必ず残す:再現手順、観測されたログ、差分要約、次に実行する検証コマンド
- 仮説は優先順位つきで残すが、根拠なしに原因を断定しない
- 不明な点は「不明」のまま保持し、確認手順(コマンドと期待結果)を提案する
自動コンパクト(Auto-compact)は /config からON/OFF切り替えできる、と公式に書かれています。[6:3]
4) Permissions:危ない行動と“拾い食い”を抑える
Claude Code は /permissions で allow / ask / deny を設定でき、評価順は deny → ask → allow です。[7:2]
ここで「破壊的コマンド」「ネットワークアクセス」「機密ファイル」を抑えると、事故防止だけでなく都合のいい前提を取りに行く挙動も減ります。
注意:環境やバージョンにより、denyが期待通り効かないケース報告もあるので、導入後は必ず自分の環境でテストしてください。[9]
まとめ:「嘘をつけない状態」を作る
- 作り話は“空白”から生まれるので、Hooksで推測より先に検証ログを増やす[4:3]
- Memoryで “根拠→仮説→検証” を常設し、/compactは要約設計込みで使う[5:3][6:4]
- Permissionsで 危ない行動や拾い食いを抑える[7:3]
補足
- そもそも仕様も理解していない段階でバグ調査をAIに丸投げるんじゃねぇ、というご意見もよくわかります。本記事ではその辺りの議論には目を瞑り、丸投げが発生しうる現実を前提に、推測が作り話に化ける前に「観測(ログ/差分/再現)」を増やして被害を最小化するTipsに絞って紹介させて頂きました。この他にも「こういうアプローチがあるよ!」という内容があれば是非コメントなど頂けますと幸いです
Discussion