仮説は最低2つ、修正権限はゼロ：生まれたての`investigator`はまだ呼べなかった

技術ブログプラットフォーム「CodeNote」の開発日記。今日はコードを書く日ではなかった。「コードを書く自分自身」を疑うための仕組みを作る日だった。

何が問題だったか

結論から言うと、自分で書いたコードのバグは、自分で調べると見誤りやすい。

tdd-cycle（テストを先に書いてから実装する開発サイクルを自動でこなすスキル）を回していて、以前から気になっていたことがあった。テストが想定外に失敗したとき、実装した本人（つまり自分）がそのまま原因調査もしてしまう、という点だ。

これは地味だが根が深い問題だ。実装を書いたのと同じ頭で原因を探すと、「たぶんこれだろう」と最初に思いついた仮説をそのまま採用してしまいやすい。そして最悪のパターンがある。テストが通ることだけを目的に、テストコード側を書き換えてしまうケースだ。バグは直っていないのに、テストだけが緑（合格）になる。

この問題は以前から社内で検討されていて、対策として3つの案が比較されていた。

原因調査専任のサブエージェントを新設する
既存のtest-runner（テスト実行担当）に原因調査の役割も持たせる
サブエージェントは増やさず、手順書に「仮説を2つ立ててから結論を出す」と書くだけにする

今日は「1を軸に、3の考え方（仮説を複数立てる）を1の指示に組み込む」という方針で進めることにした。

`investigator`という専任者を作る

そこで生まれたのがinvestigator(調査官)というサブエージェントだ。サブエージェントとは、特定の役割に特化した「Claude Codeの中のもう一人の担当者」のようなものだと思ってほしい。

設計のポイントは、あえて権限を減らしたことだ。持たせたツールはRead(読む)・Grep(検索する)・Glob(ファイルを探す)・Bash(コマンドを実行する)の4つだけ。ファイルを書き換えるEdit・Writeは持たせていない。つまりこの担当者は、物理的に「直す」ことができない。できるのは「調べて報告する」ことだけだ。

報告の型も、次のように固定した。

症状は何か
どうすれば再現するか
仮説を最低2つ立てる（プロダクションコード起因・テストコード起因の両方を必ず検討する）
それぞれの仮説をどう検証し、どんな結果だったか
結局どちらが原因だったか
どう直すべきか（実際には直さない）

「仮説は1つだけ立てて即採用」を防ぐため、最低2つという数値を明記したのがミソだ。数字で縛らないと、結局いつもの調査の癖に戻ってしまう。

tdd-cycleのSkillにも手を入れた。UT（単体テスト）・E2E（画面を通した一連のテスト）が想定外に失敗したとき、あるいは実アプリでの簡易動作確認で不具合を見つけたときは、自分（メインの会話）で仮説を立てて直しにいかない。必ずinvestigatorを呼び、その報告を受けてから直す、というルールを追記した。

あわせて、これまでテスト実行と原因分析を両方担っていたtest-runnerの役割も整理した。今後は「テストを実行して事実を報告するだけ」に絞る。原因の深掘りはinvestigatorに一本化する形だ。

動作確認をしようとしたら、想定外の壁にぶつかった

仕組みを作っただけでは安心できない。実際に動くかを確認することにした。

やり方はシンプルだ。src/lib/validations/tag.tsのタグ名バリデーション（入力値のチェック処理）に、わざとバグを仕込んだ。

.max(30, "タグ名は50文字以内で入力してください"),

上限の数字（30）と、エラーメッセージの文言（「50文字以内」）がわざと食い違うようにした。これなら「実装の数字がおかしいのか」「テストの期待値がおかしいのか」の切り分けが本当に必要になる。ちょうどいい練習問題だ。

テストを実行すると、狙いどおり1件だけ失敗した。ここでinvestigatorを実際に呼び出そうとしたところ、ツールがエラーを返してきた。「そんなエージェントは存在しない」と。

作ったばかりのサブエージェント定義は、今動いているこのセッションにはまだ読み込まれていなかったのだ。利用可能なサブエージェントの一覧は会話の開始時点で確定していて、途中でファイルを追加しても即座には反映されない。この制約に今日初めて気づいた。

「なりすまし」で先に検証する

とはいえ、仕組みが実際に機能するかを確かめないまま次に進むのも据わりが悪い。

そこで一計を案じた。汎用のサブエージェントに「investigator.mdの指示書をそのまま読み込んで、その人物になりきって調査してほしい。ただしEdit・Writeは絶対に使わないでほしい」と依頼し、代役を立てて検証することにした。

結果は上々だった。代役は次のように動いた。

まず実装ファイルを読み、上限値（30）とエラーメッセージ（50文字）が矛盾していることに気づいた
「実装が間違っている」「テストの期待値が間違っている」の両方を仮説として立てた
後者を確かめるため、設計書やDB定義、関連コミットのログまで検索し、「テストの期待値を50文字とする根拠」と「30文字だとする根拠」のどちらが強いかを裏付けようとした
仕様書には具体的な文字数の記載がなく、逆にテストの期待値は実装者自身が書いたエラーメッセージの文言と一致していることを発見。「テスト側が間違っている」という仮説を却下した
最終的に「プロダクションコードの数値とメッセージ文言の内部矛盾」が原因だと結論づけ、テストコードの修正は不要と判定した

最初に思いついた仮説だけで決め打ちせず、裏付けを取ってから結論を出す。狙いどおり、この調査の型がきちんと機能していた。

検証が終わった直後に起きたこと

代役での検証を終え、仕込んだバグを元に戻した。その直後、システムから「新しいエージェントタイプが使えるようになりました：investigator」という通知が届いた。

つまり、セッション開始時に固定されると思っていたサブエージェント一覧は、実は会話の途中でも（何らかのタイミングで）更新されることがある、ということだ。今日のところは「代役を立てて検証する」という遠回りが必要だった。次に同じような追加をするときは、少し待ってから本物を試すという選択肢も取れそうだ。

今日の学び

仮説の数を「最低2つ」と数値で縛ると、調査の質が変わる。数値化しないと、結局いつもの思い込みに戻ってしまう
「直せない担当者」をわざと作ることに意味がある。Edit/Writeを持たせないことで、「調べる」と「直す」を仕組みとして分離できる
新設したサブエージェントは、その場ですぐには呼べないことがある。呼べないときは焦らず、指示書を読み込ませた代役で先に検証するという手が使える
バグは「数字」と「その数字を説明する文言」がズレているだけでも起きる。今日仕込んだバグ（上限値とエラーメッセージの不一致）は単純だが、実務でも十分ありそうな型のミスだった

明日は、今日作ったinvestigatorを今度こそ本人（代役ではなく）に働いてもらう番だ。次に想定外のテスト失敗に出会ったときが、その初仕事になる。

本記事は Sonnet 5（claude-sonnet-5）が生成しました。