アプリを作り進めていくと、あるところで景色が変わります。

最初は2〜3個だったファイルが、気づくと15個、20個になっている。どれがどれを呼んでいるのか分からない。何かを直そうとして開いたファイルが、そもそも使われているのかも自信がない。

この記事は「AIへの質問文をどう書くか」の話ではありません。自分にもう見えていない範囲を、一望できる形に変換してもらう話です。

なお、初めて見る他人のコードを読むときは範囲を1点に絞ったほうがいいのですが、自分が育ててきたプロジェクトは逆で、先に全体を持ったほうが早いです。今日は後者の話をします。

つまずくのは「読む力」ではない

この段階でつまずく方は多いのですが、原因は読む力が足りないことではありません。全体の地図を持たないまま、部分だけを読み続けているのが実際のところです。

地図がないと、こうなります。

  • 直したい箇所を探すのに毎回ファイル検索から始める
  • 直した結果、別の場所が壊れる
  • AIに「ここを直して」と頼むとき、どのファイルの話なのか説明できない
  • 結果、依頼が曖昧になり、AIも見当違いの場所を触る

最後の項目が地味に効いてきます。自分が全体を把握していないと、AIに渡す情報も曖昧になりやすいので、返ってくるものの精度も落ちます。

対処：構成図を描かせて、1枚にする

やることはシンプルで、AIに今のプロジェクトの構造を図に起こしてもらいます。文章で説明させると長くなって結局読まないので、図の形式を指定するのがポイントです。ここでは Mermaid（マーメイド）という、テキストで図を書くための記法を指定します。

このプロジェクトの構成を Mermaid の flowchart で書いてください。

条件:
- 画面（ページ）・データを扱う処理・外部サービスの3種類に分けて表現する
- 矢印は「呼び出す側 → 呼ばれる側」の向きで
- ファイル名も併記する
- 実際に存在するファイルだけを書く。推測で補完しない

こういうものが返ってきます。

flowchart TD
  A["トップ画面<br/>app/page.tsx"] --> B["一覧取得<br/>lib/getItems.ts"]
  C["詳細画面<br/>app/items/page.tsx"] --> B
  B --> D["Supabase<br/>（外部サービス）"]

これを GitHub の Markdown ファイルや Obsidian に貼るときは、コードブロックの言語指定を mermaid にします。そうすると、テキストのままではなく図として表示されます。ただのテキストなので、コードと一緒に置いておけるのも利点です。

最後の「推測で補完しない」は入れておいたほうがいいです。これがないと、一般的なプロジェクト構成を想像で足してくることがあります。実際にはないファイルが図に載っていると、地図として使えません。

出てきた図は、この順番で見る

図が出てきたら、眺めて終わりにせず、次の順で見ていきます。

まず、自分が知らないファイルを探す

「これ何だっけ」というファイルが、たいてい1つ2つ出てきます。ここが、自分の理解が抜けている場所です。そのファイル名を挙げて「これは何をしていますか」と聞けば、抜けが埋まります。最初にここを潰しておくと、以降の見え方が変わります。

次に、矢印が集中している箇所を見る

たくさんの場所から呼ばれているファイルは、直したときの影響範囲が広い場所です。ここを触るときは慎重にする、という判断ができます。

逆に、どこからも矢印が来ていないファイルは、消し忘れの可能性があります。ただし Next.js の場合、page.tsx や layout.tsx のようにフレームワークが決まった名前で拾う入口のファイルは、矢印が来ていなくても正常です。消してはいけません。判断に迷ったら、そのファイル名を挙げて「これは消しても大丈夫ですか」と聞いてください。

最後に、自分の想像との食い違いを探す

「この画面からデータを取っていると思っていたのに、別の場所を経由していた」といった食い違いが見つかることがあります。この食い違いが、あとでバグの原因になりやすい部分です。

描く頻度

毎日やる必要はありません。ファイルを5個くらい足したタイミング、あるいは「なんだか分からなくなってきた」と感じたタイミングで1回描けば十分です。

慣れてくると、図を描かせる前に「たぶんこうなっているはず」と自分の中で予想が立つようになります。その予想と図が一致するようになったら、地図が頭の中に入った、ということです。

これはコード以外でも使えます

やっていることを抽象化すると、「自分が把握しきれなくなった対象を、AIに一望できる形へ変換させる」という作業です。

大量の資料を渡して関係を図にしてもらう、長いやりとりの経緯を時系列にしてもらう、といった場面でも同じことができます。全体像を持ってから細部に入る、という順番自体は、プログラミングに限った話ではありません。

まとめ

  • ファイルが増えて分からなくなるのは、読む力ではなく地図がない問題
  • AIに構成図（Mermaid）を描かせて、1枚にまとめる
  • 「推測で補完しない」を必ず指示に入れる
  • 図は「知らないファイル → 矢印が集中する箇所 → 想像との食い違い」の順で見る
  • Next.js の page.tsx など入口のファイルは矢印が来なくても正常
  • 5ファイル増えたら1回、くらいの頻度でOK

面談なしで、今日から始められます

この講座は 未経験から Next.js + Supabase + Claude Code で Webアプリを公開するまで を全20セッションで体系化した教材付きプランです。無料相談を挟まず、申し込んだその日から教材で学習を始められます。AIが学習パートナーになって何度でも質問でき、つまずいた所だけチャットで直接サポートします。

  • 今日から始める（教材完全版＋月5,500円・チャット質問し放題・いつでも解約OK）→ https://menta.work/plan/20251?ref=menta-knowledge
  • いきなりは不安な方へ：無料の教材体験版もあります（最初の数セッション分）→ プラン詳細をご覧ください