---
license: "MIT. Translation of the Hermes Agent documentation, Copyright (c) 2025 Nous Research. See https://wiki.winsmux.dev/hermes/licenses.txt"
title: "System Atlas — 見て回れるアイソメトリックの構成アトラスを HTML で作る"
description: "見て回れるアイソメトリックの構成アトラスを HTML で作る"
upstream_path: user-guide/skills/optional/creative/creative-system-atlas.md
upstream_blob: d00b97eef7d6e3b92fae2d84696730c7e231f019
sources:
  - https://hermes-agent.nousresearch.com/docs/user-guide/skills/optional/creative/creative-system-atlas
---

# System Atlas {#system-atlas}

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

## skill の情報 {#skill-metadata}

| | |
|---|---|
| 提供元 | 追加で入れるもの — `hermes skills install official/creative/system-atlas` で導入します |
| パス | `optional-skills/creative/system-atlas` |
| バージョン | `1.0.0` |
| 作者 | Harshyt Goel (adapted by Nous Research) |
| ライセンス | MIT |
| 対応プラットフォーム | linux, macos |
| タグ | `architecture`, `diagrams`, `isometric`, `documentation` |
| 関連 skill | [`architecture-diagram`](/hermes/docs/user-guide/skills/bundled/creative/creative-architecture-diagram/), [`excalidraw`](/hermes/docs/user-guide/skills/optional/creative/creative-excalidraw/) |

## 参考: SKILL.md 全文 {#reference-full-skillmd}

:::info
以下は、この skill が呼び出されたときに Hermes が読み込む skill 定義の全文です。skill が有効なあいだ、エージェントはこれを指示として受け取ります。
:::

# System Atlas Skill {#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 枚。

## こんなときに使います {#when-to-use}

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

## 事前に必要なもの {#prerequisites}

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

## 実行のしかた {#how-to-run}

```bash
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` にあります。

## 早見表 {#quick-reference}

| ファイル | 役割 | 編集するか |
|---|---|---|
| `atlas/data.mjs` | 唯一の正本。構造物、フロー、章、判断、質問、本文 | する |
| `atlas/template.html` + `atlas/build.mjs` | 描画部と生成部 | 見た目だけ |
| `atlas.html` | ビルドされたアトラス。ビルドし直すたびに同じ URL へ公開し直します | しない（生成物） |
| `SYSTEM.md` | ビルドされたテキスト版 | しない（生成物） |
| `CONTEXT.md` | 用語集。名詞 1 つにつき 1 行 | 手で |
| `adr/` | 後から覆しにくい判断 | 手で |
| `research/` | 掘り下げ調査の根拠 | 追記のみ |

## 手順 {#procedure}

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

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` にあります）。

## 公開 {#publishing}

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

## つまずきやすいところ {#pitfalls}

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

## 確認 {#verification}

- `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、ドキュメントのパス、日付つきの確定した判断、ユーザーが却下したものとその理由、次の一手が記録されていること。