Claude Codeの見積もり根拠をplan modeで作る — 影響範囲を数えて工数の前提表にする

既存システムの改修見積もりで工数がぶれる最大の原因は、変更の影響範囲を最初に見誤ることです。Claude Codeのplan modeはソースを編集せずにコードを調べられるので、この「数える作業」を安全に任せられます。

ただし、任せるのは数えるところまでです。ファイル数・呼び出し元・テスト数を表にして、人が人日に直すときの前提リストにします。Claudeに「何人日ですか」と聞いて出た数字を、そのまま見積書に載せる使い方はしません。ここでは、根拠表の作り方、数え漏れを減らす頼み方、人が確かめる点を順に示します。

提案前の段階で、要件メモから人月の幅を出す作業は工数見積(人月)をClaudeで書き出す手順が扱っています。こちらは既存コードが手元にあり、「この変更はどこまで波及するか」をコードから数える場面が対象です。

plan modeが見積もりの調査に向く理由

plan modeは、Claudeがファイルを読み、調査用のシェルコマンドを実行して計画を書き出し、ソースは編集しないモードです。計画を承認するまで編集はブロックされます。

見積もりの調査に向くのは、「調べるだけで、直さない」がモードの仕組みで担保されるからです。ただし、bypass permissionsを使える対話セッションでは、計画の承認前でも編集のブロックが外れます。見積もりの調査では、bypass permissionsを有効にせずに起動します。

調査中のシェルコマンドの扱いは、セッションの状態で変わります。

• auto modeが使え、useAutoModeDuringPlanがオン(既定)の場合: 分類器がコマンドを審査し、承認されたものが実行されます
• auto modeが使えない、または設定がオフの場合: 組み込みの読み取り専用コマンド以外は承認を求められます

読み取り専用コマンドの集合にはls・cat・grep・find・wc・diff・gitの読み取り系などが含まれます。影響範囲を数える作業は、この範囲でほぼ収まります。設定の詳細はuseAutoModeDuringPlanの解説に譲ります。

起動は次のどちらかです。

claude --permission-mode plan

セッション中ならShift+Tabでモードを切り替えるか、プロンプトの先頭に/planを付けます。起動方法と承認フローの全体はPlanモード完全ガイドにあります。

根拠表に入れる列を先に決める

数えさせる前に、表の列を決めておきます。列が曖昧だと、「関連しそうなファイル」まで件数に混ざり、数字の意味が人によって変わります。

見積もりの前提リストとして使いやすい列は次の5つです。

最後の「不確実な点」を必ず設けるのがこの表のコツです。検索で数えられるのは、名前が文字列として現れる参照だけです。リフレクションや設定ファイル経由の呼び出し、他リポジトリからの利用は数字に出ません。数えられなかった範囲を空欄で隠さず、行として残します。

手順: 数えさせて、表にさせて、再現コマンドも書かせる

流れは4段階です。

頼み方の例

次のようなプロンプトを、plan modeで投げます。

消費税の端数処理を切り捨てから切り上げに変える改修の
影響範囲を調べて、次の列の表にしてください。
- 変更対象(ファイルと関数名)
- 呼び出し元(ファイルと行数、件数)
- 既存テスト(ファイル名と件数)
- 追加が必要なテスト
- 不確実な点(検索では分からない部分)
条件:
- ソースは編集しない
- 件数の横に、数えた検索語またはコマンドを書く
- 工数(時間・人日)の見積もりは書かない
- 数えられなかったものは、推測で埋めず不確実な点の行に書く

最後の2つの条件が線引きです。工数を書かせないことで、Claudeの出力は「事実の列挙」に留まります。数字の根拠をコマンドで残させるのは、人が検算できるようにするためです。

次の形が、返ってきてほしい表のイメージです。数字は説明のための架空の例です。

Claudeの数字を検算する

根拠表の価値は、数字が再現できることにあります。plan modeの調査は、Claudeが検索して数えた結果です。数え方に偏りがあれば、件数もずれます。

人が確かめるときは、表に書かれたコマンドをそのまま手元で実行します。

