architecture-map

アーキテクチャマップ

リポジトリを歩き回れる場所に変えます。実際のサブシステムを実際の規模に合わせて表した建物、コードに存在する呼び出し経路を示す線、アプリが実際に送信するペイロードを表す動く点で構成された、アイソメトリックな街です。

唯一のルール

文章、グループ、フローは人が作成します。数、網羅率、形状は測定します。

スキャナーにはサブシステムの目的は判断できず、人間にはファイル数を正確に保ち続けることはできません。このページの優れた性質はすべて、この原則から導かれます。「未マッピングのファイル」に意味があるのは、人間が残りのファイルを特定している場合だけなので、ページが古びないという点もそのひとつです。

作成する部分を機械的に生成しようとしないでください。コードを読み、その内容について書いてください。それがこの作業であり、これがコード生成スクリプトではなくスキルである理由です。

始める前に

references/authoring.md を読んでください。文体、アーキタイプの用語、良いノード説明と悪いノード説明の具体例が記載されています。フットプリントやエッジの経路を手動で調整する必要がある場合にのみ、references/geometry.md を読んでください。

ステップ 1 — 検出する

リポジトリを調べて、以下に答えてください。質問する必要はありません。

質問	確認する場所
フレームワークとルーター	package.json、app/ と pages/ と src/routes/ の有無、vite.config、next.config、remix.config
デザイントークン	--* カスタムプロパティがあるグローバルスタイルシート、tailwind.config、tokens／theme モジュール
ダークモードの仕組み	.dark クラス、[data-theme]、または prefers-color-scheme
テストランナー	package.json のスクリプト、vitest.config、jest.config
パッケージマネージャー	ロックファイル
モノレポ	workspaces、pnpm-workspace.yaml、turbo.json
既存のマップ	以前の architecture.config.json。存在する場合は更新です

次に、提案スクリプトを実行し、構成の概略を確認してください。このファイルと同じ場所にあり、マッピング対象のリポジトリ内にはありません。まずパスを解決してください。

SKILL_DIR — このファイルが読み込まれたときにハーネスから通知された、この SKILL.md を含むディレクトリの絶対パスです。ツールごとに異なります（~/.claude/skills/architecture-map、~/.codex/skills/architecture-map、~/.agents/skills/architecture-map、プラグインキャッシュ、またはプロジェクトローカルの .claude/skills/…）。環境変数に頼らず、実際のパスに置き換えてください。

node "$SKILL_DIR/scripts/propose-coverage.mjs" --root . --target 22

ディレクトリークラスターごとのファイル数と行数に加え、推奨グループが返されます。これは回答ではなく下書きとして扱ってください。コードがどこにあるかは分かっても、何をするかは分かりません。

ステップ 2 — ちょうど 4 つの質問をする

質問はまとめて行ってください。ハーネスに構造化された質問の呼び出し機能がある場合はそれを使い（Claude Code では AskUserQuestion）、ない場合は番号付きのメッセージを 1 つだけ送ってください。その後は中断せずに作業してください。質問を 1 つずつ小出しにしないでください。

1. どこに配置しますか？ /~/architecture を推奨します。~ セグメントは「内部ツール」を意味し、実際のルートから離れて並びます。/architecture と /internal/architecture も提示してください。
2. どの範囲を対象にしますか？ リポジトリ全体／ソースのみ／1 つのパッケージから選びます。モノレポの場合は適切な候補をあらかじめ選択してください。
3. デザインシステム。 検出内容を伝えてください（例：「CSS カスタムプロパティを使った Tailwind v4」）。既存のものを使うか、同梱のニュートラルパレットを使うかを提示してください。
4. 追加機能。 CI に鮮度チェックを組み込みますか？ 同期を predev／prebuild に追加しますか？ バージョン履歴のドロップダウンを含めますか？

ステップ 3 — コアを導入する

$SKILL_DIR/assets/core/、assets/stores/、assets/components/ を、合意したパスの下（例：src/architecture/）にリポジトリへコピーしてください。React 以外の依存関係はなく、strict モードで型チェックできます。

次に、リポジトリのルートに architecture.config.json を作成します。

{
  "coverage": "src/architecture/coverage.json",
  "output": "src/architecture/measured.generated.ts",
  "sources": ["src/**/*.{ts,tsx}", "scripts/**/*.mjs"],
  "ignore": ["next-env.d.ts"]
}

$SKILL_DIR/scripts/architecture-sync.mjs をリポジトリ内の scripts/ にコピーし、以下を追加してください。 "architecture:sync": "node scripts/architecture-sync.mjs"。

テーマを調整する

components/theme.ts のみを編集します。各セマンティック名がリポジトリのトークンを参照するようにします。

export const paint = {
  surface: 'var(--tsc-background)',
  border: 'var(--tsc-foreground-tertiary)',
  accent: 'var(--tsc-brand)',
  // …
}

リポジトリにデザインシステムがない場合は、デフォルトのままにします。デフォルトは --am-* のフォールバックを定義しており、単独で動作します。ホストのトークンを参照するのは、このファイル以外では絶対に避けてください。

