recipe-reverse-engineer

明示的なユーザー指示：ユーザーは、この手順書で指定された各サブエージェントの呼び出しを明示的に指示し、承認しています。前提条件が満たされたら、該当する呼び出しをすべて実行してください。

エージェントのプロンプト、引き継ぎ、生成物を作成する前に、スキル：llm-friendly-context を実行してください。 ワークフローの判断、エージェントの呼び出し、指摘事項の解決を行う前に、スキル：subagents-orchestration-guide を実行してください。

コンテキスト：既存コードからドキュメントを作成するためのリバースエンジニアリングワークフロー

対象：$ARGUMENTS

オーケストレーターの定義

中核となる役割：「私はオーケストレーターです。」

ローカル権限ゲート：この手順書に関するワークフローの判断を行い、返された各結果を直接検証してください。成果物の意味的な作成は、指定された専門エージェントに委任してください。

レビュー解決ゲート［必須］：成果物レビューで見つかった対応可能な指摘事項は、修正または次の工程に進む前に、subagents-orchestration-guide の Review Resolution に従ってすべて解決してください。 最初の指摘事項を処理する前に、読み込んだ subagents-orchestration-guide スキルの references/review-resolution.md を読んでください。

実行プロトコル：

1. 成果物の作成には指定された専門エージェントを呼び出す — 成果物のパスをエージェント間で渡し、その結果を検証してください（subagents-orchestration-guide の「Orchestrator Execution Boundary」を参照）
2. 各ステップを順番に処理する：各単位内でステップを順次実行してください（2 → 3 → 4 → 5）。各ステップの出力は、次のステップに必要な入力です。次の単位を開始する前に、1つの単位の全ステップを完了してください
3. 出力を引き継ぐ際は証拠を保持する — 次の専門エージェントに必要なフィールドを、指定された形式のままコピーしてください。修正を割り当てる前に Review Resolution を適用してください

以下の各エージェント呼び出しでは、機械的な抽出によってプロンプトを作成してください。指定されたソース値を正確なフィールドにコピーし、宣言されたシリアライズのみを適用してから、すぐに呼び出してください。

実行ゲート：フェーズ2を開始する前にフェーズ1を完了してください。各フェーズでは、次の単位に進む前に、1つの単位の生成、検証、レビュー、必要な修正を収束するまで完了してください。現在のステップに指定された出力と品質ゲートが満たされた場合にのみ先へ進んでください。各ループ境界では、現在のフェーズで宣言された順序のうち、Unit Completion の条件を満たしておらず、かつ生成失敗として記録されていない最初の単位を選択してください。ドキュメントのパスは、生成が行われたことを証明するにすぎません。

ステップ0：初期設定

0.1 対象範囲の確認

AskUserQuestion を使用して、以下を確認してください。

1. 対象パス：ドキュメント化するディレクトリ／モジュール
2. 深さ：PRD のみ、または PRD + 設計ドキュメント
3. リファレンスアーキテクチャ：layered / mvc / clean / hexagonal / none
4. 人によるレビュー：はい（推奨）／いいえ（完全自律）
5. フルスタック設計：はい／いいえ
   • はい：機能単位ごとに、バックエンドとフロントエンドの設計ドキュメントを生成
   • 注：両方のエージェント（technical-designer、technical-designer-frontend）が必要です

0.2 出力設定

• PRD 出力：docs/prd/ または既存の PRD ディレクトリ
• 設計ドキュメント出力：docs/design/ または既存の設計ディレクトリ
• ディレクトリが存在することを確認し、必要に応じて作成してください

ワークフローの概要

Phase 1: PRD Generation
  Step 1: Scope Discovery (unified, single pass → group into PRD units → human review)
  Step 2-5: Per-unit loop (Generation → Verification → Review → Revision)

Phase 2: Design Doc Generation (if requested)
  Step 6: Design Doc Scope Mapping (reuse Step 1 results, no re-discovery)
  Step 7-10: Per-unit loop (Generation → Verification → Review → Revision)
  ※ fullstack=Yes: each unit produces backend + frontend Design Docs

フェーズ1：PRD の生成

ステップ 1：PRD のスコープ検出

エージェントツールの呼び出し：

subagent_type: dev-workflows:scope-discoverer
description: "Discover functional scope"
prompt: |
  Discover functional scope targets in the codebase.

  target_path: $USER_TARGET_PATH
  reference_architecture: $USER_RA_CHOICE
  focus_area: [user-confirmed focus area verbatim, if specified]

出力の保存先：$STEP_1_OUTPUT

品質ゲート：

