はじめに

Xで、Claude Code時代のWeb開発にもかなり応用できそうな投稿が流れてきました。

参考投稿：

Dave Jeffery氏のX投稿「Ask Claude to document and describe the main flows in your app」

元の投稿はアプリを題材にしていますが、この発想はWeb開発でもかなり有効です。

むしろ、Webサービスの方が効果が出やすい場面も多いと思います。

理由は、Webサービスでは以下のような要素が複雑に絡むからです。

ルーティング
画面遷移
API呼び出し
認証状態
権限制御
Feature Flag
ABテスト
フォーム入力
検索条件
決済フロー
管理画面
BFF
SSR / CSR
キャッシュ
リダイレクト

React、Next.js、Vue、Nuxt、Rails、Laravel、Node.js、BFF構成のWebサービスでは、処理フローが見えづらくなりがちです。

そこでClaude Codeにコードベースを読ませ、Webサービス内の主要な処理フローをHTML + JSONで可視化させる、という使い方が実務的です。

実際に紹介されていたプロンプト

Dave Jeffery氏が返信で公開していた実際のプロンプトは、以下です。

Create a single page html that documents workflows between packages and components in the app. Have all the components/packages on the page and I can click on different actions like "Invite new user" or "todesktop build" or {insert other flows here} and then it will highlight the flow between the packages and annotate how things are passed between each package to complete the action. This should be driven from a JSON document which documents all the flows. Does that make sense? Any questions?

かなりシンプルです。

このプロンプトの本質は、単にドキュメントを書かせることではありません。

コードベースを読ませたうえで、処理フローを人間にもAIにも再利用しやすい形へ変換させることです。

Web開発向けに言い換えると

Web開発向けに言い換えるなら、以下のようなプロンプトになります。

このWebサービス内の主要な処理フローを解析し、ページ、コンポーネント、API、状態管理、認証、権限制御の関係を可視化する単一ページHTMLを作成してください。

HTML上には、主要なページ、コンポーネント、API、状態管理、バックエンド連携を表示してください。

ユーザーが「ログイン」「検索」「商品詳細表示」「カート追加」「クーポン適用」「購入」「会員登録」「管理画面更新」などのアクションをクリックすると、その処理を完了するまでに通るページ、コンポーネント、API、状態管理、バックエンド処理をハイライトしてください。

また、各処理間で渡されるデータ、呼び出される関数、利用されるAPI、状態の変化、権限チェック、リダイレクトを注釈として表示してください。

このHTMLは、すべてのフロー情報を記述したJSONドキュメントを元に描画する構成にしてください。

まずコードベースを確認し、実装上確認できる内容に基づいて作成してください。
推測が必要な箇所は unknown と明記してください。

この依頼内容で意味は通じますか？
不明点があれば質問してください。

重要なのは、最後に「不明点があれば質問してください」と入れている点です。

Webサービスの処理フローは、プロジェクトによって構成が大きく違います。

Next.jsならApp RouterなのかPages Routerなのか、API Routesを使っているのか、BFFが別にあるのか、認証はNextAuthなのか独自実装なのか、状態管理はReduxなのかZustandなのか、GraphQLなのかRESTなのかで、解析すべき観点が変わります。

そのため、Claude Codeに最初から一方的に作業させるより、曖昧な点を先に質問させた方が出力品質は安定しやすいです。

何を作らせるのか

作らせるものは、静的な設計書ではありません。

Webサービスの処理フローを可視化する、インタラクティブなHTMLです。

画面上には、ページ、コンポーネント、API、状態管理、バックエンド処理などが表示されます。

そして、たとえば「検索」「ログイン」「購入」「フォーム送信」「管理画面更新」などのアクションをクリックすると、その処理がどこを通るのかがハイライトされます。

たとえばECサイトなら、以下のような流れです。

検索フォーム
↓
検索結果ページ
↓
検索API
↓
商品詳細ページ
↓
カート追加API
↓
カート状態更新
↓
購入画面
↓
決済API
↓
購入完了ページ

この流れをHTML上でクリック操作できるようにし、各ステップで何が渡されているかを注釈として表示します。