Step 4 — グラフを作成する

ここが本番です。core/types.ts の型を使い、GROUPS、NODES、EDGES、FLOWS、INTRO をエクスポートする graph.ts を作成します。

グループ — 4〜7 個の近隣領域を、チーム内で使われている呼び方で命名します。「Entry & control」「The pixel pipeline」「Outside world」のようにします。「utils」や「lib」は避けます。

ノード — 15〜25 個を目安にします。各ノードについて、実際のファイルを読み、次の内容を記述します。

• whatItDoes — 平易な言葉で、専門用語を使わずに 1〜2 文で説明します
• howItsBuilt — 依存関係の一覧ではなく、興味深い設計上の判断を記述します
• role — フローのキャプションに使う短い名詞句。「the session gate」のようにします
• files — 読者が開ける実在のパスを指定します

core/layout.ts を使って archetype、params、height、footprint を導き出します。

const { archetype, params } = deriveArchetype(measure)
const height = deriveHeight(measure)
const footprints = packLayout(inputs, GROUPS.map((g) => g.id))

人がすでに調整した footprint があれば、手書きの値を維持します。マージでは作成済みの値が優先されます。

エッジ — 実際の呼び出しとデータの経路のみを示します。その呼び出しを行うコードを示せない場合は、線を引かないでください。経路が建物を横切ってしまう場合は、via のウェイポイントを追加します。

フロー — それぞれエッジ ID の順序付きリストとペイロード名を持つフローを 3〜6 個作成します。フローはページの動詞であり、新規ユーザーが最初に操作するものです。実際の経路をたどって見つけます。たとえば、サインイン、主要な作成／読み取りのループ、負荷の高いバックグラウンドジョブなどです。

カバレッジ — coverage.json を作成し、すべてのソースファイルが一度だけ割り当てられるようにします。$ で始まるキーは注記です。親ディレクトリよりもネストしたディレクトリを優先する必要がある場合は、priority を使います。次に、以下を実行します。

node scripts/architecture-sync.mjs

未マッピングがゼロになるまで、または残ったものが本当にシステムの一部ではないと判断できるまで、反復します。

Step 5 — マウントする

検出されたフレームワーク用のルートを作成します。references/frameworks.md を参照してください。keyframes.css を一度だけインポートします。グラフモジュールから ArchitectureData を渡し、生成ファイルから UNCLAIMED を渡します。

ルートが公開される場合は robots: noindex を追加します。これはリンクで共有するツールであり、検索結果に表示するものではありません。

Step 6 — 検証し、誠実に伝える

1. 型チェックと lint を実行します。
2. node scripts/architecture-sync.mjs --check を実行します。成功する必要があります。
3. アプリを起動して、実際に確認します。スクリーンショットを撮ります。建物が重なっていないこと、エッジが建物の正面を横切っていないこと、すべてのフローが最初から最後まで再生されること、レールとマップで点灯箇所が一致していることを確認します。
4. リポジトリに 2 つのテーマがある場合は、両方を確認します。

そのうえで、ユーザーに率直に伝えます。

幾何形状と測定値は正確です。これらは導出されています。**文章は初稿です。**コードは読みましたが、「このサブシステムが何をするか」の説明は、1 回の作業では最も不十分になりやすい部分です。graph.ts を編集してください。それ以外を変更する必要はありません。

自信に満ちたマップの陰に、平凡な文章を残したままにせず、そのことを伝えてください。

既存マップの更新

architecture.config.json が存在する場合は、更新作業です。作成済みの内容を決して上書きしないでください。

1. sync を実行します。新しい数値は生成ファイルに反映され、それ以外は変更されません。
2. UNCLAIMED を読みます。各項目は、マップにまだ記載されていないサブシステムか、既存モジュールのパターンが狭すぎるものです。
3. 本当に新しいサブシステムの場合は、導出したジオメトリと草案の文章を含むノードを追加し、coverage.json を拡張します。既存のすべてのノードの文章、フットプリント、エッジはそのままにします。
4. 追加した内容と変更しなかった内容を報告します。

規模

建物が約 25 個を超えると、マップは読みにくくなります。提案ツールは、最小の兄弟ノードを、より広い glob を所有する親ノードにまとめます。分割の網羅性は維持され、描画だけが簡略化されます。リポジトリに本当にそれ以上必要な場合は、すべてを縮小するのではなく、パッケージごとにマップを作成します。

やってはいけないこと

• コード内の呼び出しまでたどれないエッジを描かないでください。
• 説明文を等幅フォントにしないでください。等幅フォントはコードとパスに使います。
• ホストリポジトリの Button や Dropdown をインポートしないでください。マップには専用のものが用意されています。
• ファイル数を手書きしないでください。ファイル数の確認はスキャナーに任せてください。
• もっともらしいフローをでっち上げないでください。ソースをたどって確認できないフローは、ページが自信満々に語る嘘です。