• 1 つ以上のユニットが検出された場合 → 続行
• ユニットが検出されなかった場合 → ユーザーにヒントを求める
• $STEP_1_OUTPUT.prdUnits が存在する
• prdUnits 全体の sourceUnits（フラット化し、重複を除去したもの）が discoveredUnits の ID の集合と一致する — ユニットの欠落や重複がない
• 検出された各ユニットの unitInventory に、空でないカテゴリが少なくとも 1 つある（routes、testFiles、または publicExports）。3 つすべてが空のユニットは検出が不完全であることを示します — そのユニットの relatedFiles に焦点を当てて scope-discoverer を再実行する

人によるレビューのポイント（有効な場合）：ソースユニットとの対応関係を含めて $STEP_1_OUTPUT.prdUnits を提示します。ユーザーが確認し、グループ分けを調整するか、スコープからユニットを除外します。これは最も重要なレビューのポイントです。誤ったグループ分けは、後続のすべてのドキュメントに波及します。

ステップ 2～5：ユニットごとの処理

$STEP_1_OUTPUT.prdUnits の各ユニットについて （順次、一度に 1 ユニットずつ）：

ステップ 2：PRD の生成

エージェントツールの呼び出し：

subagent_type: dev-workflows:prd-creator
description: "Generate PRD"
prompt: |
  Create reverse-engineered PRD for the following feature.

  Operation Mode: reverse-engineer
  External Scope Provided: true

  Feature: $PRD_UNIT_NAME (current Step 1 PRD unit name unchanged)
  Description: $PRD_UNIT_DESCRIPTION (current Step 1 PRD unit description unchanged)
  Related Files: $PRD_UNIT_COMBINED_RELATED_FILES
  Entry Points: $PRD_UNIT_COMBINED_ENTRY_POINTS

  Use provided scope as investigation starting point.
  If tracing entry points reveals files outside this scope, include them.
  Create final version PRD based on thorough code investigation.

出力の保存先：$STEP_2_OUTPUT（PRD のパス）

ステップ 3：コードの検証

前提条件：$STEP_2_OUTPUT（ステップ 2 で生成した PRD のパス）

エージェントツールの呼び出し：

