こんなことが起きている → どうするか
題ではなく症状から引きます。「どうするか」の下のリンクで、その打ち手を書いた節へ飛びます。 全記事の目次はこのページの下にあります。
この表は Claude Code(Anthropic のコーディングエージェント)を前提にしています。hook・CLAUDE.md・subagent・auto memory はその機能名です。
| こんなことが起きている | どうするか |
|---|---|
| AI がテストを走らせるたび、数万行の出力がコンテキストに流れ込む |
テスト実行をラッパースクリプト 1 本に集約し、全出力はログファイルへ落として、AI に返すのは失敗の要約だけにします。 |
| AI が知見メモを保存するほど、以後の全セッションが読む量が増えていく |
メモリへの書き込み直前に走る PreToolUse hook でチェックリストを読ませます。指示ファイル(CLAUDE.md)に置くのは「書く前に読む」の 1 行だけにします。 |
| テストは通っているが、それが本当に何かを守っているのか分からない |
mutation testing(テストをわざと壊して落ちるか見る手法)の方針を 1 枚のドキュメントにして、テストの点検を依頼するときに読ませます。 |
| 登録したスキルを、AI が使うときと使わないときがある |
コマンドは通常のスクリプトのまま置き、誤った呼び出し方を PreToolUse hook で止めて、読むべきドキュメントを案内します。 |
| サブエージェントに投げた仕事は、終わるまで何が起きているか見えない |
サブエージェントに委譲してよいタスクと、起動前に必要な入力ファイルを YAML で定義し、hook で起動前に検査します。 |
| 指示ファイルにルールを足すほど、前に足したルールが守られなくなる |
「〜しないこと」というルールを 1 件ずつ、違反を検出できる自動テスト(Minitest)に書き換えます。 |
| 並列で走るセッションが共有するメモリが荒れる。方針を読ませても効かない |
同じ方針ファイルを PostToolUse hook へ移し、保存後の差分と一緒に提示します。読ませる内容は変えず、タイミングだけ変えます。 |
| 同じ失敗への対処を書いておいても、AI は次にまた同じ失敗をする |
リトライ時の方針を数行のファイルにまとめ、失敗を検知した hook から自動で挿入します。 |
| 引き継ぎ文と完了報告を読んでも、都合の悪いことが落ちている |
完了報告の隣に、git diff --stat などで機械的に取得した数値を毎回並べます。 |
| 機械が数えた数字が、報告に着くまでに別の数へ変わっている |
数値の行に固定の接頭辞を付け、それが逐語でコピーされているかを hook で検査します。 |
| 作業中の AI に口を挟むと、そのあとの動きが崩れる |
作業中に人が口を挟む代わりに、保存直後に方針を返す PostToolUse hook と、失敗を検知して差し戻す hook に介入させます。人は区切りまで待ちます。 |
| セッションの終わりに、何を読んで何を読まなくてよいのか決まっていない |
成果物も作業ログも読まず、テストやリンターの終了コード(exit code)による合否だけを見ます。 |
| 一度断った提案が、次のセッションでまた出てくる |
却下した判断を、決まったフォーマットで 1 つのドキュメントに集約します。 |
| 禁止の 1 行を書いたのに、拡大解釈も縮小解釈もされる |
却下した判断をまとめた 1 つのドキュメント(例: non_goals.md)で、禁止事項ごとに「理由」の見出しを設け、結論と併記します。 |
| 禁止が正しく書いてあるのに守られない。そのたびに相談が来る |
却下ドキュメントの禁止事項ごとに「適用範囲」の見出しを設け、判断に迷う境界のケースを 1 行ずつ列挙します。 |
| 同じ指示を複数のサブエージェントに配ると、返ってくる形が体ごとに違う |
サブエージェントに渡してよいタスクの一覧に、起動前に用意すべき入力ファイルを明記します。 |
| 自動テストの無い禁止事項が、書いてあるだけのまま積み上がる |
却下ドキュメントの一覧に「機械検証」の見出しを追加し、対応する自動テスト(Minitest)の有無を項目ごとに明示します。 |
| AI の作業が毎回「画面を開いて確認してください」で終わる |
Playwright でスモークテストを 1 本用意し、合否は画面の見た目ではなく DB に残ったレコードで判定します。 |
| AI が少しズレたことを言うたび、こちらが説明して直している |
ズレを人が説明して直す代わりに、指摘を hook の stderr(exit 2)と自動テストの失敗メッセージに書き、AI に届く経路をそちらに揃えます。 |
| 断った判断の一覧が増え続けて、いつか読まれなくなりそう |
却下ドキュメントの末尾に「採用しなかった案」の節を設け、却下した提案はそこへ記録します。 |
| 指示ファイルの「必ず実行してください」が、減らないまま残っている |
指示ファイルが「必ず実行」と書いているコマンドが pre-commit hook にも存在するかを、突き合わせる自動テストで検証します。 |
| やり方まで書いて渡しているのに、そのとおりには直ってこない |
手順を指示する代わりに、サブエージェントの起動前に存在していなければならない入力ファイルを、用途ごとに定義します。 |
| 不具合を伝えるのに、毎回こちらが手順と症状を書き起こしている |
不具合報告フォームを設置し、人が入力するのは症状の一文だけにして、URL・操作履歴・ブラウザ情報は JavaScript で自動収集します。 |
| 「まず計画を出して」と打つ手間が、毎回かかっている |
新たな実装は不要です。設計ドキュメントを 1 本置けば、AI は既存のドキュメントを読んで同じ体裁を踏襲します。 |
| 守ってほしい行ほど強く書いているのに、効いているか分からない |
効果測定はやめて、指示ファイル内の強調表現を含む行数を数え、基準値を超えたら失敗する自動テスト(ratchet)を置きます。 |
| サブエージェントの成果物が、こちらの想定と違う形で返ってくる |
サブエージェントの用途ごとに、成果物の受け入れ条件(ファイル名・形式・必須項目)を 1 枚のドキュメントに定義します。 |
| 間違いを見つけると「ちゃんと読みましたか」と問い詰めたくなる |
問い詰める代わりに、依頼の 2 文目を「〜ではないですか?」の疑問形テンプレートに固定します。 |
| 返ってきた答えに「そうじゃなくて」と返しても、良くならない |
指摘する代わりに、代替案のない禁止事項を PostToolUse hook から保存直後の差分と一緒に提示します。 |
| AI が、開いていないファイルの中身を開いたかのように話す |
参照先の文書とコードの両方に対応する印(marker)を書かせ、印が実在するかを自動テストで検証します。 |
| AI から「A と B どちらにしますか」と聞かれ続けて、手が止まる |
即答するのをやめ、選択肢の判定が自動テストや hook の側で決まるようにします。 |
| AI にレビューをさせているが、何を見ていないのかが分からない |
ファイルを走査しているのに件数の下限(assert_operator ... :>=)を持たない自動テストを、外から数える自動テストで検出します。 |
| 撮影画像が溜まっていくが、どれが何を確かめた 1 枚か分からない |
画面確認の前に「何を検証するか」「なぜ安い手段では済まないか」の 2 問に答えさせ、単体テスト → 結合テスト → E2E の順に安い手段から試す指針を 1 枚置きます。 |
| 書かせる工程を置いたのに、書かずに走った実行の数を数えられない |
撮影や E2E の前に「何を検証するか」を書く宣言ファイル(例: tmp/visual_verification.md)を置き、その存在を PreToolUse hook の実行条件にして、無ければ撮影や E2E が起動しないようにします。 |
| コードを変えていないのに同じテストが走り、そのぶん待たされる |
テストのラッパースクリプトに --last オプションを追加し、前回のログを再表示して再実行を不要にします。 |
| 何も壊していないのに、見覚えのないエラーがずらりと並ぶ |
テストのラッパースクリプトで排他ロック(mkdir の原子性を利用)を取り、取得できなければ実行しないようにします。 |
| 「テストは通っています」の報告に、走らなかったぶんが書かれていない |
重い E2E に領域名のタグを付けて既定では skip し、実行しなかった領域の一覧を毎回出力します。 |
| 進め方を指定した指示が、守られたのかどうか後から見分けられない |
手順を守らせたいときは指示の書き方を強めず、その手順を踏んだ痕跡が成果物として残る形に変更します(例: 開いたファイルごとに 1 行出力させる)。 |
| 置いたラッパーが、途中から素のコマンドに戻されている |
ラッパーを使わせたいときは指示を強めず、素のコマンドへ戻る必要が残っていないか(ラッパーの機能が不足していないか)を確認します。 |
| 同じ問いを何度も投げると答えが毎回違う。まとめると何かが消える |
複数の回答を 1 つに集約する前に、指摘の種類ごとの出現数(何件中何件が挙げたか)を出力します。 |
| 「必要なら〜してください」と書いた行が、発火したのか分からない |
「必要なら〜してください」という条件付きの指示は書かず、その工程を経ないと次へ進めない hook で強制します。 |
| 「もう一度考えて」と返すと答えが変わるが、納得したのか分からない |
「もう一度考えてください」と差し戻さず、どの前提が誤っているかを具体的に指摘します。 |
| 「推測するな」と書いたら、AI が何も作らずに帰ってくるようになった |
禁止だけを渡さず、「該当しない場合は『該当なし』と出力してください」のように、代わりの出力先を併記します。 |
| うまくいっている会話を続けていると、確かめる手間が増えていく |
タスクの区切りでセッションを終了し、次のタスクは新しいセッションで開始します。 |
| 成果物は全部正しいのに、そこに残らない無駄が積み上がっている |
成果物が揃った時点で、作業ログ(transcript)の側をスクリプトで 1 回集計します。 |
| 次の人のために書き残した知見が、実物と食い違って古くなる |
知見はドキュメントに書き残さず、自動テストの失敗メッセージや hook の停止メッセージに埋め込んで、必要な瞬間に出力されるようにします。 |
| 原因を掘り続けて、答えが出たあとも読み続けている |
作業ログから「何も変えないまま続いた読み取りの連続」を数え、掘り始める前に終わりの条件を 1 行で書きます。 |
| 単価がいちばん安いモデルを、用途を測らずに既定にしている |
同じ課題を安いモデルと高いモデルの両方へ渡し、完了までの手番と、新しく読ませた量・使い回した量(cache read)・書いた量を別々に数えてから決めます。 |
| うまくいかないと、仕組みではなくモデルを上げに行っている |
同じ課題を高い側と安い側の両方へ渡し、安い側だけが落ちた箇所を検査にして置きます。 |
| 本体で終わる調べものを、念のためサブエージェントへ渡している |
渡す前に「その前提を親のエージェントがもう持っているか」を見ます。持っているなら親のエージェントで続け、持っていない大量の読み取りだけサブエージェントに渡します。 |
| とりあえず 4 つに割って、同時に走らせている |
サブエージェント 1 つに渡すのは、1 回の応答で返せる大きさまでにします。費用を決めるのは数ではなく、分割した先の 1 つが親のエージェントと何往復するかです。 |
| 作業の途中で「ここも見て」と外から差し込んでいる |
作業の区切りまで待ってから、範囲を狭めて追加の依頼を入れます。AI 本人に不足点を聞くときは「足りているなら足りていると書いてください」を必ず添えます。不足点をひねり出さずに済む逃げ道(escape hatch)を用意するためです。 |
| どのモデルを使うかを、比べて決めようとしている |
モデルを比べ始める前に、その比較が hook や自動テスト何本ぶんの手間かを数えます。書き出せる仕組みのほうが多いなら、比較より先にそれを置きます。 |
| 「差はありませんでした」で、検証を畳もうとしている |
「差はありませんでした」で畳む前に 2 つ数えます。集計から外した結果(失敗したサブエージェントなど)があるなら戻して数え直し、全条件で 0 の項目が半分以上なら課題の言い方を変えて測り直します。 |
全記事の目次
連載ごとに、序論から最終回までの並びです。
はじめに —— 3 つの連載を、1 冊に
バイブコーディングにおける読まない技術
- 読まない技術 序論 AIの出力を、もうほとんど読んでいない
- 読まない技術 第1回 テスト結果を読まない技術
- 読まない技術 第2回 メモリを読まない技術
- 読まない技術 第3回 単体テストを読まない技術
- 読まない技術 第4回 スキルを使わない技術
- 読まない技術 第5回 サブエージェントの出力だけは読め
- 読まない技術 第6回 ルールを読まない技術
- 読まない技術 第7回 共有メモリを整理しない技術
- 読まない技術 第8回 修正履歴を読まない技術
- 読まない技術 第9回 引き継ぎを読まない技術
- 読まない技術 第10回 AIに要約しろと言わない技術
- 読まない技術 第11回 口を挟まない技術
- 読まない技術 第12回 作業結果を読まない技術
- 読まない技術 最終回 AIの出力を、ほとんど読まなくなった
AIの意見を聞かない技術
言わない技術
- 言わない技術 序論 AI に指示することが、ほとんどなくなった
- 言わない技術 第1回 検証を指示しない技術
- 言わない技術 第2回 具体的な指示を出さない技術
- 言わない技術 第3回 不具合詳細を書かない技術
- 言わない技術 第4回 計画を書けと言わない技術
- 言わない技術 第5回 念を押さない技術
- 言わない技術 第6回 サブエージェントの出力だけは、細かく指示しろ
- 言わない技術 第7回 AI を問い詰めない技術
- 言わない技術 第8回 AI にダメ出ししない技術
- 言わない技術 第9回 AI に考えさせない技術
- 言わない技術 第10回 質問に答えない技術
- 言わない技術 第11回 AI にレビューをさせない技術
- 言わない技術 最終回 何もしない技術
付録
はじめに —— 前巻の続きを、もう 1 冊に
確かめない技術
動かさない技術
追わない技術
番外編
- 番外編 A-1 整理する技術 —— 記録が増えたときに、何が起きているか
- 番外編 A-2 指示を残す技術 —— 「調べるだけ」が通らなかった日
- 番外編 A-3 参照するタイミングを変える技術 —— 2,000 行の壁
- 番外編 A-4 導出を依頼者の言葉と分ける技術 —— 誰も言っていない条件が、memory に載った日
- 番外編 A-5 memory を要約しない技術 —— 整理から、要約を抜く
- 番外編 A-6 責務で線を引く技術 —— 仕組みが増えたときに、どれを消すか
- 番外編 A-7 読まれたかを確かめる技術 —— 確かめるのをやめて、読めていない形を止めた
- 番外編 A-8 面積で数える技術 —— 読ませた量で数えていたら、102 倍外していました
- 番外編 A-9 ルールを短くする技術 —— 読みに来るのは、止められた直後の人です
- 番外編 B-1 連載を本にする技術 —— 本単位のスイッチでは、足りなかった日
- 番外編 C-1 校正の方法に、先に本編を当てる技術 —— 方法を決める文が、本文と同じ地雷を踏んでいた日
- 番外編 C-2 仕組みと人を分ける技術 —— 検査を置いたその手で、検査の外側で 2 度転んだ日
- 番外編 C-3 要素ごとに観点を変える技術 —— 一様に当てた点検が、要素をまたいだところで数を落としていた
- 番外編 C-4 指示の揺れを、事故として残す技術 —— 事故を見て置いた仕組みは、まだ一度も鳴っていない
- 番外編 C-5 作業の流れを見る技術 —— 終わりにしたつもりの日に、まだ起きていたこと
- 番外編 C-6 作業を進める技術 —— 選ぶ場面が、1 つも残らなかった日
- 番外編 C-7 基準の出どころを見る技術 —— 2 分前に開いたページに、答えが書いてありました
- あとがき —— 本当の事実はどうでもいい話