これができると、Webサービスの仕様を「文章で読む」のではなく、「処理フローとして見る」ことができます。

HTMLだけでなくJSONも重要

この発想で特に重要なのは、HTMLだけでなくJSONも作らせる点です。

HTMLは人間向けです。

エンジニア、PdM、ディレクター、QA、CS、ビジネス担当が、Webサービスの流れを理解するために使えます。

一方で、JSONはAI向けです。

LLMに渡すことで、新機能開発、バグ修正、影響範囲分析、テスト生成に再利用できます。

たとえば、以下のようなJSONです。

{
  "flows": [
    {
      "name": "Purchase flow",
      "steps": [
        {
          "type": "page",
          "name": "SearchPage",
          "route": "/search",
          "action": "input keyword",
          "passes": ["keyword", "filters"]
        },
        {
          "type": "api",
          "name": "SearchAPI",
          "endpoint": "/api/search",
          "action": "fetch search results",
          "passes": ["keyword", "filters", "page"]
        },
        {
          "type": "page",
          "name": "ProductDetailPage",
          "route": "/products/[id]",
          "action": "display product detail",
          "passes": ["productId"]
        },
        {
          "type": "api",
          "name": "CartAPI",
          "endpoint": "/api/cart",
          "action": "add item to cart",
          "passes": ["productId", "quantity", "userId"]
        },
        {
          "type": "page",
          "name": "CheckoutPage",
          "route": "/checkout",
          "action": "start checkout",
          "passes": ["cartId", "couponCode", "paymentMethod"]
        }
      ]
    }
  ]
}

このようなJSONがあると、AIはWebサービスの処理フローを構造として扱えます。

自然言語の仕様書だけだと、AIは毎回文章を読み直して解釈する必要があります。

しかしJSONであれば、route、page、component、api、state、passesといった単位で処理できます。

これはClaude Codeに後続作業を依頼するときにかなり効きます。

新機能開発でどう使えるか

Web開発では、新機能追加時に既存フローの理解がボトルネックになりやすいです。

たとえば、ECサイトに「クーポン適用機能」を追加する場合、単に画面に入力欄を増やせば終わりではありません。

検索、商品詳細、カート、購入画面、決済、購入完了、マイページ、メール通知、管理画面などに影響する可能性があります。

HTML + JSONで既存フローが整理されていれば、Claude Codeに以下のように聞けます。

このJSONフローを前提に、クーポン適用機能を追加する場合に影響を受けるページ、コンポーネント、API、状態管理、バックエンド処理を洗い出してください。

これにより、最初からコードベース全体を手探りで読むのではなく、既存フローを起点に影響範囲を確認できます。

特に、長年運用されているWebサービスでは、仕様がコードに埋もれていることが多いです。

その場合、Claude Codeで一度フローをJSON化しておくと、後続の調査がかなり楽になります。

バグ修正でどう使えるか

バグ修正でも有効です。

たとえば、以下のようなバグがあったとします。

クーポンコードを入力して購入したが、購入完了画面では割引後金額になっているのに、注文履歴では割引前金額になっている

この場合、問題はフロントエンドの表示なのか、購入APIなのか、注文履歴APIなのか、DB保存なのか、キャッシュなのかを切り分ける必要があります。

JSON化されたフローがあれば、Claude Codeに以下のように聞けます。

Purchase flowで、購入完了画面では割引後金額が表示されるが、注文履歴では割引前金額が表示される場合、どのstepに問題がある可能性が高いですか？

AIは、購入フローと注文履歴フローの差分を見ながら、怪しい箇所を絞り込めます。

もちろん、最終的には人間がコードとログを確認する必要があります。

ただし、初動調査で見るべきページ、API、状態、DB更新箇所を絞れるだけでも価値があります。

QAやE2Eテストにも使える

HTML + JSONで処理フローを可視化できると、QAやE2Eテストにも使えます。

Webサービスでは、重要導線のテストが抜けやすくなります。

特に、ログイン状態、未ログイン状態、会員ランク、クーポン、キャンペーン、Feature Flag、ABテストが絡むと、テストパターンが急に増えます。

