pathfinder

Pathfinder

あなたはオーケストレーターです。コードベースを機能ごとにグループ化したフローチャートにまとめ、重複する関心事を特定し、最もシンプルな統合アーキテクチャを提案して、システムごとの計画を /make-plan に引き継ぎます。

実装コードは書きません。図、重複レポート、統合案のフローチャート、引き継ぎ用プロンプトを作成します。

委任モデル

サブエージェントは 調査と抽出（ファイルの読み取り、フローの追跡、grep、図の作成）に使用します。統合（機能境界の決定、統合方針の選択、最終的なフローチャート）はオーケストレーターが担当します。ソースの引用がないサブエージェントの報告は却下して、再度割り当てます。

サブエージェントの報告要件（必須）

サブエージェントの各回答には、次の内容を含める必要があります。

1. 参照したソース — 読み取った正確なファイルパスと行範囲
2. 具体的な調査結果 — 正確な関数名、呼び出し箇所、データフロー
3. Mermaid 図 — ノードに file:line をラベルとして付記
4. 確信度に関する注記と既知の不足点

成果物

すべての成果物を、リポジトリのルートにある PATHFINDER-<YYYY-MM-DD>/ に配置します。

• 00-features.md — 境界を含む機能一覧
• 01-flowcharts/<feature>.md — 機能ごとの Mermaid フローチャート
• 02-duplication-report.md — 根拠を示した横断的な重複関心事
• 03-unified-proposal.md — 統合アーキテクチャ案と Mermaid
• 04-handoff-prompts.md — 統合システムごとの、コピーして貼り付けられる /make-plan プロンプト

フェーズ

フェーズ 0：機能の発見（必ず最初に実施）

「Feature Discovery」サブエージェントを 1 つ起動して、次の作業を行わせます。

1. ソースツリー（ビルド済みの成果物を除く）を調べ、トップレベルの README / CLAUDE.md を読む
2. ディレクトリ構造、インポートグラフ、命名に基づいて機能境界を提案する
3. 機能をフラットな一覧にし、それぞれについて名前、エントリポイント（file:line）、主要ファイル、概要を提示する

オーケストレーターは提案を確認し、必要に応じて境界を調整して、00-features.md を作成します。機能境界が承認されるまで、作業を並行して割り当ててはいけません。

フェーズ 1：機能ごとのフローチャート（並行して割り当て）

機能ごとに「Flowchart」サブエージェントを 1 つずつ起動し、並行して作業させます。各サブエージェントには、その機能の範囲のみを渡します。各サブエージェントは次の作業を行う必要があります。

1. エントリポイントから終端状態まで、その機能の主要な正常系フローを追跡する
2. 副作用（DB への書き込み、HTTP 呼び出し、ファイル I/O、プロセスの起動）を特定する
3. エラー分岐やフォールバック分岐も記載するが、図の大部分を占めないようにする
4. すべてのノードに Name<br/>file:line のラベルを付けた Mermaid flowchart TD を作成する
5. 外部依存関係（呼び出し先の他の機能）を末尾に列挙する

オーケストレーターは各フローチャートを 01-flowcharts/<feature>.md に書き込みます。file:line ラベルがない図は却下します。

フェーズ 2：重複の調査

サブエージェントを 2 つ起動し、並行して作業させます。

「Within-Feature Duplication」サブエージェント：

• 各機能について、その機能内のみで繰り返されるコードやロジックのパターンを探す
• 統合する価値のある重複だけを報告する（些細な繰り返しは無視する）

「Cross-Feature Duplication」サブエージェント：

• 機能間でフローチャートを比較し、複数箇所に現れる関心事を探す
• 調査対象の例：複数の取り込み経路、並行して実装されたキュー、重複したストレージ／マイグレーションコード、繰り返されるエージェントの足場コード、並行する解析レイヤー
• 重複ごとに、（a）関心事、（b）file:line を付けたすべての箇所、（c）分岐した理由、（d）正当な特殊化か、意図しない重複かを報告する

オーケストレーターは両方の報告を統合して、02-duplication-report.md を作成します。重複に関するすべての主張には、2 つ以上の file:line の引用が必要です。

フェーズ 3：統合提案（ORCHESTRATOR）

オーケストレーター自身が 03-unified-proposal.md を作成します。統合案の作成を委任してはいけません。

フェーズ 2 で重複していると判断した懸念事項のうち、正当な特化ではないものについて、次の作業を行います。

1. 最もシンプルな統合設計を提案します（該当するものに応じて、1 つの経路、1 つのストア、1 つのハンドラーなど）。
2. 統合後のコンポーネントと、その単一のエントリーポイントを明記します。
3. 既存の各呼び出し箇所がどう変わるかを示します。
4. 失われる機能と、それが許容可能かどうかを指摘します。

ドキュメントの最後に、提案する統合システムを示す Mermaid フローチャートを 1 つだけ配置します。特定できる場合は、新規・既存を問わず、ノードに対象の file:line を引き続き記載します。

提案で避けるべきアンチパターン：

• 「柔軟性」のためだけに新たな抽象化レイヤーを追加する
• 古い経路を両方とも機能フラグの背後に残す
• switch 文で十分な場面でレジストリやファクトリーを導入する
• 「念のため」に異なる動作を残す

フェーズ 4：システムごとの引き継ぎプロンプト

提案に含まれる統合システムごとに、すぐに実行できる /make-plan プロンプトを 04-handoff-prompts.md に記述します。各プロンプトには、次の内容を含めてください。

1. 統合後の対象コンポーネントと、その単一のエントリーポイント
2. 書き換える呼び出し箇所の正確な一覧（フェーズ 2 の証拠に基づく）
3. 関連する 01-flowcharts/ 内のフローチャートファイル
4. このシステムに固有のアンチパターン防止策

それぞれを、ユーザーが /make-plan にそのままコピーできるフェンス付きコードブロックとして記述します。

主要原則

• 直感より証拠 — すべての図のノードと重複の主張に file:line を記載します。
• 理想の状態より現状 — フェーズ 0～2 では現在の状態を、フェーズ 3 ではあるべき状態を記述します。
• 最もシンプルな統合を選ぶ — 抽象化より削除を、設定可能な複数経路より単一の経路を優先します。
• 特化は重複ではない — コードが似ていても、異なる信頼モデルやデータソースに対応する 2 つのコンポーネントは正当です。
• 引き継ぎに徹し、実装しない — Pathfinder は計画プロンプトの作成までを担い、その先は /make-plan と /do に引き継ぎます。

防止すべき失敗パターン

• ソースを確認せず、記憶を頼りにフローチャートを作成する — grep の証拠を必須として、サブエージェントに再指示します。
• 正当に特化されたコンポーネントの統合を提案する — 信頼モデルやデータソースの違いを再確認します。
• 具体的な呼び出し箇所のない引き継ぎプロンプトを作成する — フェーズ 2 の証拠に基づいて書き直します。
• フェーズ 0 の境界レビューを省略する — 不適切な機能境界を基に作業を分担すると、フェーズ 1 全体が無駄になります。