omm-scan

omm-scan — 視点ベースのアーキテクチャスキャナー

目的

視点主導の再帰的分析を使用して、コードベースを分析し、アーキテクチャドキュメントを .omm/ に生成します。

• 視点は最上位の要素であり、アーキテクチャを捉える独自の方法です。
• 図の各要素を再帰的に分析します。内部構造がある場合は子要素（独自の図を持つサブディレクトリ）になります。ない場合はリーフのままです。
• ネスト構造はファイルシステムによって決まります。図の要素 ID は子ディレクトリ名と一致します。ビューアーはファイルシステムからグループを解決します。

前提条件

command -v omm || npm install -g oh-my-mermaid

インストールに失敗した場合は、ユーザーに「ターミナルで npm install -g oh-my-mermaid を実行してから、もう一度お試しください」と伝えてください。

---

ステップ 0：言語を確認する

omm config language

フィールドの内容（description、context、constraint、concern、todo、note）は、設定された言語で記述します。デフォルトは英語です。要素 ID、ディレクトリ名、図のノード ID は、常に英語のケバブケースにします。

ステップ 1：コードベースを調査する

Glob と Read を使ってプロジェクトを把握します。

• package.json、pyproject.toml、または同等のマニフェストを読みます
• トップレベルのディレクトリを一覧表示して、モジュールの境界を特定します
• 主要なエントリーポイント（main、index、app ファイル）を読みます
• ルート定義、サービスレイヤー、データベース接続、外部連携を探します

ステップ 2：視点を選択する

以下のカタログから、このコードベースに適した視点を選択します。

視点カタログ

視点	作成するタイミング	明らかにすること
overall-architecture	常に	何が存在し、各要素がどのように関連しているか
request-lifecycle	サーバー/API がある場合	リクエストがどのように受け取られ、最後まで処理されるか
data-flow	データ処理または DB の使用がある場合	データの取得元、変換方法、格納先
dependency-map	モジュールグラフが複雑な場合	何が何に依存し、何が共有されているか
external-integrations	外部 API/サービスがある場合	システムが何に、どのような目的で接続するか
state-transitions	ステートフルな機能（フロントエンドまたはバックエンド）がある場合	状態がどのように変化し、何がそれを引き起こすか
route-page-map	ルーティングを備えたフロントエンドの場合	ページ構造とナビゲーションの流れ
command-surface	CLI ツールの場合	コマンド階層とディスパッチ
extension-points	プラグイン/拡張システムがある場合	拡張アーキテクチャとレジストリ
pipeline	ML/データパイプラインがある場合	ステージの構成とデータフロー
orchestration	イベント駆動/キューシステムがある場合	パブリッシャー、サブスクライバー、ブローカーの構成
storage	2 つ以上のストレージシステムがある場合	ストレージの構成（DB、キャッシュ、キュー、オブジェクトストア）

コードに存在しない視点を無理に選ばないでください。

ステップ 3：再帰的に掘り下げながら視点を生成する

選択した視点ごとに、以下の再帰的な手順に従います。

3a. 視点の図を記述する

要素 ID は子ディレクトリ名と一致させます。ビューアーはファイルシステムからネスト構造を解決します。

omm write <perspective> diagram - <<'MERMAID'
graph LR
    renderer["Renderer\nsrc/renderer/"]
    renderer -->|"IPC invoke/on"| main-process["Main Process\nsrc/main/"]
    main-process -->|"spawn PTY"| engine-system["Engine System\nsrc/main/engine/"]
    main-process -->|"read/write JSON"| data-store["Data Store\nsrc/main/store.ts"]
    main-process -->|"xterm.js"| terminal-dock["Terminal Dock\nsrc/renderer/src/panel/"]
MERMAID

3b. 残りの 6 フィールドを記述する

description、context、constraint、concern、todo、note を、それぞれ個別の omm write コマンドで記述します。

3c. 再帰的に掘り下げる：すべての要素を分析する