git grep -n "roundTax(" -- 'src/*.ts' | wc -l
git grep -l "roundTax(" -- 'tests/*' | wc -l

パスのパターンは引用符で囲んでいます。find・sort・sed・gitのように書き込み系のフラグを持てるコマンドは、Manual modeで引用符なしのglobを含むと承認を求められます。Claudeにコマンドを書かせるときも、引用符付きで書くよう頼んでおくと、調査が止まりにくくなります。

検算で見るのは次の4点です。

• 検索語の取りこぼし: 別名・エイリアス・ラッパー関数経由の呼び出し
• 件数の水増し: コメントや文字列、生成コード、ビルド成果物の中の一致
• テストの数え方: ファイル数とテストケース数が混ざっていないか
• 範囲外: モノレポの別パッケージや別リポジトリからの利用

件数が合わなければ、表の該当行を直して使います。Claudeに「数え直して」と頼むときは、どの検索語が足りなかったかを伝えると、同じ失敗を繰り返しにくくなります。

調査が広いときの進め方

対象が大きいコードベースだと、調査の出力が会話を圧迫します。plan modeでコードベースを理解する必要があるとき、Claudeは調査をPlanサブエージェントに任せます。サブエージェントは読み取り専用のツールだけを使い、調査の出力は別のコンテキストウィンドウに留まります。メインの会話は読み取り専用のまま、結果の要約だけを受け取る形です。

広い範囲の検索は、組み込みのExploreエージェントも担当します。Exploreを呼ぶときの探索の深さには、quick・medium・very thoroughの3段階があります。粗い当たりを付ける段階と、提出前に精査する段階とで、深さを分けて頼む使い方ができます。

対象を絞るために、変更の入口になるモジュールやディレクトリをプロンプトで指定する方法も有効です。dbtのようにモデルの依存関係を機械的にたどれる領域では、ツール側のセレクタで影響範囲を出す方が確実です。その例はdbt build --selectの手順にあります。

表から見積もりに進む前に人が決めること

根拠表が出来たら、人日への換算は人が行います。換算に必要な判断は、表の外にあるからです。

• 1ファイルを直す重さ: 同じ件数でも、定型の置換と、設計を伴う改修では工数が違います
• テストの書きやすさ: 既存テストが整っているか、まず環境整備が要るか
• レビューと調整の時間: 関係者が多い箇所、承認が要る箇所
• 不確実な点の扱い: 幅に含めるのか、前提条件として除外するのか

最後の項目は、提案前の見積で前提・除外条件を表にする考え方と同じです。根拠表の「不確実な点」の行は、そのまま見積書の前提条件の下書きになります。チームの過去実績があれば、同程度の件数の改修にかかった実績と並べて換算します。

変更の種類で、数える対象を変える

同じ表でも、変更の種類によって「呼び出し元」にあたるものが違います。頼む前に、何を数えるのかを一行添えておくと、件数の意味がそろいます。

「見落としやすい点」の列は、そのまま「不確実な点」の行の下書きになります。プロンプトに「この種類の変更では、次の点は検索で拾えないので不確実な点に書く」と添えておくと、空欄のまま渡される表が減ります。

つまずきやすい点

• plan modeのつもりが編集可能になっている: 計画を承認すると、plan modeを抜けて編集が始まります。表を受け取っただけなら承認せず、「No, keep planning」で止めるか、Shift+Tabでモードを抜けます
• 検索結果が多すぎて表が読めない: 呼び出し元は、件数と代表例の数件に絞らせます。全件は再現コマンドで人が必要なときに出せます
• 古い表を使い回す: コードは日々変わります。見積もりの根拠として提出する表は、提出直前の状態で数え直します

まとめ

plan modeに任せて価値が出るのは、影響範囲を数えて表にするところまでです。件数と再現コマンドと「不確実な点」を並べておけば、人日への換算は、表を見ながら人が前提を一つずつ置いていく作業になります。Claudeの調査は、見積もりの数字を出すためでなく、人が置く前提の数を減らすために使います。