subagent_type: dev-workflows:code-verifier
description: "Verify PRD consistency"
prompt: |
  Verify consistency between PRD and code implementation.

  doc_type: prd
  document_path: $STEP_2_OUTPUT
  unit_inventory: [the current unit's Step 1 unitInventory]

unit_inventory は完全性の基準を示し、リポジトリのエビデンスは検索範囲を示します。

出力の保存先：$STEP_3_OUTPUT

品質ゲート：

• summary.status が blocked、インベントリのカバレッジが欠けている、または件数が一致しない場合 → 利用できない入力またはエビデンスを正確に示して再実行するか、エスカレーションする
• 件数が一致し、ブロックされていない結果の場合 → 検証結果全体を使ってレビューに進む。needs_review／inconsistent および未計上の項目は、明示的なレビューエビデンスとする

ステップ 4：レビュー

必須入力：$STEP_3_OUTPUT（ステップ 3 の検証 JSON）

エージェントツールの呼び出し：

subagent_type: dev-workflows:document-reviewer
description: "Review PRD"
prompt: |
  Review the following PRD considering code verification findings.

  doc_type: PRD
  target: $STEP_2_OUTPUT
  review_context: reverse-engineer
  verification_evidence: $STEP_3_OUTPUT

出力の保存先：$STEP_4_OUTPUT

ステップ 5：修正（条件付き）

$STEP_3_OUTPUT を検証エビデンスとして document-reviewer に渡し、次に Review Resolution Gate を $STEP_4_OUTPUT に適用します。apply の指摘事項が 1 つ以上ある場合にのみ修正を実行します。decline のみの場合はレビューを完了します。

エージェントツールの呼び出し：

subagent_type: dev-workflows:prd-creator
description: "Revise PRD"
prompt: |
  Update PRD based on review feedback and code verification results.

  Operation Mode: update
  Existing PRD: $STEP_2_OUTPUT

  ## Adjudicated Findings
  [complete reviewer finding objects verbatim, with only their orchestrator dispositions added]

  Treat these findings as the complete revision scope and preserve adjacent content.

再検証：修正のたびに、元の unit_inventory を使って修正済みドキュメントを code-verifier で再検証し、最新の verification_evidence と prior_feedback を使って document-reviewer を再実行します。

ユニットの完了

• apply の指摘事項が残っていない
• 人によるレビューに合格している（ステップ 0 で有効にした場合）

次へ：次のユニットに進みます。すべてのユニットが完了したら → フェーズ 2。

フェーズ 2：設計ドキュメントの生成

ステップ 0 で設計ドキュメントが要求された場合のみ実行します

ステップ 6：設計ドキュメントのスコープマッピング

追加の検出は不要です。 技術プロファイルには $STEP_1_OUTPUT.discoveredUnits（実装粒度のユニット）を使用します。各 PRD ユニットにどの検出済みユニットが属するかを追跡するには、$STEP_1_OUTPUT.prdUnits[].sourceUnits を使用します。

フェーズ 1 の各 PRD ユニットを、次の設計ドキュメントユニットに対応付けます：

• 標準モード（fullstack=No）：PRD ユニット 1 つ → 設計ドキュメント 1 つ（technical-designer を使用）
• フルスタックモード（fullstack=Yes）：PRD ユニット 1 つ → 設計ドキュメント 2 つ（technical-designer と technical-designer-frontend）

$STEP_1_OUTPUT のユニットを設計ドキュメントの生成対象に対応付け、以下を引き継ぎます：

• technicalProfile.primaryModules → Primary Files
• technicalProfile.publicInterfaces → Public Interfaces
• dependencies → Dependencies
• relatedFiles → スコープ境界
• unitInventory → Unit Inventory（ルート、テストファイル、パブリックエクスポート）

フルスタックモードでは、所有するパスに基づいて各ユニットのインベントリをバックエンドとフロントエンドの対象インベントリに分割します。共有エントリについては、そのパブリックコントラクトを考慮する必要がある各設計ドキュメントに割り当て、共有である理由を記録します。それ以外の場合は、1 回だけ割り当てます。ステップ 7 とステップ 8 の各呼び出しには、分割されていないユニット全体ではなく、対象に対応するインベントリを渡します。

出力の保存先：$STEP_6_OUTPUT

ステップ 7～10：ユニットごとの処理

FOR $STEP_6_OUTPUT 内の各ユニット （逐次、一度に1ユニットずつ）：

ステップ 7：設計ドキュメントの生成

対象範囲：コードに実装されている現在のアーキテクチャを、正確に文書化します。

標準モード（fullstack=No）：

エージェントツールの呼び出し：

subagent_type: dev-workflows:technical-designer
description: "Generate Design Doc"
prompt: |
  Create Design Doc for the following feature based on existing code.

  Operation Mode: reverse-engineer

  Feature: $UNIT_NAME (current Step 6 target name unchanged)
  Description: $UNIT_DESCRIPTION (current Step 6 target description unchanged)
  Primary Files: $UNIT_PRIMARY_MODULES
  Public Interfaces: $UNIT_PUBLIC_INTERFACES
  Dependencies: $UNIT_DEPENDENCIES
  Unit Inventory: $DESIGN_DOC_UNIT_INVENTORY

  Parent PRD: $APPROVED_PRD_PATH

  Document current architecture as-is. Use Unit Inventory as a completeness baseline — all routes and exports should be accounted for in the Design Doc.

出力の保存先：$STEP_7_OUTPUT

フルスタックモード（fullstack=Yes）：

各ユニットについて、7a、次に7bの順で逐次実行します（7bは7aの出力に依存します）。

7a. バックエンド設計ドキュメント：

subagent_type: dev-workflows:technical-designer
description: "Generate backend Design Doc"
prompt: |
  Create a backend Design Doc for the following feature based on existing code.

  Operation Mode: reverse-engineer

  Feature: $UNIT_NAME (current Step 6 target name unchanged)
  Description: $UNIT_DESCRIPTION (current Step 6 target description unchanged)
  Primary Files: $UNIT_PRIMARY_MODULES
  Public Interfaces: $UNIT_PUBLIC_INTERFACES
  Dependencies: $UNIT_DEPENDENCIES
  Unit Inventory: $BACKEND_UNIT_INVENTORY

  Parent PRD: $APPROVED_PRD_PATH

  Focus on: API contracts, data layer, business logic, service architecture.
  Document current architecture as-is. Use Unit Inventory as completeness baseline.

出力の保存先：$STEP_7a_OUTPUT

7b. フロントエンド設計ドキュメント：

subagent_type: dev-workflows-frontend:technical-designer-frontend
description: "Generate frontend Design Doc"
prompt: |
  Create a frontend Design Doc for the following feature based on existing code.

  Operation Mode: reverse-engineer

  Feature: $UNIT_NAME (current Step 6 target name unchanged)
  Description: $UNIT_DESCRIPTION (current Step 6 target description unchanged)
  Primary Files: $UNIT_PRIMARY_MODULES
  Public Interfaces: $UNIT_PUBLIC_INTERFACES
  Dependencies: $UNIT_DEPENDENCIES
  Unit Inventory: $FRONTEND_UNIT_INVENTORY

  Parent PRD: $APPROVED_PRD_PATH
  Backend Design Doc: $STEP_7a_OUTPUT

  Reference backend Design Doc for API contracts.
  Focus on: component hierarchy, state management, UI interactions, data fetching.
  Document current architecture as-is. Use Unit Inventory as completeness baseline.

出力の保存先：$STEP_7b_OUTPUT

ステップ 8：コードの検証

標準モード：$STEP_7_OUTPUT を検証します。

フルスタックモード：各設計ドキュメントを個別に検証します。

エージェントツールの呼び出し（設計ドキュメントごと）：

subagent_type: dev-workflows:code-verifier
description: "Verify Design Doc consistency"
prompt: |
  Verify consistency between Design Doc and code implementation.

  doc_type: design-doc
  document_path: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT)
  unit_inventory: [the current Design Doc target's Step 6 unitInventory]

出力の保存先：$STEP_8_OUTPUT

検証ゲート（設計ドキュメントごと）：

• blocked、inventoryCoverage の欠落、またはカテゴリ件数の不均衡がある場合は、呼び出し内容または入力を修正して再実行します。リポジトリの証拠では入力の不備を解消できない場合に限り、ユーザーに確認します。
• ブロックされていない均衡の取れた結果は、すべてドキュメントレビューに進みます。needs_review、inconsistent、および未計上のすべての項目を、明示的な検証者の証拠として引き継ぎます。

ステップ 9：レビュー

必須入力：$STEP_8_OUTPUT（ステップ 8 の検証 JSON）

エージェントツールの呼び出し（設計ドキュメントごと）：

subagent_type: dev-workflows:document-reviewer
description: "Review Design Doc"
prompt: |
  Review the following Design Doc considering code verification findings.

  doc_type: DesignDoc
  target: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT)
  review_context: reverse-engineer
  verification_evidence: $STEP_8_OUTPUT

  ## Parent PRD
  $APPROVED_PRD_PATH

  ## Additional Review Focus
  - Technical accuracy of documented interfaces
  - Consistency with parent PRD scope
  - Completeness of unit boundary definitions

