タッチマップ

タッチマップ は何をしますか？

この変更を完了するために触れる必要があるもののメンタルマップを構築します。実装計画は書きません。コードは書きません。パイプライン内の次のスキルはロードしません。後のワークフロースキルがこのマップを他のスキルと連携させます。

マップが成果物です：変更を完了するために必要な部品とファイル。

いつ使用するか

ユーザーが変更内容と、ユーザーが選択した方法を決定した後にロードします。

• 実行する対象： 新機能、バグ修正、境界を移動するリファクタリング。
• スキップする対象： タイポ、コメント、フォーマット、ロックファイルのみ、コードのないドキュメント。
• 意図が未決定の場合（「Xを実装して」と選択された振る舞いがない場合）：停止します。変更が確定するまで質問します。その後マッピングします。まだ選択されていない機能はマッピングしません。

ハードゲート

1. コードも次のスキルもなし。 このスキルはマッピングします。ブロックは計画しません。実装もしません。
2. マップを表示して停止します。 承認を待ちません。ユーザーがマップが間違っている場合は中断します。
3. coupling.json を読み込まないでください。 それは後で別に行うチェックです。
4. リポジトリ全体をユーティリティで検索しないでください。 エージェントがヒットしたドメインで実際に確認した再利用のみを記録します。後のスキルが完全な検索を担当します。

永続アトラス

パス: <repo>/.agent/domain-map.json

リポジトリにコミットされます。ドメイン粒度のみ。関数名はここには含めません。

{
  "version": 1,
  "domains": [
    {
      "id": "auth",
      "owns": ["packages/auth", "packages/auth-ui"],
      "talksTo": ["users", "sessions"]
    }
  ]
}

• id — 短い名前、単一単語またはケバブケース。
• owns — パッケージまたはフォルダのパス。
• talksTo — 他のドメインのID。

このファイルは、ドメインレベルの事実が変更された場合のみ書き込みます： ドメインの追加、削除、名前変更、owns パスの変更、または talksTo リンクの変更。既存のドメイン内への関数の追加では、このファイルを編集してはいけません。

手順

手順1：確定した意図を確認

1. 変更がすでに明確（名前付きバグ、名前付き関数、名前付き振る舞い）であれば、続行します。
2. ユーザーがまだ何をしたいか選択中の場合は、マッピングを停止します。意図が確定するまで質問します。その後、ここに戻ります。

手順2：アトラスを読み込むかブートストラップ

