System Atlas

見て回れるアイソメトリックの構成アトラスを HTML で作ります。

skill の情報

参考: SKILL.md 全文

System Atlas Skill

アトラスは 1 つのデータファイル（data.mjs）で、そこから 2 つのビューを描き出します。1 つは操作できるアイソメトリックの地図です（自己完結した 1 枚の atlas.html。ホバーで読み、クリックで固定し、中に入ると手順が見え、流れるデータパケットを調べられ、章ごとに構造物を数個ずつ見せてシステムを明かしていきます）。もう 1 つは生成されるテキスト版（SYSTEM.md）で、判断の表、すべての構造物、フロー、未解決の質問を ID つきで載せます。人が編集するのはデータファイルだけで、両方のビューはそこから作り直されます。横には手書きの用語集（CONTEXT.md）と ADR を置きます。

できること: 段階的に見せる操作可能な構成図、フィードバックの回をまたいだ質問の追跡、生成されるテキスト版、繰り返せる更新の流れ。 しないこと: 一度きりの静的な図（architecture-diagram か excalidraw の skill を使います）、README だけで足りる完成済みのシステム、PR 用の図 1 枚。

こんなときに使います

誰かが構成を図で話し合いたい、設計したい、レビューしたい、説明したいときに使います。たとえば「アトラスを作って」「システムを地図にして」「構成を見て回れるようにして」「コードベース／エージェント／パイプラインを図にして話し合えるようにして」「クリックして回れる図がほしい」「全体がどうつながるのか案内して」といった依頼です。構成の議論から未解決の質問が山のように出て、フィードバックの回をまたいで追いかける必要があるときにも使います。判断が変わったあとに既存のアトラスを更新するのにも使えます。いちばん向いているのは、システムがまだ新しく、用語も判断も質問も動いていて、フィードバックが 1 回では終わらない場合です。

事前に必要なもの

• Node.js（最近のバージョンなら何でもかまいません。ビルドは node:fs, node:path, node:url しか使わないので、npm install は要りません）。
• 確認用の静的サーバー（npx serve か python3 -m http.server）。

実行のしかた

mkdir -p <atlas home>/atlas
cp <skill>/assets/{template.html,build.mjs} <atlas home>/atlas/
cp <skill>/assets/data.example.mjs <atlas home>/atlas/data.mjs   # then fill it in
node <atlas home>/atlas/build.mjs   # writes ../SYSTEM.md and ../atlas.html

データファイルの各フィールドの説明は、すべて assets/data.example.mjs にあります。

早見表

手順

この順番を守ってください。どの手順も、最初のときに受けた指摘から生まれたものです。