図のすべての要素について、以下を行います。

1. 分析する — その要素が表すコードを調べます（関連するファイル/ディレクトリに対して Glob + Read を使用します）。

2. すべてのノードに例外なく description を記述する。 これにより要素ディレクトリが作成されます。必要に応じて、他のフィールド（context、constraint、concern、todo、note）も記述します。設定された言語で記述してください。

   omm write <perspective>/<element-name> description - <<'EOF'
   (what this element does, which files/dirs it covers)
   EOF
   

3. リーフかグループかを判断する：

   • 明確に異なる内部コンポーネントが見つかった場合 → 図を記述し、さらに再帰的に掘り下げます（グループになります）。
   • 意味のあるサブコンポーネントがない場合（単一ファイル、単純なラッパー、外部システム）→ 残りのフィールドのみを記述します（リーフのままです）。

4. グループの場合 — 図を記述し、再帰的に掘り下げます。

   omm write <perspective>/<element-name> diagram - <<'MERMAID'
   graph LR
       (internal elements)
   MERMAID
   

その後、この図の各要素についてステップ 3c を繰り返します。

再帰の例

overall-architecture (perspective)
  elements: renderer, main-process, engine-system, data-store, terminal-dock

  → analyze renderer (src/renderer/)
    → finds: App.tsx, components/, hooks/, stores/, world/
    → group → write diagram with: components, stores, world
      → analyze components → 15 .tsx files, no sub-structure → leaf
      → analyze stores → 4 zustand stores → leaf
      → analyze world → OfficeCanvas + PixiJS logic → leaf

  → analyze main-process (src/main/)
    → finds: ipc.ts, auth/, engine/, terminal-session-service.ts, store.ts
    → group → write diagram with: auth, engine, terminal-session
      → analyze auth → auth-service.ts, callback-server.ts → leaf
      → analyze engine → claude-code.ts, codex.ts → leaf

  → analyze data-store (src/main/store.ts)
    → single file → leaf

  → analyze terminal-dock (src/renderer/src/panel/)
    → TerminalDock.tsx, DockManager → leaf

ステップ 4：要約する

作成/更新した内容を報告し、表示には omm view を使うよう提案します。

図のルール

• 要素 ID は子ディレクトリ名と一致させる必要があります。 ケバブケースを使用します：main-process、data-store、terminal-dock。

• 要素ラベルは 2 行形式にします。名前とファイルパスを \n で区切ります：

  main-process["Main Process\nsrc/main/"]
  auth-service["Auth Service\nsrc/auth/service.ts"]
  

• すべてのエッジに意味のあるラベルを付ける必要があります：A -->|"why this connection exists"| B

• 1 つの図に要素を増やすほど、さらに深く再帰する必要があります。

• ほとんどの図では graph LR を使用し、階層には graph TD を使用します。

• 視覚的な区別が役立つ場合は classDef を使用します：

  スタイル	色	使用する場面
  external	#585b70	コードベース外部のサードパーティサービス
  concern	#f38ba8	既知のリスクまたはボトルネック
  entry	#89b4fa	エントリーポイント（HTTP ハンドラー、CLI、キューコンシューマー）
  store	#a6e3a1	永続ストレージ（DB、キャッシュ、ファイルシステム）

  classDef external fill:#585b70,stroke:#585b70,color:#cdd6f4
  classDef concern fill:#f38ba8,stroke:#f38ba8,color:#1e1e2e
  classDef entry fill:#89b4fa,stroke:#89b4fa,color:#1e1e2e
  classDef store fill:#a6e3a1,stroke:#a6e3a1,color:#1e1e2e
  

一般的なルール

• 各フィールドは個別の omm write コマンドとして記述します。 各 omm write は、それぞれ個別の Bash ツール呼び出しで実行する必要があります。
• 変更されていない要素を書き換えないでください。
• 循環参照を作成しないでください。子要素から親要素を参照してはいけません。