inkboard/system-atlas

何を解決するか

System Atlas は、古くなりがちな静的なアーキテクチャ図の問題を解決します。手動で描いた図はすぐに「嘘」になってしまうため、単一の真実の源（データファイル）を提供し、自動的にインタラクティブな等軸測図のビジュアルマップと構造化されたテキストドキュメント（SYSTEM.md）を生成します。これにより、システムアーキテクチャの視覚的・テキスト的表現が常に一致し、1回の編集で更新可能になります。

動作方法

このツールはデータ駆動型のアプローチでシステムをマッピングします：

1. 単一の真実の源：すべてのシステム構造、フロー、意思決定は data.mjs ファイルに定義されます。
2. 生成：ビルドスクリプト（build.mjs）がこのデータを処理し、2つの出力を生成します：インタラクティブな探索用の自己完結型 atlas.html ファイルと、ドキュメント用の SYSTEM.md ファイル。
3. インタラクティブマップ：生成されたHTMLマップでは、構造にマウスオーバーで内容を表示、クリックでピン留め、実行ステップに深掘りできます。情報過多を防ぐために「プログレッシブディスクロージャーチャプター」を採用し、システムを小さな、管理可能な部分に段階的に提示します。
4. エージェント統合：「エージェントスキル」として設計されており、AIエージェントが自然言語のリクエストに基づいてアトラスの作成・更新・ウォークスルーをトリガーできます。

対象ユーザー

複雑なシステム設計を他者に伝える必要がある開発者やアーキテクト、安定したIDでアーキテクチャ意思決定や未解決の質問を追跡したい人、実際のコードベースと同期されたドキュメントを維持したい人向けです。

特徴

• インタラクティブな等軸測図：ズーム可能・パン可能で、役割ごとに異なる形状（例：ブレイン、ストア、ゲート）を用いたHTMLマップ。
• テキストの双子：自動的に SYSTEM.md ファイルを生成し、意思決定テーブル、フローテーブル、質問インデックスを含みます。
• プログレッシブディスクロージャー：システムをチャプターごとに組織し、構造とデータフローを段階的に提示します。
• 検査可能なデータパケット：実際のリクエストを移動するドットとして可視化し、クリックでJSONペイロードを確認できます。
• 質問追跡：安定したID（Q-<code><n>）を使用して、フィードバックラウンドを通じて未解決・解決済みのアーキテクチャ質問を追跡します。