1. 描く前に材料を読みます。 ビジョンを書いた文書、リポジトリにすでにある入口、それにユーザーが許す範囲の先行事例です（許可を聞いてください。ブランチや情報源を禁じられることがあります）。フレームワークの上に作るなら、先にそのドキュメントを読みます。長いドキュメントは delegate_task でサブエージェントに渡し、具体的な設計上の問いを添えて、注意点と「それが与えてくれないもの」の一覧つきの入門メモを返してもらいます。これを飛ばして描くと、実在する何にも対応しない箱ができあがります。
2. 描く前に話し合います。 チャットで構造を提案し、ランタイムの実際の基本要素に対応づけます。質問するのは、リポジトリから導けないことだけにします。残りは既定値を採り、どれを既定にしたかを伝えます。
3. 最初のアトラスはシステム全体です。 assets/ をアトラスの置き場にコピーし（data.example.mjs は data.mjs に名前を変えます）、データを埋めて node でビルドし、公開します。アトラスの置き場は、そのリポジトリのドキュメント方針で決まります。何かをコミットする前に聞いてください。ドキュメントを受け入れるリポジトリなら、ツリー内の docs/{system}/atlas/ です。ADR と CONTEXT.md しかコミットしないリポジトリなら、アトラス、SYSTEM.md、research/ は git で無視されるスクラッチ用ディレクトリに置き、公開したら SYSTEM.md と調査結果を仕様の issue に添付します（一式をまとめてコミットしたら、3,900 行のドキュメント PR になり、同じ設計を 3 通りに言い直した箇所をすり合わせるのにレビューが 4 往復かかったことがあります）。HTML 成果物の作り方の指針がほしければ、skill_view で design-md か architecture-diagram の skill を読み込みます。どちらにしても、見た目の決まりは references/design-language.md で読みます。
4. 段階的に見せます。 システム全体を一度に見せると雑音にしか見えません。章は 10 前後にします。各章で足す構造物は 3 つまでにし、すでに見せた構造物だけを通る小さなフローを 1 つ流します。最後の章ではすべてを見せ、フローを選べるようにします。まだ見せていない構造物も索引には残し、薄く表示して章番号を添えます。パネルは要約を先に出します。1 文を置き、*Read more* と *Steps* は折りたたみます。
5. 形とラベル。 箱に文字を載せるだけでは足りません。役割ごとに形を決め、各構造物の下に読める名前のラベルをキャンバス上に置きます。design-language を見てください。
6. テキスト版。 CONTEXT.md は用語集で、それ以外のものは入れません（名詞を 1 行ずつ）。ADR は、覆しにくく、背景を知らないと意外に見え、本当のトレードオフの末に決めた判断にだけ書きます。この 2 つがツリー内に置くものです。SYSTEM.md は生成物で、research/ には根拠を置きます。どちらもアトラスと同じ場所（手順 3 のとおり、スクラッチ用ディレクトリか docs/）に置きます。頼まれない限り issue は立てません。
7. フィードバックは質問 ID で受けます。 質問はすべて Q-<code><n> の形で、状態を持ちます。未解決（文字列）、解決済み {q, r}（回答と日付）、引き継ぎ {q, to}（名前のある次の手順に渡したもの）のどれかです。ユーザーの言葉をそのまま記録します。「それは質問じゃない」と言われたら外します。「これがわからない」と言われたら、解決済みにする*前に*具体例で説明します。1 回のやり取りが終わるたびに、ビルドし直し、公開し直し、メモリを更新します。
8. 掘り下げ調査の結果を戻します。 サブエージェント（delegate_task）での調査は、共通の指示書 1 つをもとに行います（こちらが持つインターフェース、候補を分ける要件、コストを見積もるための利用モデル、決まった成果物の形）。コストと適合度をそろえた表で総括を書きます。解決した内容は {q, r: '… (from the deep dive, date)'} の形でデータに取り込みます。ユーザーが提案を却下したら、*すべての*ファイルを洗って書き直します。古くなった節の上に注意書きを載せるだけでは足りません。
9. 最新に保ちます。 正本は 1 つ、変更のたびにビルドし直して公開し直し、生成されたファイルは決して手で直さず、ドキュメントのフォルダにはファイル一式を説明する README.md を置きます（表は references/process-and-lessons.md にあります）。

公開

atlas.html は自己完結した 1 ファイルです。ビルド手順は要らず、Google Fonts のスタイルシート以外に外部の素材もありません。フォルダを好きな静的サーバー（npx serve, python3 -m http.server）で配信して URL を渡すか、コミットしたファイルをリポジトリのページホスティングに配信させます。URL は 1 つにし、データを変えるたびに公開し直します。2 つ目のコピーは作りません。公開 URL を固定しておくなら、META.artifactUrl に書いておくと SYSTEM.md からリンクされます。

つまずきやすいところ

• <!doctype html> を先頭に、<meta charset="utf-8"> をその直後に置いてください。そうしないと互換モードになり、矢印が文字化けします。
• 描画部は描くたびに場面全体を作り直します。ホバーのハンドラーに余計な render() が紛れ込むと、カーソルの下の要素が外れ、ブラウザーがクリックを発生させなくなります。スクリーンショットでは地図が完璧に見えるのに、何も反応しない状態になります。
• アプリ内ブラウザーの中には file:// を静的なスナップショットとして描くものがあります。ディスクから開くのではなく、静的サーバー経由で確かめてください。
• 質問は決して削除しません。解決済みにするか、外したと記録して、ID が変わらないようにします。
• 判断のたびに、出力を grep して古い言葉（pending、古いモデル名、却下された設計）が残っていないか探します。読む人はすべてを読みます。
• 大きな HTML/JS をシェルのヒアドキュメントで書くと壊れやすいです。write_file を使い、データ部分は JSON にシリアライズできる形に保ちます。

確認

• node <atlas home>/atlas/build.mjs が終了コード 0 で終わり、SYSTEM.md と atlas.html の両方を書き出すこと。
• ビルドされたスクリプトの構文を確かめ（new Function(js)）、配信したページを実際のブラウザーで 1280×800 程度で開くこと。最初の章、途中の章、最後の章、中に入ったビュー、ライトテーマを見ます。
• 構造物をクリックし、パネルに pinned と出て *Go inside* が選べることを確かめること。パケットの点をクリックし、中身が開くことを確かめること。
• どの構造物にも one、what、how、short ラベル、役割の kind、それに質問があること。まだ実在しない構造物には印がついていること。章があり、章ごとにフローがあり、最後の章がシステム全体であること。
• SYSTEM.md に、判断の表、ID と状態つきの質問の索引、「このファイルの保守のしかた」のフッターがあること。
• プロジェクトのメモリに、アトラスの URL、ドキュメントのパス、日付つきの確定した判断、ユーザーが却下したものとその理由、次の一手が記録されていること。