cartography

カートグラフィースキル

階層的なコードマップを作成して、ユーザーがリポジトリを理解し、マッピングできるよう支援します。

使用する場面

• ユーザーがリポジトリの理解やマッピングを求めている場合
• ユーザーがコードベースのドキュメント作成を求めている場合
• 不慣れなコードベースで作業を始める場合

ワークフロー

ステップ 1: 既存の状態を確認する

まず、リポジトリのルートに .slim/cartography.json が存在するか確認します。

存在する場合：ステップ 3（変更の検出）に進みます。再初期化する必要はありません。

存在しない場合：ステップ 2（初期化）に進みます。

ステップ 2: 初期化する（状態が存在しない場合のみ）

1. リポジトリの構造を分析する - ファイルを一覧表示し、ディレクトリを把握します
2. パターンを推測し、対象に含めるのはコアコード／設定ファイルのみとします。
   • 含める：src/**/*.ts、package.json など
   • 除外（必須）：テスト、ドキュメント、翻訳は含めないでください。
     • テスト：**/*.test.ts、**/*.spec.ts、tests/**、__tests__/**
     • ドキュメント：docs/**、*.md（必要な場合を除き、ルートの README.md は対象外）、LICENSE
     • ビルド／依存関係：node_modules/**、dist/**、build/**、*.min.js
   • .gitignore を自動的に尊重します
3. cartographer.py init を実行します：

python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py init \
  --root ./ \
  --include "src/**/*.ts" \
  --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"

これにより、次のものが作成されます。

• .slim/cartography.json - 変更検出用のファイルおよびフォルダーのハッシュ
• 関連するすべてのサブディレクトリに空の codemap.md ファイル

4. Explorer エージェントに委任します - フォルダーごとに Explorer を 1 つ起動し、コードを読み取って、担当する codemap.md ファイルに内容を記入させます。

ステップ 3: 変更を検出する（状態がすでに存在する場合）

1. cartographer.py changes を実行して変更を確認します。

python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py changes \
  --root ./

2. 出力を確認します - 次の項目が表示されます。

   • 追加されたファイル
   • 削除されたファイル
   • 変更されたファイル
   • 影響を受けるフォルダー

3. 影響を受けるコードマップのみを更新します - 影響を受けるフォルダーごとに Explorer を 1 つ起動し、該当する codemap.md を更新させます。

4. update を実行して新しい状態を保存します。

python3 ~/.config/opencode/skills/cartography/scripts/cartographer.py update \
  --root ./

ステップ 4: リポジトリアトラスを仕上げる（ルートコードマップ）

各ディレクトリのマッピングが完了したら、Orchestrator がルートの codemap.md を作成または更新する必要があります。このファイルは、リポジトリに入るエージェントや人間のためのマスターエントリーポイントとして機能します。

1. ルートアセットをマッピングする：ルート階層のファイル（例：package.json、index.ts、plugin.json）と、プロジェクト全体の目的を記述します。
2. サブマップを集約する：「Repository Directory Map」セクションを作成します。codemap.md がある各フォルダーについて、責務の概要を抜き出し、ルートマップの表またはリストに含めます。
3. 相互参照を追加する：エージェントが関連する詳細に直接移動できるよう、ルートマップにサブマップへの絶対パスまたは相対パスを記載します。

コードマップの内容

このワークフローでは、Explorer に codemap.md ファイルへの書き込み権限が付与されます。実装を記述する際は、正確な技術用語を使用してください。

• 責務 - 標準的なソフトウェアエンジニアリング用語（「サービス層」、「データアクセスオブジェクト」、「ミドルウェア」など）を用いて、このディレクトリの具体的な役割を定義します。
• デザインパターン - 使用されている具体的なパターン（「オブザーバー」、「シングルトン」、「ファクトリー」、「ストラテジー」など）を特定し、名称を示します。抽象化とインターフェースについて詳しく記述します。
• データと制御のフロー - データがどのようにモジュールに入り、どのように出ていくかを明確にたどります。具体的な関数呼び出しの順序と状態遷移について記述します。
• 統合ポイント - 依存関係と利用側のモジュールを列挙します。フック、イベント、API エンドポイントには技術的な名称を使用します。

コードマップの例：

# src/agents/

## Responsibility
Defines agent personalities and manages their configuration lifecycle.

## Design
Each agent is a prompt + permission set. Config system uses:
- Default prompts (orchestrator.ts, explorer.ts, etc.)
- User overrides from ~/.config/opencode/oh-my-opencode-slim.json
- Permission wildcards for skill/MCP access control

## Flow
1. Plugin loads → calls getAgentConfigs()
2. Reads user config preset
3. Merges defaults with overrides
4. Applies permission rules (wildcard expansion)
5. Returns agent configs to OpenCode

## Integration
- Consumed by: Main plugin (src/index.ts)
- Depends on: Config loader, skills registry

**ルートコードマップ（アトラス）**の例：

# Repository Atlas: oh-my-opencode-slim

## Project Responsibility
A high-performance, low-latency agent orchestration plugin for OpenCode, focusing on specialized sub-agent delegation and background task management.

## System Entry Points
- `src/index.ts`: Plugin initialization and OpenCode integration.
- `package.json`: Dependency manifest and build scripts.
- `oh-my-opencode-slim.json`: User configuration schema.

## Directory Map (Aggregated)
| Directory | Responsibility Summary | Detailed Map |
|-----------|------------------------|--------------|
| `src/agents/` | Defines agent personalities (Orchestrator, Explorer) and manages model routing. | [View Map](src/agents/codemap.md) |
| `src/features/` | Core logic for tmux integration, background task spawning, and session state. | [View Map](src/features/codemap.md) |
| `src/config/` | Implements the configuration loading pipeline and environment variable injection. | [View Map](src/config/codemap.md) |