Claude Code活用 #15 書いた本人には見直させない──観点ごとにサブエージェントを分けたら、仕様書の質が変わった
blueleaf
「今動いているシステムを、作り直したい」
長く使われてきたシステムほど、この相談は難しくなります。理由はシンプルで、設計書が残っていないからです。作った当時の資料はあっても、その後の改修が反映されていない。担当者はもう社内にいない。結局、いま何が正しいのかを知っているのはソースコードだけ、という状態になります。
いま関わっている案件がまさにこれで、20年近く使われてきた基幹システムを、新しい技術基盤で作り直しています。画面の数は数百。1つの画面のソースが13万文字を超えることもあります。
この「コードを読んで仕様書に起こす」作業を、Claude Code に任せています。今日の話の芯は一つで、サブエージェントという仕組みを使って、観点ごとに、記憶を共有しない別人格のレビュー担当を立てているということです。
技術寄りの話に見えますが、後半で書くとおり、これはプログラミングに限った話ではないと思っています。
その前に：サブエージェントとは何か
先に、この記事の土台になる言葉だけ説明させてください。ここが分かると、あとの話は全部つながります。
エージェントとは、ざっくり言えば「目的を渡すと、自分で考えて手を動かすAI」です。チャットのように一問一答で答えるだけでなく、ファイルを読んだり、検索したり、コマンドを実行したりしながら、任された仕事を最後までやり切ろうとします。ここまでは、いわゆるAIアシスタントのイメージに近いと思います。
大事なのは次です。エージェントにはコンテキストがあります。これは「その仕事のあいだ、頭の中に置いている情報」だと思ってください。これまでの会話、読んだファイル、自分が下した判断。人間でいう「その場の記憶」です。
サブエージェントとは、そのエージェントが、別の作業用に新しく立ち上げるもう一人のAIのことです。ポイントは、サブエージェントがまっさらなコンテキストで始まること。親がそれまで何を考え、何を書いてきたかを、一切知りません。渡された指示と資料だけがすべてです。
この「知らない」が、今回の肝でした。
人間に例えるなら、こうです。同じ会話の続きで「見直して」と頼むのは、書いた本人に見直させるのと同じです。その人の頭の中には、書いたときの前提も、そのとき下した判断も、全部残っている。だから同じ結論に戻ってきます。
一方サブエージェントは、今日初めてその書類を渡された、事情を何も知らない担当者です。「たぶんこういう意図だろう」という忖度がない。書いてあることだけを見て、書いていないことを「書いていない」と言います。
前置きは以上です。ここからが本題です。
最初は「一発で書いて」と頼んでいた
始めた頃は、素直にこう頼んでいました。
このソースファイルを読んで、仕様書を書いてください。
出てくるものは、それなりに立派です。画面の目的があって、テーブル一覧があって、検索条件の表がある。ぱっと見は完成品に見えます。
問題は、読み込んでいくと崩れることでした。
- ソースのどこを探しても出てこないテーブル名が、しれっと書いてある
- 画面にあるボタンが1つ、表から抜けている
- 「〜と思われます」「〜のようです」という推測が、断定と混ざったまま並んでいる
仕様書は、これから実装する人が「これが正解」として読むものです。9割正しくて1割が推測、という状態が一番たちが悪い。どこが推測なのか、読む側には見分けがつかないからです。
そして、同じ会話の続きで「見直してください」と頼んでも、ほとんど改善しませんでした。理由は、さっきのコンテキストの話そのものです。書いた本人は、書いたときの前提を握ったまま読み直す。「このテーブル名はソースのどこかにあったはずだ」という感触が残っているので、もう一度確かめには行きません。自分の書いたものを、自分の記憶で裏書きしてしまうんです。
だとすれば、必要なのは「もう一度見直す」ことではありませんでした。コンテキストを切って、違う観点を持った別人格に読ませることでした。
観点ごとに、サブエージェントを分けた
いまは大きく2段階・4つの観点で動いています。それぞれが独立したサブエージェントで、コンテキストは共有していません。切り方は、工程というより「何を見るか」です。
第1段階：古いコードから、現行システムの仕様書を起こす
- 書く担当（観点：この関数は何をしているか） — ソースを関数単位に分割して、1つの関数につき1体のサブエージェントを立てます。1体が数十の関数を流し読みすると取りこぼしが出るので、「あなたはこの関数だけを見てください」と持ち場を狭くして、全員を同時に走らせます。
- 確かめる担当（観点：書かれていないものは何か） — 書く担当が作った調査メモを、別のサブエージェントが独立に検証します。見るのは「書いてある内容が正しいか」ではなく「数が合っているか」です。ソースを機械的に数えて（SQL文が何本、エラーメッセージが何個）、メモの記載数と突き合わせる。合わなければ差し戻して、その関数だけ書き直させます。書いた本人には持てない観点です。
第2段階：現行システムの仕様書から、新システム向けの仕様書に書き直す
ここが今回の肝で、同じ1本の仕様書を、まったく違う2つの観点で読む2体を立てています。
- 設計者としてレビューする担当（観点：新旧が一致しているか） — 新旧の仕様書を並べて、変換の漏れと、逆に残ってはいけないものの残存を見ます。旧システムにあった検索条件が新システム側で消えていないか。逆に、新システムでは不要になったはずの旧画面固有のボタンが残っていないか。この担当は、新システムのコードを一切見ません。見るのは新旧の対応関係だけです。
- 実装者としてレビューする担当（観点：これで手が動くか） — 対照的に、この担当は旧システムの仕様書を見ません。「この仕様書を渡されて、自分は実装できるか」だけを考えます。書かれているテーブルやカラムは新システムのDBに本当に実在するか（実際にDBに接続して確認します）。曖昧な記述やTODOが残っていないか。最後に「実装着手OK／修正必須／議論が必要」のどれかを必ず宣言させます。
3と4は、それぞれ新しいサブエージェントとして起動して、同時に走らせています。渡すのは仕様書のパスと、観点を書いたチェックリストだけ。仕様書を作っていたときの経緯は、どちらも知りません。「ここは議論の末にこう決めた」も「ここは時間がなくて雑になった」も伝わらない。だから、忖度なしで書いてあることだけを見ます。
そして、2体はお互いの結果も見えません。片方の指摘が見えると、それに引きずられて、せっかく分けた観点が1つに戻ってしまうからです。
効果は、出てくる指摘のズレにはっきり出ました。同じ仕様書を読んでいるのに、2体の指摘はほとんど重なりません。設計者役は「メーカー欄が旧仕様から消えている」と言い、実装者役は「このカラムはDBに存在しない」と言う。どちらも、もう一方には見えていない指摘です。
結果は優先度つきで統合されて、こんな形で手元に届きます。
🔴 重大 2件／🟡 中 5件／🟢 軽微 3件 どこまで対応しますか？（重大のみ／重大+中／全件／個別に判断）
実際の数字でいうと、13万文字のソースから1000行程度の現行仕様書ができて、そこから新システム向けの仕様書が約570行。この一連を、レビューまで含めて回しています。
効いたのは、この3つでした
コンテキストを切るだけでは足りない。観点も変える
一番効いたのは、サブエージェントに分けるときに、観点まで分けたことでした。
コンテキストを切るのは前提条件にすぎません。まっさらな状態で起動しても、渡す観点が同じなら、結局同じところしか見ないからです。だから設計者役と実装者役には、見るべき資料そのものを変えて渡しています。片方には新旧2本の仕様書だけ。もう片方には新仕様書と、実物のDBとコードへの接続手段だけ。見えるものが違えば、見つかるものも違う。
さらに、書く担当と確かめる担当では使うAIモデルそのものを変えています。同じモデル同士だと、得意なところも苦手なところも似てしまう。見落としが同じ場所で重なるんです。あえて別のモデルにすることで、盲点がずれてくれます。
観点を、ドキュメントに固定する
サブエージェントはまっさらな状態で来ます。裏を返せば、渡した指示がすべてです。「よろしくレビューしてください」だけでは、その時々で見る場所が変わってしまう。
そこで、観点そのものをチェックリストとして書き出して、ファイルに保存しました。
- 旧仕様書のカラム表と新仕様書のカラム表を、1行ずつ照合する（省略禁止）
- 指摘には必ず行番号を添える
- 消えているべき旧システム固有のUIが残っていないか
これを毎回読み込ませてからレビューさせます。人がやると、疲れている日は「まあ大丈夫だろう」で飛ばしてしまう工程です。それが毎回きっちり同じ厳しさで回る。観点はファイルになった瞬間、担当者の体調から切り離せるということでもあります。
推測させず、実物を見に行かせる
AIは、知らないことをそれらしく埋めてしまいます。なので「推測するな、実際に見に行け」と手順に組み込みました。テーブルが実在するかは実際のDBに問い合わせる。参照している画面が既に実装済みでないかは、実際のリポジトリを検索する。
これは実害を防いだ場面がありました。「この画面は新規で作る」という前提で仕様を書きかけたところ、実装者役が実リポジトリを調べて、画面の見た目部分だけ既に実装済み（中身は未実装）だと見つけたんです。気づかなければ、二重に作るところでした。「新規で作る」という思い込みを共有していないサブエージェントだからこそ、素直に実物を確認しに行けた指摘だと思っています。
あわせて、仕様書には「〜と思われます」の類を書くことを禁止し、最後に該当表現を機械的に検索して残っていないか確認しています。仕様書は指示書であって、調査メモではないからです。
小さなチームでも、レビュー体制は作れる
ここからが、本当に書きたかったことです。
「作る人とは別に、レビューする人を置く」。これは、体制に余裕のある組織の話だと思われがちです。うちのような小さなチームだと、そもそも人が足りない。書いた本人が確認して、そのまま出す。よくある光景だと思います。
でも今回やってみて感じたのは、レビュー体制の本質は人数ではなく「観点が言語化されているかどうか」だということでした。
「設計者として、新旧が一致しているかを見る」 「実装者として、これで手が動くかを見る」
この2つは、見ている場所がまったく違います。そして、これらは紙に書ける。書けるなら、サブエージェントに渡せます。人を増やさずに、観点だけを増やすことができる。
しかもこれは、プログラミング固有の話ではないはずです。見積書を出す前に「この金額でお客様は納得するか」という営業目線と、「この工数で本当に作りきれるか」という現場目線は別物です。提案書も、契約書も、採用の募集要項も同じでしょう。一人で書いて一人で見直しているものほど、観点を分ける効果が出ると思っています。
やり方も、大げさなものではありません。まず自分が普段どういう観点で見直しているかを1つずつ書き出して、観点ごとにファイルを分ける。あとはその観点を、それぞれ別のサブエージェントに、経緯を渡さずに投げるだけです。うちも実際、見積もりやブログ記事のチェック観点を同じようにファイルに書き出して使っています。今回の仕様書レビューは、それを一番シビアな場所に持ち込んでみた、という位置づけです。
サブエージェントを使えると、AI活用の幅が広がる
最後に、この記事で一番お伝えしたいことを。
今回やったことは、同じ1つの仕事を観点で切り分けて、それぞれに経緯を見せずに渡した、それだけです。まっさらな担当者が来るというのは、裏を返せばこちらが見せたものしか見えないということでもあります。設計者役に新システムのコードを見せない、実装者役に旧仕様書を見せない。この「見せない」判断が、あの2体の指摘のズレを作っていました。
ただ、これはサブエージェントの使い道の一つにすぎません。サブエージェントを使いこなせるかどうかが、AI活用の幅をそのまま決めているというのが、いまの実感です。代表的な使い方を3つ挙げます。
- 独立した視点を持たせる（今回の話）— コンテキストを分けて、経緯を知らない別人格として立てる。書いた本人には見えないものが見えます。レビュー、チェック、セカンドオピニオンはこの形です。
- 数で押す — 調べものを100体以上のサブエージェントに分担させて、一斉に走らせる。世に出ている「ディープリサーチ」系の機能は、だいたいこの形です。1体で順番に読んでいたら日が暮れる調査が、現実的な時間で終わります。
- 役割を与えて議論させる — たとえば事業計画を検討するとき、財務担当・マーケティング担当・現場担当をそれぞれサブエージェントとして立て、同じ計画について意見を出させる。一人で考えているうちは出てこなかった反論が出てきます。
共通しているのは、1体のAIと一問一答するのをやめた瞬間に、できることが変わるという点です。同じAIでも、1体に全部聞くのと、切り分けて渡すのとでは、返ってくるものがまるで違います。今回の仕様書づくりは1番の使い方でしたが、2番も3番も、うちの中で普通に使っています。
なので、もし1つだけ試すなら、次に何か書き終えたとき、同じ画面で「見直して」と続けないことからをおすすめします。自分がいつも見直している観点を1行だけ書き出して、新しいサブエージェントに、経緯を渡さずに投げてみてください。それだけで、返ってくる指摘の質が変わるはずです。
そこから、観点の数を増やす（1番）、手分けさせる（2番）、議論させる（3番）と広げていける。AIをうまく使うというのは、いい指示を1つ書くことよりも、どう分けて誰に渡すかを考えることなんだと思います。仕様書という一番ごまかしの効かない書類でそれが通ったので、たぶん他の仕事でも通ります。
＼ 最新情報をチェック ／
