system-atlas

System Atlas

アトラスは1つのデータファイルから、インタラクティブなアイソメトリックマップ（単体で完結する1つのHTMLファイル）と、生成されたテキスト版（決定事項の表、すべての構造、フロー、ID付きの未解決の質問を含むSYSTEM.md）という2つのビューを描画します。編集するのはデータファイルだけです。両方のビューはそこから再生成されます。データファイルは、手書きの用語集（CONTEXT.md）とADRの隣に置かれます。

この形式を採用する理由は、アーキテクチャの議論では、1つのドキュメントに収まりきらない速さで決定事項、質問、用語が生まれ、議論相手はシステムを読むのではなく、見たいと思っているからです。マップは相手のため、テキスト版はリポジトリと次回の自分のため、単一の情報源は2つのビューの整合性を保つためのものです。

このスキルは、1回の長い設計セッションと数回のフィードバックを通じて、実際のエージェントアーキテクチャのアトラスを構築した経験からまとめられました。そのセッションでユーザーから受けた修正内容が、以下のルールになっています。経緯についてはreferences/process-and-lessons.mdをご覧ください。

いつ使うか — いつ使わないか

システムがまだ新しく、用語、決定事項、質問が変化しており、フィードバックを複数回行う場合に使います。完成済みのシステムにREADMEだけが必要な場合や、PR内の図が1つだけ必要な場合には使わないでください。

プロセス

順序どおりに進めてください。各ステップは、最初の試行で受けた修正を踏まえたものです。

1. 描画する前に入力情報を読む。 ビジョンドキュメント、リポジトリにすでに存在する要素、そしてユーザーが許可する既存事例を確認します（確認してください。ブランチや情報源を禁止している場合があります）。フレームワークをベースに構築する場合は、まずそのドキュメントを読みます。長いドキュメントは、具体的な設計上の質問とともにサブエージェントに渡し、注意点と「このフレームワークで実現できないこと」のリストを含む入門資料を作成してもらいます。こうした確認をせずに描画すると、実在するものに対応しない箱ができあがります。
2. 描画する前に話し合う。 ランタイムの実際のプリミティブに対応づけた構造案をチャットで提示し、リポジトリから導き出せないことだけを質問します。それ以外はデフォルトを採用し、どのデフォルトを選んだか伝えます。質問は通常のチャットテキストで行います。
3. 最初のアトラス — システム全体。 assets/ をアトラスの配置先にコピーし（template.html、build.mjs、data.example.mjs の名前をそれぞれ data.mjs に変更して）、データを入力し、ビルドして公開します。アトラスの配置先は、リポジトリのドキュメントポリシーによって異なります。 設計ドキュメントを自由にコミットするリポジトリでは、ツリー内の docs/<system>/atlas/ が適切です。一方、ADR と CONTEXT.md のみを意図的にコミットし、仕様や根拠資料は課題管理システムに置くリポジトリでは、アトラス、SYSTEM.md、research/ を git の無視対象となる一時ディレクトリに配置します。仕様の公開時に SYSTEM.md と根拠資料をコメントとして仕様の課題に添付し、ツリー内には docs/<system>/adr/ と docs/<system>/CONTEXT.md のみを残します。何かをコミットする前に、どちらのポリシーが適用されるか確認してください。身をもって学びました。すべてをコミットした結果、3,900 行に及ぶドキュメントの PR と、1 つの設計を 3 通りに言い換えた内容をすり合わせる 4 回のレビューが発生しました。ADR と用語集だけにすれば、整合性を保つべき場所は 1 か所だけです。エージェントに HTML 成果物向けの設計ガイダンススキルがある場合は、テンプレートに手を加える前に読み込みます。いずれの場合も、視覚的なルールについては references/design-language.md を読みます。
4. 段階的に情報を開示する。 システム全体を一度に見せると雑然とします（最初の修正では「読み解きにくい」と指摘されました）。章は 10 章程度とし、各章で追加する構造は最大 3 つにします。また、そこで初めて明かされた構造だけに触れる小さなフローを 1 つ実行します。最後の章ではフロー選択機能とともにすべてを表示します。まだ明かしていない構造は目次に残し、暗く表示して章番号を付けます。パネルは要約を先に表示します。まず 1 文を示し、その後に 続きを読む と 手順 を折りたたんで表示します。
5. 形状とラベル。 箱に文字を付けるだけでは不十分です（2 回目の修正では「箱の形状とラベルを改善する」と指摘されました）。役割ごとに形状を変え、各構造の下のキャンバス上に読みやすい名前ラベルを配置します。デザインガイドを参照してください。
6. テキスト版も用意する。 CONTEXT.md は用語集のみとします（ドメインモデル形式で、名詞を 1 行ずつ記載します）。ADR は、覆すのが難しく、背景なしでは意外に感じられ、実際のトレードオフの結果である決定だけに使用します。この 2 つをツリー内のファイルとします。SYSTEM.md は生成ファイルで、research/ には根拠資料を格納します。どちらもアトラスと同じ場所（一時ディレクトリまたは docs/。手順 3 を参照）に置きます。依頼されない限り、課題を作成しないでください。
7. 質問 ID でフィードバックを管理する。 質問にはすべて Q-<code><n> という ID を付け、状態を設定します。状態は、未解決（文字列）、解決済み {q, r}（回答と日付）、または次の詳細調査など、名前付きの次のステップに引き継いだ {q, to} です。ユーザーの言葉を記録します。「これは質問ではない」と言われたら削除します。「よく分からない」と言われたら、解決済みにする前に具体例を使って説明します。各ラウンドの後に、再ビルドして再公開し、メモリを更新します。
8. 詳細調査の結果を反映する。 共通のブリーフ（こちらが担当するインターフェース、候補を区別する要件、コストの使用モデル、固定の成果物形式）に基づき、サブエージェントを使って調査します。正規化したコスト／適合性グリッドを含む統合結果を作成します。解決内容を {q, r: '… (from the deep dive, date)'} としてデータに反映します。ユーザーが提案を却下した場合は、すべてのファイルを確認して書き換えます。古いセクションを残したまま先頭に告知を追加するだけでは不十分です。ユーザーは必ず気づきます。
9. 常に最新の状態に保つ。 「アトラスは私にとってすばらしい。でも、最新でなければ意味がありません」。情報源は 1 つに統一し、変更のたびに再ビルドして再公開します。生成ファイルを手作業で編集してはいけません。また、ドキュメントフォルダーには、資料一式を説明する README.md を置きます（手順と教訓の表を参照してください）。