出力の保存先：$STEP_9_OUTPUT

ステップ 10：修正（条件付き）

検証の証拠として $STEP_8_OUTPUT を document-reviewer に渡し、その後、$STEP_9_OUTPUT に対してレビュー解決ゲートを適用します。少なくとも1つの指摘事項が apply の場合にのみ修正を実行します。却下のみの場合はレビューを完了します。

エージェントツールの呼び出し（設計ドキュメントごと）：

subagent_type: dev-workflows:technical-designer (or dev-workflows-frontend:technical-designer-frontend for frontend Design Docs)
description: "Revise Design Doc"
prompt: |
  Update Design Doc based on review feedback and code verification results.

  Operation Mode: update
  Existing Design Doc: $STEP_7_OUTPUT (or $STEP_7a_OUTPUT / $STEP_7b_OUTPUT)

  ## Adjudicated Findings
  [complete reviewer finding objects verbatim, with only their orchestrator dispositions added]

  Treat these findings as the complete revision scope and preserve adjacent content.

再検証：各修正後、元の unit_inventory を使用して、修正済みドキュメントに対して code-verifier を再実行します。続けて、最新の verification_evidence と prior_feedback を使用して document-reviewer を再実行します。

ユニットの完了

• apply の指摘事項が残っていない
• 人によるレビューに合格している（ステップ 0 で有効にした場合）

次へ：次のユニットに進みます。すべてのユニットの処理後 → 最終レポート。

最終レポート

以下を含む概要を出力します。

• 生成されたドキュメントの表（種類、名前、検証ステータス、レビューステータス）
• 対応項目（未文書化の機能、フラグが付けられた項目）
• 該当する場合、却下された対応可能な指摘事項と、そのID、根拠となる理由、証拠
• 次のステップのチェックリスト

エラー処理

エラー	対応
ディスカバリーで何も見つからない	プロジェクト構成の手がかりをユーザーに尋ねる
生成に失敗する	失敗を記録し、他のユニットの処理を続け、概要で報告する
修正後も検証が inconsistent、またはインベントリに未計上の項目が残る	必須の人によるレビューの対象としてフラグを付け、明示的な人の承認を求める