JSONに処理フローが整理されていれば、Claude Codeに以下のように依頼できます。

このJSONフローを元に、Playwrightで購入フローのE2Eテストケースを作成してください。
ログイン済み、未ログイン、クーポンあり、クーポンなしのパターンを含めてください。

また、QA観点では以下のような依頼もできます。

このJSONフローを元に、購入フローでテストすべき観点を洗い出してください。
認証、権限、金額計算、在庫、クーポン、リダイレクト、エラー表示を含めてください。

Web開発では、仕様書と実装とテストケースがズレることがあります。

コードベースからClaude Codeにフローを抽出させれば、少なくとも「現在の実装に近いフロー」を起点にQA設計できます。

ビジネス担当にも価値がある

この仕組みは、Webエンジニアだけのものではありません。

PdM、ディレクター、マーケティング、CS、営業、事業責任者にも価値があります。

Webサービスでは、ビジネス側から以下のような質問がよく出ます。

このキャンペーンLPから購入完了まで、どの導線を通っていますか？

このクーポンは、どの画面で適用されていますか？

ログイン前とログイン後で、表示が変わる箇所はどこですか？

このAPIを変更すると、どのページに影響しますか？

このフォーム項目は、最終的にどこに保存されていますか？

こうした質問に対して、毎回エンジニアがコードを読んで説明するのは負荷が高いです。

しかし、HTMLで処理フローが可視化されていれば、非エンジニアでも大まかな流れを理解できます。

さらにJSONがあれば、AIに質問できます。

つまり、Webサービスの仕様を「詳しい人に聞かないとわからない状態」から、「AIに聞ける状態」へ近づけられます。

これは、開発効率だけでなく、ビジネス側の意思決定速度にも影響します。

電子書籍ストアWebで考えると相性が良い

電子書籍ストアWebのようなサービスでは、この考え方はかなり相性が良いです。

たとえば、以下のような導線があります。

検索
検索結果
作品詳細
無料試し読み
ログイン
会員登録
カート
クーポン適用
決済
購入完了
本棚
ビューア起動
キャンペーンLP
レコメンド
ランキング
お気に入り

これらは単独で存在しているわけではありません。

検索条件、ログイン状態、購入済み状態、クーポン条件、キャンペーン条件、端末種別、会員属性などによって、表示や遷移が変わります。

このようなWebサービスでは、Claude Codeに以下のようなプロンプトを投げる価値があります。

電子書籍ストアWebの主要な処理フローを解析し、単一ページHTMLとして可視化してください。

HTML上には、主要なページ、コンポーネント、API、状態管理、認証、権限制御、キャンペーン判定、クーポン判定を表示してください。

ユーザーが「検索」「作品詳細表示」「無料試し読み」「ログイン」「会員登録」「カート追加」「クーポン適用」「決済」「購入完了」「本棚追加」「ビューア起動」「キャンペーンLPからの購入」などのアクションをクリックすると、その処理を完了するまでに通るページ、コンポーネント、API、状態管理、バックエンド処理をハイライトしてください。

また、各処理間で渡されるデータ、呼び出される関数、利用されるAPI、状態の変化、リダイレクト、エラー分岐を注釈として表示してください。

このHTMLは、すべてのフロー情報を記述したJSONドキュメントを元に描画する構成にしてください。

まずコードベースを確認し、実装上確認できる内容に基づいて作成してください。
推測が必要な箇所は unknown と明記してください。

この依頼内容で意味は通じますか？
不明点があれば質問してください。

この粒度で作れると、エンジニアだけでなく、PdM、ディレクター、QAにも使える資料になります。

Next.jsで特に効く理由

Next.jsのようなWebフレームワークでは、この可視化は特に効果があります。

理由は、ページ、コンポーネント、API、サーバー処理、クライアント状態が混在しやすいからです。

App Routerでは、server component、client component、server actions、route handlers、middleware、layout、loading、error boundaryなどが絡みます。

コードを見慣れている人でも、処理フロー全体を一度に把握するのは簡単ではありません。