マップの公開

atlas.html は自己完結型の単一ファイルです。ビルド手順は不要で、Google Fonts のスタイルシート以外に外部アセットはありません。利用者が実際に開ける方法で公開してください。

• エージェントからホストされた HTML アーティファクトを公開できる場合は、そこに公開し、再ビルド後も URL を固定してください。META.artifactUrl に設定すると、生成される SYSTEM.md からリンクされます。
• それ以外の場合は、任意の静的サーバー（npx serve、python3 -m http.server）でフォルダーを配信してローカル URL を渡すか、ファイルをコミットし、リポジトリの Pages ホストで配信してください。

どちらの場合もルールは同じです。URL は 1 つにし、データが変更されるたびに再公開してください。コピーを 2 つ作ってはいけません。

完了の条件

• <atlas home>/data.mjs が存在し、編集するソースはこれだけです。bun <atlas home>/build.mjs を実行すると、エラーなく SYSTEM.md と atlas.html が生成されます。
• アトラスは固定 URL で公開されており、データが変更されるたびにその URL で再公開されます。
• すべての構造に one、what、how、short ラベル、役割を示す kind、質問があり、ゴーストには印が付いています。章ごとのフローを含む章があり、最後の章はシステム全体です。
• SYSTEM.md には、決定事項の表、ID と状態を含む質問インデックス、「このファイルのメンテナンス方法」のフッターがあります。
• プロジェクトのメモリには、アトラスの URL、ドキュメントのパス、日付付きで確定した決定事項、ユーザーが却下した内容とその理由、次のステップが記録されています。

公開前の確認

生成したスクリプトを構文チェックし（new Function(js)）、内容を確認してください。フォルダーを静的サーバーで配信し、実際のブラウザーで開きます。一部のアプリ内ブラウザーでは file:// が静的スナップショットとして表示され、フォントが読み込まれない場合があります。サイズを約 1280×800 に変更し、最初の章、中ほどの章、最後の章、内部ビュー、ライトテーマのスクリーンショットを撮ります。<!doctype html> を先頭に置き、その直後に <meta charset="utf-8"> を置いてください。DOCTYPE がないとページは互換モードで表示され、早い位置に charset がないと矢印が文字化けします。構造をクリックして、パネルに ピン留め済み と表示され、内部へ移動 が提示されることを確認します。また、パケットのドットをクリックしてください。このレンダラーは描画のたびにシーン全体を再構築します。そのため、ホバーハンドラーに余計な render() があるとカーソル下の要素が切り離され、ブラウザーはクリックイベントの生成を停止します。スクリーンショットではマップが完璧に見えても、何もクリックに反応しなくなります。決定するたびに、出力に古い用語（pending、以前のモデル名、却下された設計）が残っていないか grep してください。利用者はすべてに目を通します。

このスキルに含まれるファイル

• assets/template.html — アトラスのレンダラー（ビルド時にタイトルと上部ストリップの統計情報を挿入）
• assets/build.mjs — data.mjs → atlas.html + SYSTEM.md
• assets/data.example.mjs — すべてのフィールドの説明を含む最小限のスターター。data.mjs にコピーしてください
• references/design-language.md — レイアウト、パレット、アイソメトリック表現のルール、役割別の形状、ラベル、文章作成のルール、章の作成手順
• references/process-and-lessons.md — 初回セッションの手順、README の表、サブエージェントによる詳細調査のパターン、コストモデルの習慣、つまずきやすい点