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. 相互参照を設定する：エージェントが該当する詳細に直接移動できるよう、ルートマップにサブマップへの絶対パスまたは相対パスを記載します。

ステップ 5：AGENTS.md にコードマップを登録する

OpenCode は、すべてのセッションで AGENTS.md をエージェントのコンテキストに自動読み込みします。 エージェントがコードマップを自動的に見つけて利用できるようにするには、リポジトリのルートにある AGENTS.md を更新（または作成）します：

1. AGENTS.md がすでに存在し、## Repository Map セクションも含まれている場合は、このステップをスキップします。参照はすでに設定されています。
2. AGENTS.md は存在するものの、## Repository Map セクションがない場合は、以下のセクションを追記します。
3. AGENTS.md が存在しない場合は、以下のセクションを含めて作成します。

## Repository Map

A full codemap is available at `codemap.md` in the project root.

Before working on any task, read `codemap.md` to understand:
- Project architecture and entry points
- Directory responsibilities and design patterns
- Data flow and integration points between modules

For deep work on a specific folder, also read that folder's `codemap.md`.

これは冪等です。カートグラフィーを繰り返し実行しても、既存のセクションを検出してスキップするため、重複しません。

Codemap の内容

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

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

codemap の例：

# 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

**ルート codemap（Atlas）**の例：

# 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) |