Claude Codeに以下の観点で整理させると、かなり見通しがよくなります。

route
page
layout
server component
client component
server action
route handler
middleware
API call
state
redirect
error handling
cache
revalidate

特に、認証や権限制御がmiddleware、server component、API側に分散している場合、HTML + JSONで流れを可視化する価値は大きいです。

より短く試すなら

最初から完璧なプロンプトを書く必要はありません。

まず試すなら、以下の程度でもよいと思います。

このWebサービスの主要な処理フローを解析し、ページ、コンポーネント、API、状態管理の関係を可視化する単一ページHTMLを作成してください。

各フローはJSONで定義し、HTMLはそのJSONを元に描画してください。

アクションをクリックすると、その処理を完了するまでに通るページ、コンポーネント、API、関数、渡されるデータをハイライトしてください。

不明点があれば、作業前に質問してください。

これだけでも、コードベースを読める環境であれば十分に試せます。

重要なのは、最初から全フローを完璧に可視化しようとしないことです。

まずは、ログイン、検索、購入、フォーム送信、管理画面更新など、重要な1フローだけで試すのがよいです。

シンプルなプロンプトでも成立する理由

今回の面白い点は、プロンプト自体がかなりシンプルなことです。

昔のAI活用では、長いプロンプトを書き、細かく条件を指定し、出力形式を厳密に定義することが重要でした。

もちろん今でも出力形式の指定は重要です。

ただし、Claude Codeのようにコードベースを読める環境では、コードそのものが強力なコンテキストになります。

つまり、重要なのはプロンプトの長さではありません。

重要なのは、AIが読みやすいコードベースになっているかです。

責務分離、命名、ディレクトリ構成、型定義、API層、状態管理、ルーティングが整理されているほど、Claude Codeは処理フローを理解しやすくなります。

逆に、巨大なコンポーネント、暗黙の状態、命名の崩壊、依存循環、場当たり的なAPI呼び出しが多いコードベースでは、同じプロンプトでも精度は落ちます。

これは、プロンプトエンジニアリングだけでは解決しにくい問題です。

これからは、AIが理解しやすいコードベース設計も重要になります。

これはドキュメント生成ではなく、AI時代のWebシステムマップ生成

この投稿を単なる「Claude Codeにドキュメントを書かせる話」と捉えると、少し浅いです。

本質は、Webサービスの処理フローをAIが再利用可能な形に変換することです。

HTMLは人間が見るためのシステムマップです。

JSONはAIが再利用するための構造化データです。

この2つをセットで作ることで、Webサービスの知識を、人間にもAIにも扱いやすくできます。

今後のWeb開発では、以下のような流れが増えるはずです。

コードベース
↓
Claude Codeが解析
↓
HTMLで可視化
↓
JSONで構造化
↓
新機能開発・バグ修正・QA・影響範囲分析で再利用

これは、ドキュメントを作るためのAI活用ではありません。

開発チームが、AIと一緒にWebサービスを理解し続けるための仕組みです。

まとめ

Dave Jeffery氏の投稿は、短いプロンプトの紹介でした。

しかし、その中身はWeb開発にもかなり応用できます。

重要なのは、単一ページHTMLで人間が処理フローを理解し、JSONでAIが処理フローを再利用できるようにする点です。

Webサービスでは、ルーティング、API、状態管理、認証、権限制御、Feature Flag、ABテスト、決済、フォーム、管理画面などが複雑に絡みます。

そのため、コードベースからClaude Codeに処理フローを抽出させ、HTML + JSONとして可視化する価値は大きいです。

これからのWeb開発では、AIにコードを書かせるだけでなく、AIにコードベースを理解させることが重要になります。

そのためには、コードをそのまま読ませるだけでなく、HTMLやJSONのような中間成果物を作り、チームとAIの両方が使える形にしていく必要があります。

特に、導線が複雑で、仕様が属人化しやすく、影響範囲調査に時間がかかるWebサービスほど、この発想は効きます。

Claude Codeを使っているWeb開発チームなら、まずは主要フロー1つだけでもHTML + JSON化してみる価値があります。