codemap

Codemap スキル

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

使用するタイミング

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

ワークフロー

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

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

存在しない場合は、レガシー状態の .slim/cartography.json を確認します。

レガシー状態が存在する場合：.slim/cartography.json を .slim/codemap.json に移動してから、変更の検出に進みます。

.slim/codemap.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. codemap.mjs init を実行します（scripts/codemap.mjs はこのスキルのベースディレクトリからの相対パスです。ホストはこれを Base directory for this skill として出力します）。

node scripts/codemap.mjs init \
  --root ./ \
  --include "src/**/*.ts" \
  --exclude "**/*.test.ts" --exclude "dist/**" --exclude "node_modules/**"

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

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

4. Codemap の作成を Fixer エージェントに委任します - フォルダーごとに 1 つの Fixer を起動し、コードを読み取って、担当フォルダーの codemap.md ファイルを作成または更新します。

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

1. 変更内容を確認するため、codemap.mjs changes を実行します。

node scripts/codemap.mjs changes \
  --root ./

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

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

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

4. 新しい状態を保存するため、update を実行します。

node scripts/codemap.mjs 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 エンドポイントには技術的な名称を使用します。

テンプレート例：

# src/<dir>/
## Responsibility
<role of this directory>
## Design
<patterns and abstractions>
## Flow
<data in → key calls → data out>
## Integration
<consumers / dependencies>

ルートの atlas では、同じ見出しに加えて、次のディレクトリマップの表を作成してください。

ディレクトリ	責務	リンク
src/<dir>/		マップを表示