map

Map

map エントリーランプを実行しています。既存のコードベースを把握し、architect、triage、verify が機能するための、生きた CONTEXT.md の階層を作成することがあなたの役割です。負債も含め、現状を記録してください。あるべき姿を設計するのはあなたの役割ではありません。それは architect の役割です。

ヘルパースクリプトの実行

このスキルには、独自の scripts/ ディレクトリ（この SKILL.md と一緒にインストールされています）にヘルパースクリプトが含まれています。SKILL_DIR にこのスキルの絶対パスを設定してください。このファイルの末尾に このスキルのベースディレクトリ として表示されています。その後、スクリプトをプロジェクトのルートディレクトリから実行してください（スクリプトはプロジェクトの .changes/ ファイルと CONTEXT.md ファイルを操作します）。

SKILL_DIR="<absolute path to this skill's directory>"

以下の node "$SKILL_DIR/scripts/..." コマンドは、すべてこの設定に依存します。packages/build/ は参照しないでください。このパスはツールキットの開発リポジトリにのみ存在し、インストール済みのスキルには存在しません。

基本姿勢

処方的ではなく、記述的に対応します。コードベースの現状をマッピングしてください。最適でない箇所を見つけた場合：

• Known-soft-spots に記録します。
• そのパターンが重要な基盤である（外部の利用者に依存されている、契約上定められているなど）という強い証拠がない限り、堅さは soft にします。
• ユーザーに変更を勧めないでください。このセッションで作るのはドキュメントであり、リファクタリング計画ではありません。

堅さの判定は慎重に行ってください。迷ったら soft とします。後から firm にするのは簡単ですが、誤って firm とした境界を格下げするのは影響が大きいためです。

インテーク

コンテキストのスキャン、リポジトリの調査、サブエージェントの起動、または参考資料の読み取りを行う前に、目標と観測可能な成果、影響を受ける領域、制約と回避事項、要件が確定しているか、一部確定しているか、未確定かを確認してください。インテークに必要な範囲だけをマッピングします。

フェーズ 1：調査

コンテキストの検出スキャンを実行し、既存の CONTEXT.md ファイルを探します。

node "$SKILL_DIR/scripts/context-discover.mjs"

次に、調査サブエージェントを使ってコードベースの構造を把握します。作業を分担してください。

調査エージェント 1 — システムレベル：

「このコードベースを調査してください。トップレベルのコンポーネントとその責務、主なデータフロー、技術スタック、コンポーネント間の明らかな境界、設定や環境への依存関係を特定してください。構造化した要約を報告してください。」

調査エージェント 2 — ビルドおよびテスト基盤：

「このコードベースを調査してください。ビルド方法、テストの構成と実行方法、使用しているテストフレームワーク、テストカバレッジの状況を特定してください。調査結果を報告してください。」

各トップレベルコンポーネントについて（複数ある場合は並列で実施）：

「 ディレクトリ／モジュールを調査してください。公開インターフェース、内部構造、他のコンポーネントへの依存関係、読み込む設定、明らかな技術的負債や既知の最適でないパターンを特定してください。調査結果を報告してください。」

フェーズ 2：ルート CONTEXT.md

調査結果をもとに、references/templates/CONTEXT.md.tmpl と --root を使用して、ルートの CONTEXT.md の草案を作成します。

重要な判断：

• 境界の堅さ： soft とする方向で判断してください。境界を firm とするのは、公開 API、外部の利用者がいる IPC プロトコル、外部ユーザーがいるファイル形式など、外部との契約がある場合に限ります。
• Known-soft-spots： 率直かつ具体的に記述してください。この項目は将来のエージェントにとって最も価値があり、改善する許可を与えるものです。
• 用語集： 理想的な定義ではなく、コード内で使われているドメイン用語を記録してください。コードベースに登場する名称を使います。
• 技術要件： 根拠のある厳格な制約のみを含めてください。「高速であるべき」は技術要件ではありません。「config/sla.yaml の API 契約に基づき、レイテンシの p99 が 50ms 未満」は技術要件です。

ひな形を作成して内容を埋めます。

node "$SKILL_DIR/scripts/context-scaffold.mjs" --path . --name "<Project Name>" --root

その後、すべてのセクションを埋めてください。コードから明確で外部から観測可能な動作の契約を特定できる場合を除き、Acceptance/Behavioral Criteria は空欄にしておきます。

フェーズ 3：コンポーネントごとの CONTEXT.md ファイル

各トップレベルコンポーネントについて、CONTEXT.md を作成し、内容を記入します：

node "$SKILL_DIR/scripts/context-scaffold.mjs" --path <component-dir> --name "<Component Name>"

探索エージェントのレポートから各フィールドを埋めます。同じ慎重な確度のルールを適用してください。

各コンポーネントについて、次の点を確認します：

• コンポーネントの単一の責務は何ですか？（責務が2つある場合は、Known-soft-spots に記載してください。）
• 他のコンポーネントに対する公開インターフェースは何ですか？
• 何に依存していますか？
• 変更した場合、何が壊れますか？

フェーズ 4：妥当性チェック

サブエージェントを起動します：

"コードベースの分析に基づいて作成された CONTEXT.md ファイルをレビューしています。各 CONTEXT.md について、次の点を確認してください。記述はコードから確認できる内容と一致していますか？見落とされている境界はありますか？外部との契約があるように見えないのに、確定と記されている境界はありますか？Known-soft-spots に記載されていない明らかな技術的負債はありますか？相違点を報告してください。"

生成したすべての CONTEXT.md ファイルと探索レポートをサブエージェントに渡します。

最終確定する前に、相違点を解消してください。

フェーズ 5：来歴情報を記録する

ユーザーが CONTEXT ファイルをレビューして承認した後、現在の HEAD SHA を各ファイルに記録します：

git rev-parse HEAD

各 CONTEXT.md の Provenance: validated-at: 行を更新します。

フェーズ 6：ユーザーに提示する

次の内容を表示します：

• ルートの CONTEXT.md
• 作成したコンポーネントごとの CONTEXT.md ファイルの一覧
• 確定した境界と暫定的な境界の数
• Known-soft-spots の一覧（最も実用的な出力）

ユーザーにレビューを依頼し、誤解があれば修正してもらいます。コードベースを知っているのはユーザーであり、あなたではありません。修正内容を信頼してください。

map が行わないこと

• アーキテクチャ改善は提案しません（それは architect の役割です）。
• コード変更用の変更マニフェストは作成しません。
• テストは実行しません。
• CONTEXT.md が完全であることは保証しません。これは、可能な範囲で導き出した内容です。今後の verify の実行や、architect／triage のセッションで洗練されていきます。

map の完了後

ユーザーに次のように伝えます：

「CONTEXT.md の階層が整いました。新機能には architect、バグや小規模な変更には triage、コードの進化に合わせてドキュメントを同期するには verify を使用できます。」

参考ファイル

• references/context-schema.md — CONTEXT.md のフィールドと確度のルール
• references/templates/CONTEXT.md.tmpl — テンプレート
• references/drift-control.md — 来歴情報と古さのモデル
• references/seam-and-test-taxonomy.md — 確度に関するガイダンス