1. .agent/domain-map.json が存在すれば、読み込みます。
2. 存在しない場合は、ドメイン粒度のみで最初のアトラスを構築します：
   • packages/*（またはリポジトリのパッケージフォルダ）を優先します。
   • それ以外の場合は、src/（またはメインソースルート）配下のトップレベルエリアフォルダを使用します。
   • talksTo は、それらの owns パス間のインポートエッジから設定します。
   • アトラスに関数名を含めないでください。
3. .agent/ が必要であれば作成します。ファイルを書き込みます。新しいアトラスを同じターンで表示します。続行します。待機しません。

手順3：この変更にズームイン

1. アトラスと確定した意図から、ヒットするドメインを選択します。
2. 変更に明確に属するモジュールから開始します。
3. それらのファイルを読み込みます。「触れる必要のあるファイル」リストがまだ変化している間のみ、インポートを追跡します。
4. 新しく開いたファイルがマップを変更しなくなったら停止します。完全を期すためにパッケージ全体を読むことはしません。
5. 部品は、変更が使用する、または隣接するモジュールと、既存の関数および型として命名します。ファイルはポインタであり、マップそのものではありません。
6. それらのファイルで実際に確認した再利用（パスとシンボル）を記録します。ワークスペース全体をヘルパーでgrepしないでください。

手順4：複数のパスが存在する場合、パスを選択

正直なパスが1つしかない場合は、1行でそれを示します。

複数のパスが存在する場合は、1つを選択します。以下のラダーの最初のステップで決定した時点で停止します：

1. 新しいモジュールを書くよりも、既存のものを再利用する。
2. ヒットしたドメイン内に留まる。新しいドメインを開かない。
3. 内部的な変更で済むなら、パッケージ、レイヤー、公開APIを追加しない。
4. 次にファイル数が最も少ないもの。

勝者と、それを決定したラダーのステップを名前を挙げます。最も少ないファイル数がタイブレークであり、ルール全体ではありません。ファイル数を稼ぐために、巨大なファイルに新しい振る舞いを詰め込まないでください。

手順5：アトラスを更新（ドメインレベルのみ）

1. この変更がドメインの追加、削除、名前変更、または owns / talksTo の変更を行う場合は、同じ作業内で .agent/domain-map.json をパッチします。
2. ドメイン粒度で何も変更がなければ、ファイルはそのままにします。

手順6：変更ごとのマップを表示

以下の6つのセクションを、この順序で表示します。タスクごとのマークダウンファイルは書きません。

1. ヒットドメイン — アトラスから。
2. 部品 — モジュール、および関与する既存の関数と型。確認した再利用（パスとシンボル）を含めます。
3. それらの連携方法 — この変更が使用するエッジのみ（呼び出し、型、データ）。完全なコールグラフではありません。それらのエッジが箇条書きで見づらい場合にのみ、Mermaid図を追加します。
4. 触れるファイル — 最終的なリスト。これがスタンドアロンの成果物です。
5. 触れないファイル — 明示的に。横槍編集を防ぎます。
6. パス選択 — パスが1つしかなかった場合は1行。複数あった場合は、勝者とラダーのステップ。

手順7：停止

1. 手順6の後、停止します。
2. コードを書きません。このスキルから別のスキルをロードしません。

決定木

• 意図が確定していない → 手順1、その後、確定するまでマッピングを停止。
• 意図が確定、振る舞い変更 → 手順2 → 3 → 4 → 5 → 6 → 7。
• タイポ / コメント / フォーマット / ロックファイル / ドキュメントのみ → このスキルは適用されません。
• アトラスファイルが存在しない → 手順2のステップ2（ブートストラップ）、その後続行。
• 1つのパス vs 複数のパス → 手順4。

レッドフラグ

シグナル	意味	代わりに行うこと
ユーザーが機能を選択する前にマッピング	意図が確定していない	手順1。まずは突き詰めて質問。
owns内のすべてのファイルを開く	ツアーであってマップではない	手順3：ファイルリストが安定したら停止。
モノレポ内を isRecord でgrep	完全な検索は別のスキル	既に確認した再利用のみを記録。
coupling.json を読み込む	誤ったファイル	そのチェックは後で行う。
マップに対して「これでよさそう？」と待機	ゲートは表示して停止	6つのセクションを表示して停止。
マップ後にコーディングを開始	このスキルはマッピングのみ	手順7。コードは書かない。
ここから次のパイプラインスキルをロード	ワークフローが構成を任せている	停止。ワークフロースキルに連携させる。
.agent/touch-maps/<task>.md を書き込む	古くなったタスクのゴミ	チャット（またはセッション）のみ。アトラスファイルのみが永続化。
ヘルパーが追加されたためアトラスを編集	アトラス内の関数粒度	アトラスはそのままに。セクション2にヘルパーを配置。
最初にファイル数が最も少ないパスを選択	巨大ファイルの罠	完全なラダーを実行。

エラーハンドリング

• gitリポジトリ内にない場合： 変更を6つのセクションでマッピングします。アトラスファイルはスキップします。その旨を1行で伝えます。
• アトラスのJSONが無効な場合： 推測しないでください。パースエラーを報告します。手順2ステップ2からの再構築は、ユーザーが同意した場合のみ、またはJSONの修正が明白な場合（末尾カンマ、括弧欠落）のみ行います。
• ヒットドメインが不明瞭な場合： 変更を所有できる最小のドメインセットを選択します。その疑念をパス選択で示します。1ファイルのバグのために新しいドメインを作成しないでください。
• ユーザーがマップが間違っていると中断した場合： 6つのセクションを修正します。パスが変更された場合は手順4を再実行します。その後停止します。