floorplan

フロアプラン

コードベースのルートに floorplan/ を作成します。初めて見る人がシステム図のように読める、アプリのフロアプランです。各カードには人が読める名前と1行の説明が表示され、その下に実際のパスが小さく表示されます。

• 作成するもの： architecture.json（サブシステム、モジュール、フロー）と descriptions/*.json（すべてのファイルとルートの名前と説明）。
• 生成されるもの： graph.json と index.html。

スクリプトが機械的な作業を担います。リポジトリの検出、インポートとルートの解析、HTTP 呼び出しとエンドポイントの照合、レイアウトとレンダリングです。あなたの役割は、コードを読む人にしかできない部分、つまり、各要素が「何であるか」を判断し、わかりやすく説明することです。

既存のマップ：!node ${CLAUDE_SKILL_DIR}/scripts/status.mjs || true 引数：$ARGUMENTS

マップがすでにある場合は、新規作成せずに更新してください

上記のステータスに既存のマップが表示された場合は、最初からやり直さないでください。次を実行します。

node ${CLAUDE_SKILL_DIR}/scripts/refresh.mjs <root>

再スキャンし、前回のビルドとコンテンツのフィンガープリントを比較して、トークンを消費することなく記録を整理します。

• 移動または名前変更されたファイルやエンドポイントの説明を引き継ぎます。
• 削除されたファイルのエントリを削除します。
• エクスポートまたはルートが変更されたエントリに review メモを付けて示します（関数本体内の編集は対象外です）。
• 再ビルドします。
• 変更内容と短い NEXT リストを出力します。

NEXT の指示に従って作業してください。

• 「unassigned」に追加された新しいディレクトリの glob を追加します。
• describe.mjs（ステップ6）を実行します。これにより、新規項目と要確認項目のワークシートのみが生成されます。
• 変更が大きい場合は、モジュールの概要とフローを確認します。

数時間作業した後の典型的な更新では、ワークシートの項目は数件です。その後、最近の作業を記録し（ステップ7）、表示して報告します（ステップ8）。変更がなくても、必ず表示してください。ユーザーはフロアプランを見たいと依頼しています。

ワークフロー（初回実行）

コードベースのルートには、指定されていれば引数を、指定されていなければ現在のディレクトリを使います。単一のリポジトリの場合も、複数のリポジトリ（フロントエンド + バックエンド + インフラなど）を含む通常のフォルダーの場合もあります。スキャナーはその下にあるすべての Git リポジトリを検出し、重複するワークツリーはスキップします。

1. スキャンします。 node ${CLAUDE_SKILL_DIR}/scripts/scan.mjs <root> floorplan/.cache/scan.json を書き込み、概要を出力します。概要には、リポジトリ、LOC を含むコードツリー、エントリーポイント、ディレクトリ間のインポートで特に多いエッジ、リポジトリをまたぐ HTTP 呼び出しとルートのマッチ、外部パッケージとホストが含まれます。概要をもとに作業してください。容量が大きいため、scan.json は読まないでください。

2. 仕様を読みます。 references/schema.md（architecture.json の形式）と references/choosing-boundaries.md（コードベースを適切なマップに分割する方法）を読みます。

3. 必要な範囲だけ調査します。 README、マニフェスト（package.json、pyproject、go.mod、docker-compose、デプロイ設定）、エントリーポイントを読み、候補となるサブシステムごとに1～2個のファイルにざっと目を通し、それぞれを1文で要約できるようにします。目的はシステムの全体像を把握することであり、コードレビューではありません。

4. floorplan/architecture.json を作成します。 次を目安にしてください。

   • トップレベルノードは3～9個。
   • 大きなノードの下には、それぞれ子ノードを3～12個。
   • コードファイルの90%超をカバーする glob。
   • コードが実際に接続するデータベースとサードパーティーサービスの外部ノード。
   • スキャンでは検出できないもの（キュー、cron、Webhook、環境変数で設定された URL を介するサービス間呼び出し）に限ったエッジ。
   • システムの主な役割を説明するフローを1～3個。
   • 「Start here」ツアー（下記参照）のための tour。案内付きの立ち寄り先を3～8か所設定します。

   すべてのノードに summary が必要です。 対象読者。 このマップを開く人は、通常、アプリの所有者です。多くは、AI を使ってアプリを作った、技術に詳しくない開発者です。ユーザーから開発者向けのマップを求められない限り、"audience" は未設定のままにするか、"everyone" に設定してください。また、すべての project.summary、ノードの label／summary、ファイル／ルートの説明は平易な言葉で書いてください（references/writing-descriptions.md の「平易な言葉」を参照）。「Shop API (Flask)」ではなく、「メインサーバー」のような短いラベルを使ってください。パスとメソッド／URL はカードに表示されるため、説明ではそのものの用途だけを述べれば十分です。

   ツアー。 "tour": [{ "node": "<node id or file path>", "title": "…", "note": "…" }] を追加し、初めて見る人が確認するとよい順番で立ち寄り先を並べます。順番は、アプリの概要、ユーザーが使うアプリ、メインサーバー、外部サービス、そして重要な画面のファイルで締めくくります。コードを読んだことがない人にもわかる平易な言葉でタイトルとメモを書いてください。最初のガイド付きフローは「実際のリクエストをたどる」として末尾に自動で追加されます。ツアーがない場合は、ノードの概要と最初のフローからツアーが作成されるため、適切な概要と少なくとも 1 つのフローが重要です。

5. ビルドして修正する。 node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> すべてを検証し、問題ごとに内容を示します（「…のことですか」、ディレクトリによって割り当てられていないファイル、曖昧な glob など）。修正して再ビルドし、エラーがなく、未割り当ての割合が約 10% 未満になるまで繰り返します。

   Floorplan が生成するものは、コミットされません。 floorplan/ にはフォルダー全体を無視する独自の .gitignore があるため、プロジェクトの追跡対象ファイルには影響しません。すでに Git がこのフォルダー内のファイルを追跡している場合、ビルド時に追跡を解除するための git rm -r --cached コマンドが表示されます。実行せず、そのコマンドをユーザーに伝えてください。

   各ビルドでは、プロジェクトの CLAUDE.local.md に短いマーク付きブロックも保持されます。これは Claude Code の個人用・未コミットのプロジェクトメモで、CLAUDE.md と同様にセッション開始時に読み込まれます。このブロックは、今後の Claude Code セッションにマップの存在と floorplan/query.mjs を使った検索方法を伝え、コードを一から検索するのではなく、マップを出発点にできるようにします。ビルドでは CLAUDE.local.md をリポジトリのローカル除外リスト（.gitignore ではなく .git/info/exclude）に追加します。書き換えるのはこのブロックだけです。以前のバージョンがブロックを CLAUDE.md に追加していた場合は、そこから移動します。無効にするには、--no-claude-md を渡すか、CLAUDE.local.md に `` を記述します。

6. すべてのファイルとルートを説明する。 node ${CLAUDE_SKILL_DIR}/scripts/describe.mjs <root> モジュールごとにワークシート（floorplan/.cache/worksheets/<key>.md）と、記入用のひな形（floorplan/descriptions/<key>.json）を 1 つずつ作成します。各ワークシートには、すべてのファイルの要約（ドキュメント文字列、定義、使用するものと使用される箇所）と、すべてのルートの情報（ハンドラー、ドキュメント文字列）が含まれています。これらの情報だけで、ほとんどのファイルは開かずに説明できます。

   • 最初に references/writing-descriptions.md を読んでください。
   • ファイルが約 150 個を超える場合： 並列サブエージェントが使える場合は、ワークシートを分担してください。各サブエージェントが担当するのは約 100～150 個のファイルとし、エリア別（バックエンドのルート、サービス、スクリプト、テスト、UI）にまとめます。それぞれにワークシートのキー、コードベースのルート、執筆ガイドを渡し、自分が担当する descriptions/<key>.json ファイルのみを編集し、キーは変更しないよう伝えてください。
   • 小規模なコードベースの場合： 自分で行ってください。

   次に再ビルドします。ビルドでは DESCRIPTIONS files X/Y · routes X/Y と報告されます。どちらも 100% にしてください。describe.mjs を再実行すると、未対応の項目だけが一覧表示されます。

7. 最近の作業をマークします。 マップでは、直近で作業した内容が強調表示されます。該当するカードには緑色の「変更済み」／「新規」タグが付き、それらを含む部分には「N 件変更」と表示されます。ホバーするとメモが表示され、最近の作業ボタンを押すと、該当カードが1つのボードにまとめて表示されます。以前の強調表示は上書きされるため、作成時も更新時も必ず実行してください。 node ${CLAUDE_SKILL_DIR}/scripts/recent.mjs <root> 前回のマップ以降の変更、未コミットの変更、最近のコミットが一覧表示され、それぞれが該当するカードに対応付けられます。理由はあなたが記入します。

   • 対象となる作業。 この会話であなたまたはサブエージェントが行った作業が主な情報源です。把握している内容を活用してください。このセッションで何も作業していない場合（新しいセッションの場合）は、recent.mjs に表示される、作業中であることが明らかな内容、つまり未コミットの変更と最新のコミットを使います。何もなければ、{ "tasks": [] } と記述して、以前の強調表示をクリアします。
   • floorplan/recent-work.json を作成します。 ユーザーが依頼した作業ごとに1つのタスクを記述します。各タスクには、title（2～5語）、request（依頼内容をユーザーの言葉で短く記述）、summary（削除したものも含め、依頼に対して行った作業と現在の状況を1～2文で記述します。削除したファイルは強調表示できないためです）を含めます。次に items を追加し、変更されたカードをファイルパス、ノード ID、または "METHOD /path" で指定します。それぞれに change（"new" または "changed"）と note を含めます。
   • すべてのメモで「これは依頼とどう関係するのか」に答えます。 どのカードに何の変更を加えたか、また依頼の達成にその変更がなぜ必要だったかを、平易な文で1～2文にまとめます。たとえば、「アドレスがいったん変数に組み立てられるウェブリクエストも検出するようになりました。そのため、注文画面と在庫画面でサーバー呼び出しが表示されなかった問題が解消されます。」と記述します。「flattenTemplates と variableUse ヘルパーを追加しました」のようには記述しません。
   • 重要な箇所を強調します。 この依頼によって動作が変わったファイルやエンドポイントを選びます。通常は3～15件です。テストや付随的な編集は、それ自体が依頼の対象でない限り省略します。変更されたエンドポイントがある場合は、そのファイルとエンドポイントの両方を記載できます。
   • 対象読者が開発者でない限り、コード内の用語は使わないでください。 メモにシークレットを記載してはいけません。

   形式：references/schema.md#recent-work。その後、build.mjs を実行します。RECENT WORK N card(s) highlighted と表示され、マップにない参照があれば警告されます。

8. 表示してから報告します。 フロアプランを作成または更新したときは、必ず最後にユーザーが見られる状態にします。 node ${CLAUDE_SKILL_DIR}/scripts/open.mjs <root>

   • マップのサーバーをバックグラウンドで起動します（または、このマップ用にすでに実行中のサーバーを再利用します）。その後、ブラウザーでマップを開きます。すでに開いているタブがある場合は、新しいタブを開かずにそのタブを再読み込みします。
   • URL、Ask が利用可能かどうか（Claude Code CLI が見つかったかどうか）、サーバーの停止方法が表示されます。最後のタブを閉じてから数時間後に、サーバーも自動的に停止します。
   • アプリ内ブラウザーやプレビューツールがある場合は、--no-open を指定し、表示された URL をそのツールで開いてください。会話のすぐ横にマップが表示されます。
   • リモート環境またはヘッドレス環境のため、ユーザーが 127.0.0.1 にアクセスできない場合は、open.mjs を実行せず、ユーザー自身のマシンで node floorplan/serve.mjs を実行するよう案内するか、Claude アプリを使う方法（ステップ9）を提案してください。 その後、報告してください。 URL を伝え、把握したアーキテクチャをユーザーの言語で 3～5 行で説明し、意外な点があれば含めます。循環、巨大なファイル、使われていない領域、密結合したサブシステムなどです。重大度が高い Health 項目（graph.health。ビルド出力と graph.json に一覧表示されます）は必ず伝えてください。ハードコードされたパスワードやキー、誰でもデータを変更できるエンドポイントは、プロジェクトの所有者に伝える必要があります。シークレットの値は決して繰り返さないでください。architecture.json と descriptions/ はユーザー自身で編集できること、作業を進めた後は「フロアプランを更新して」と頼むだけで、変更された箇所だけが再読み込みされることを伝えてください。スラッシュコマンドではなく、平易な言葉で伝えます。プラグインとしてインストールされている場合、コマンドは /floorplan:floorplan、個人スキルとしてインストールされている場合は /floorplan です。初回実行時は、今後のセッション用のマップとメモ（CLAUDE.local.md 内）が git.md の対象外となり、今後のセッションでマップが使用されることを 1 行で伝えてください。更新時は、依頼に対して何が変わったかから始めてください（Recent work の下で強調表示されています）。

9. マップを開いて質問する

マップにはフローティングの質問バーがあります。ユーザーが質問を入力すると、Claude はテキストと回答ボードで答えます。回答ボードには、関連するカード、それらのつながり、各カードのメモ、任意のステップごとの解説が含まれます。利用方法は 2 通りあります。どちらの場合も UI は同じです。

• Claude Code CLI（推奨）。 マップのサーバー（floorplan/serve.mjs。手順 8 で open.mjs が起動します）は、http://127.0.0.1:4378 または次に空いているポートでマップを配信します。各質問では、読み取り専用ツール（floorplan/query.mjs 経由のマップと、ソースに対する Read／Grep／Glob）を使って、ユーザーのコードベース内で claude CLI を実行するため、回答で実際のコードを引用できます。スクリプトは PATH または ~/.local/bin 内の claude を探します。--claude <path> で場所を指定でき、--model <name> でモデルを選択できます（open.mjs は両方を引き継ぎます）。ユーザーはいつでも node floorplan/serve.mjs を自分で実行でき、バックグラウンドで動作しているサーバーは node floorplan/serve.mjs --stop で停止できます。

• Claude アプリ。 Claude アプリで実行している場合（Artifact ツールが利用可能な場合）は、マップを公開して、そこで開き、ユーザー自身の Claude アカウントで質問できるようにすることを提案してください。この場合、回答の情報源はマップのみ（名前、説明、つながり、エンドポイント）で、ソースは参照されません。また、質問バーには、より快適に使うため CLI をインストールするよう案内が表示されます。公開するには、次の手順を行います。

  1. node ${CLAUDE_SKILL_DIR}/scripts/build.mjs <root> --artifact。これにより、マシンの絶対パスを含まない floorplan/artifact.html が作成されます。
  2. Artifact ツールでそのファイルを公開します。capabilities: {"sample": {}} を指定し、URL が変わらないよう、以降の公開でも同じファイルパスを使ってください。
  3. 更新のたびに --artifact を指定して再ビルドし、再公開します。

  公開すると、ソースコードではなく、マップ（パス、名前、説明、構造）がユーザーの非公開 claude.ai アカウントにアップロードされます。公開する前にそのことを伝えてください。

• どちらも使わない場合： floorplan/index.html は引き続きブラウザーで直接開けます。質問バーに必要な設定が表示されます。

ほかにもマップが自動で表示する情報

• ヘルス。 重要な問題の件数が表示されたヘッダーボタンを押すと、スキャンで見つかった問題を平易な言葉でまとめたリストが開きます。

  • コード内やコミット済みの .env に書き込まれたパスワードや API キー。
  • サインインせずに誰でもデータを変更または読み取れるエンドポイント（ルート行より上にサインインチェックが置かれている場合も含みます）。
  • どこからも使われていないファイル。
  • AI が安全に編集するのに苦労する、約1,000行を超えるファイル。

  各問題には Show on map（該当するファイルとエンドポイントを注記付きで強調表示）と Fix with Claude（正確なファイル名と行番号、安全な修正方法を示す、すぐに貼り付けられるプロンプト）があります。スキャンとビルドの際に scripts/lib/health.mjs で計算され、秘密の値は保存せず、ファイル名、行番号、マスクされたヒントのみを保存します。これは手軽な自動チェックであり、セキュリティ監査ではありません。

• 画面。 ビルド時に scripts/lib/screens.mjs でアプリの画面（Next.js、React Router、Vue、SvelteKit、Remix、Nuxt、Astro、Expo、Angular、TanStack）を検出します。各画面の背後にあるもの、つまり、そのコンポーネント、送信するリクエスト、それに応答するサーバーコードとデータ、外部サービスも特定します。Screens ボタンを使うと、利用者が知っているページから操作を始められます。

• ここから始めましょう。 初回表示時に1分間のツアーが始まり、ヘッダーから再生することもできます。tour を使うか、ツアーがない場合は自動で作成します。

• 標準では平易な言葉で表示。 接続の種類は「Uses」「Web requests」「Background jobs」と表示されます。一般的な技術用語には下線が引かれ、ホバーすると説明が表示されます。Filters → Show technical detail を切り替えると、開発者向けの用語が表示され、エクスポートも確認できます。

Flows → Request a new flow を使うと、「返金はどのように顧客のカードに返されますか？」のような内容を Claude にたどらせ、手順ごとのフローを作成することもできます。serve.mjs を使う場合、これらは floorplan/custom-flows.json に保存され、ビルドのたびにマップに取り込まれます（削除されたコードを指すステップは警告とともに除外されます）。このファイルはユーザーコンテンツとして扱ってください。更新時も保持し、依頼がない限り編集しないでください。

注記

• パスはコードベースのルートからの相対パスで、スラッシュ / を使います。複数リポジトリのルートでは、api-service/src/** のようにリポジトリのフォルダーから始まります。
• 説明のルートキーは、ワークシートに表示されるとおりの "METHOD /full/path" です。
• ビューアーはレイアウトエンジン（ELK）とフォントを CDN から読み込みます。オフラインで出力を動作させるには、elk.bundled.js（elkjs 0.9.x）を ${CLAUDE_SKILL_DIR}/assets/vendor/ に配置すると、ビルド時にインライン化されます。
• HTTP のエッジは、呼び出し箇所にある URL 文字列（変数に事前に保持された URL、ネストされたテンプレート文字列、パスのプレフィックスを追加する同一ファイル内の小さなヘルパーを含みます）と、ルート定義（Flask、FastAPI、Express、Next.js、Spring、Go など）を照合して作成されます。Blueprint やルーターのプレフィックスは解決され、ネストされたマウントも含まれます。これは有力なヒントとして扱ってください。重要なサービス間リンクが欠けている場合は、明示的なエッジとして追加してください。
• graph.json や index.html を手動で編集しないでください。ビルドのたびに再生成されます。