はじめに
Xで、かなり実務的なClaude Code活用例が流れてきました。
参考投稿：
Dave Jeffery氏のX投稿「Ask Claude to document and describe the main flows in your app」
投稿の要点は、Claude Codeにアプリ内の主要な処理フローを解析させ、単一ページのHTMLとJSONデータとして出力させる、というものです。
HTMLは人間がアプリの流れを理解するために使えます。
一方で、JSONはLLMに渡すことで、新機能開発やバグ修正時に、アプリ内の処理フローを説明するための材料として使えます。
一見すると、単なる「AIによるドキュメント生成」に見えます。
しかし、実際にはもう少し重要です。
これは、コードベースをClaude Codeに読ませ、アプリの構造や処理フローを、人間にもAIにも理解しやすい形へ変換するという話です。
特に、アプリエンジニア、Webエンジニア、PdM、ディレクター、QA、ビジネス担当にとって、かなり価値があります。
実際に紹介されていたプロンプト
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?
かなりシンプルです。
日本語にすると、以下のような意味になります。
アプリ内のパッケージとコンポーネント間のワークフローをドキュメント化する、単一ページのHTMLを作成してください。
ページ上には、すべてのコンポーネントとパッケージを表示してください。
「Invite new user」や「todesktop build」や「{ここに他のフローを入れる}」のようなアクションをクリックできるようにし、そのアクションを完了するために、どのパッケージ間をどのように処理が流れるのかをハイライトしてください。
また、各パッケージ間で何がどのように渡されているのかを注釈として表示してください。
このHTMLは、すべてのフローを記述したJSONドキュメントによって駆動される構成にしてください。
この依頼内容で意味は通じますか？
不明点があれば質問してください。
重要なのは、最後の一文です。
Does that make sense? Any questions?
Claude Codeに一方的に作業させるのではなく、要求が曖昧であれば、先に質問させる形になっています。
これは実務でかなり重要です。
アプリの構造、package、component、flow、action、JSONの粒度は、コードベースによって違います。
そのため、最初から完璧な指示で押し切るよりも、Claude Code側に「この理解で合っているか」「不足情報はあるか」を確認させた方が、出力品質が安定しやすいです。
何を作らせているのか
このプロンプトで作らせているものは、単なる仕様書ではありません。
より正確には、アプリ内の処理フローを可視化するインタラクティブなHTMLです。
画面上には、アプリ内のpackageやcomponentが並びます。
そして、「Invite new user」「todesktop build」のようなアクションをクリックすると、その処理を完了するまでに、どのpackageやcomponentを通るのかがハイライトされます。
さらに、package間で何が渡されているのか、どの関数が呼ばれるのか、どのデータが次の処理へ渡されるのか、といった情報も注釈として表示されます。
つまり、これは「見て理解するアーキテクチャドキュメント」です。
従来の静的な仕様書とは違い、アクションごとに処理フローをハイライトできる点が重要です。
HTMLだけではなくJSONも出す意味
この投稿で特に重要なのは、HTMLだけでなくJSONも生成させている点です。
HTMLは人間向けです。
エンジニア、PdM、QA、ディレクター、ビジネス担当が見て、アプリの流れを理解するために使えます。
一方で、JSONはAI向けです。
LLMに渡すことで、新機能開発やバグ修正時に、アプリ内の処理フローを説明しやすくなります。
たとえば、以下のようなJSONがあるとします。
{
"flows": [
{
"name": "Invite new user",
"steps": [
{
"package": "UserManagement",
"component": "InviteUserForm",
"action": "submit invite form",
"passes": ["email", "role"]
},
{
"package": "APIClient",
"component": "UserInviteService",
"action": "call invite API",
"passes": ["email", "role", "authToken"]
},
{
"package": "Notification",
"component": "Toast",
"action": "show success message",
"passes": ["resultMessage"]
}
]
}
]
}
このようなJSONがあると、AIは処理の流れを構造として理解できます。
自然言語の仕様書だけだと、AIは毎回読み直して解釈する必要があります。
しかしJSONであれば、flow、package、component、action、passesといった単位で機械的に扱えます。
これにより、後続の作業がかなりやりやすくなります。
新機能開発でどう使えるか
新機能開発では、既存フローの理解が最初のボトルネックになりがちです。
たとえば、アプリに「クーポン適用」や「新しい会員登録導線」を追加する場合、ビジネス担当は要件を理解していても、実装上どの画面、どのAPI、どの状態管理、どのcomponentに影響するかは把握しづらいです。
エンジニア側も、既存実装を追いながら影響範囲を確認する必要があります。
ここでHTML + JSONのフロー図があると、既存フローを前提にした影響範囲の確認がしやすくなります。
たとえばClaude Codeに以下のように依頼できます。
このJSONフローを前提に、クーポン適用機能を追加する場合に影響を受けるpackage、component、API、状態管理を洗い出してください。
これができると、調査の初速がかなり上がります。
最初からコードを全部読むのではなく、既存フローの地図を見ながら、影響範囲を絞り込めるからです。
バグ修正でどう使えるか
バグ修正でも有効です。
たとえば、以下のようなバグがあったとします。
招待メール送信後に成功メッセージは表示されるが、実際にはユーザーが招待されていない
この場合、問題はUIなのか、API呼び出しなのか、レスポンス処理なのか、状態更新なのかを追う必要があります。
JSON化されたフローがあれば、AIにこう聞けます。
Invite new user フローで、成功メッセージが表示されるが実際には招待が完了していない場合、どのstepに問題がある可能性が高いですか？
AIは、フロー上の処理順序を見ながら、怪しい箇所を絞り込めます。
もちろん最終判断は人間がコードを確認する必要があります。
しかし、最初の調査対象を絞るだけでも十分に価値があります。
アプリ開発のビジネス担当にも価値がある
この仕組みは、エンジニアだけのものではありません。
むしろ、ビジネス担当、PdM、ディレクター、QA、CSにも価値があります。
アプリ開発では、よく以下のような会話が発生します。
このキャンペーン導線、どこから入れるんでしたっけ？
この画面から購入完了まで、何ステップありますか？
iOSとWebでログイン後の挙動が違うのは仕様ですか？
このAPI変更、どの画面に影響しますか？
この機能、まだ使われていますか？
こうした問いに対して、毎回エンジニアがコードを読んで説明するのは負荷が高いです。
しかし、HTMLで可視化されたフローがあれば、非エンジニアでも全体像を把握しやすくなります。
さらにJSONがあれば、AIに質問できます。
つまり、アプリの仕様や処理フローを「人に聞かないとわからない状態」から、「AIに聞ける状態」へ近づけられます。
これは、開発生産性だけでなく、ビジネス側の意思決定速度にも影響します。
電子書籍アプリで考えると相性が良い
たとえば電子書籍アプリやストアWebでは、以下のような導線があります。
検索
作品詳細
試し読み
購入
クーポン適用
決済
本棚追加
ビューア起動
ログイン
会員登録
キャンペーン遷移
レコメンド
これらは単独で存在しているわけではありません。
検索結果から作品詳細へ遷移し、作品詳細から試し読みや購入に進み、ログイン状態によって表示が変わり、クーポンやキャンペーン条件によって決済フローも変わります。
このようなアプリでは、フローが複雑化しやすいです。
そのため、Claude Codeに以下のようなプロンプトを投げる価値があります。
アプリ内のパッケージとコンポーネント間のワークフローを可視化する、単一ページのHTMLを作成してください。
ページ上には、主要なパッケージとコンポーネントをすべて表示してください。
ユーザーが「検索」「作品詳細表示」「試し読み」「購入」「クーポン適用」「決済」「本棚追加」「ビューア起動」などのアクションをクリックすると、その処理を完了するまでに、どのパッケージ・コンポーネント間をどのように処理が流れるのかをハイライトしてください。
また、各パッケージ間で渡されるデータ、呼び出される関数、利用されるAPI、状態の変化を注釈として表示してください。
このHTMLは、すべてのフロー情報を記述したJSONドキュメントを元に描画する構成にしてください。
まずコードベースを確認し、実装上確認できる内容に基づいて作成してください。
推測が必要な箇所は unknown と明記してください。
この依頼内容で意味は通じますか？
不明点があれば質問してください。
これは、実務でそのまま試せる粒度です。
より短く試すなら
最初から完璧なプロンプトを書く必要はありません。
まず試すなら、以下のようにシンプルでもよいと思います。
このアプリ内の主要な処理フローを解析し、packageとcomponent間の関係を可視化する単一ページHTMLを作成してください。
各フローはJSONで定義し、HTMLはそのJSONを元に描画してください。
アクションをクリックすると、その処理を完了するまでに通るpackage、component、関数、API、渡されるデータをハイライトしてください。
不明点があれば、作業前に質問してください。
この程度でも、コードベースを読める環境であれば十分に効果があります。
シンプルなプロンプトでも成立する理由
今回の面白い点は、プロンプト自体があまり複雑ではないことです。
昔のAI活用では、長いプロンプトを書き、細かく条件を指定し、出力形式を厳密に定義することが重要でした。
もちろん今でも出力形式の指定は重要です。
ただし、Claude Codeのようにコードベースを読める環境では、コードそのものが強力なコンテキストになります。
つまり、重要なのはプロンプトの長さではありません。
重要なのは、AIが読めるコードベース、理解しやすい設計、追跡しやすい構造です。
コードの責務分離、命名、ディレクトリ構成、型定義、API層、状態管理が整理されているほど、AIはフローを理解しやすくなります。
逆に、巨大なコンポーネント、暗黙の状態、命名の崩壊、依存の循環が多いコードベースでは、同じプロンプトでも精度は落ちます。
これは仕様書生成ではなく、AI時代のシステムマップ生成
この投稿を単なる「Claude Codeに仕様書を書かせる話」と捉えると、少し浅いです。
本質は、アプリの処理フローをAIが再利用可能な形に変換することです。
HTMLは人間が見るための地図です。
JSONはAIが再利用するための構造化データです。
この2つをセットで作ることで、アプリ開発の知識を、人間にもAIにも扱いやすくできます。
今後のアプリ開発では、以下のような流れが増えるはずです。
コードベース
↓
Claude Codeが解析
↓
HTMLで可視化
↓
JSONで構造化
↓
新機能開発・バグ修正・QA・影響範囲分析で再利用
これは、ドキュメントを作るためのAI活用ではありません。
開発チームが、AIと一緒にコードベースを理解し続けるための仕組みです。
まとめ
Dave Jeffery氏の投稿は、かなり短いプロンプトの紹介でした。
しかし、その中身は非常に実務的です。
重要なのは、単一ページHTMLで人間が処理フローを理解し、JSONでAIが処理フローを再利用できるようにする点です。
クリック可能なアクションでpackage/component間の流れを可視化できれば、新機能開発やバグ修正時に、LLMへフローを説明しやすくなります。
これからのアプリ開発では、AIにコードを書かせるだけではなく、AIにコードベースを理解させることが重要になります。
そのためには、コードをそのまま読ませるだけでなく、HTMLやJSONのような中間成果物を作り、チームとAIの両方が使える形にしていく必要があります。
特に画面数が多く、導線が複雑で、仕様が属人化しやすいアプリほど効果が出やすいです。
Claude Codeを使っているチームなら、まずは主要フロー1つだけでもHTML + JSON化してみる価値があります。