reverse-engineer

リバースエンジニアリング（ルート対応）

仕様駆動開発へのリバースエンジニアリングプロセスのステップ 2／6です。 6 ステップのプロセス：1. 分析、2. リバースエンジニアリング（このスキル）、3. 仕様作成、4. ギャップ分析、5. 実装計画、6. 実装。

所要時間の目安： 30～45 分 前提条件： ステップ 1 が完了していること（analysis-report.md と .stackshift-state.json のルート選択） 出力： docs/reverse-engineering/ 内の 11 個のドキュメントファイル

ルートに応じた動作：

• グリーンフィールド： ビジネスロジックのみ抽出（フレームワーク非依存）
• ブラウンフィールド： ビジネスロジックと技術的な実装の詳細を抽出

実装フレームワーク（Spec Kit、BMAD、BMAD Auto-Pilot）にかかわらず、出力は同じです。フレームワークの選択が影響するのは、ステップ 2 の後の処理のみです。

---

設定の確認

ガード：続行する前に、状態ファイルが存在することを確認します。

if [ ! -f .stackshift-state.json ]; then
  echo "ERROR: .stackshift-state.json not found."
  echo "Step 1 (Initial Analysis) must be completed first. Run /stackshift.analyze to begin."
  exit 1
fi

DETECTION_TYPE=$(cat .stackshift-state.json | jq -r '.detection_type')
ROUTE=$(cat .stackshift-state.json | jq -r '.route')

if [ "$DETECTION_TYPE" = "null" ] || [ -z "$DETECTION_TYPE" ]; then
  echo "ERROR: detection_type missing from state file. Re-run /stackshift.analyze."
  exit 1
fi
if [ "$ROUTE" = "null" ] || [ -z "$ROUTE" ]; then
  echo "ERROR: route missing from state file. Re-run /stackshift.analyze."
  exit 1
fi

echo "Detection: $DETECTION_TYPE"
echo "Route: $ROUTE"

SPEC_OUTPUT=$(cat .stackshift-state.json | jq -r '.config.spec_output_location // "."')
echo "Writing specs to: $SPEC_OUTPUT"

if [ "$SPEC_OUTPUT" != "." ]; then
  mkdir -p "$SPEC_OUTPUT/docs/reverse-engineering"
  mkdir -p "$SPEC_OUTPUT/.specify/memory/specifications"
fi

状態ファイルの構造：

{
  "detection_type": "monorepo-service",
  "route": "greenfield",
  "implementation_framework": "speckit",
  "config": {
    "spec_output_location": "~/git/my-new-app",
    "build_location": "~/git/my-new-app",
    "target_stack": "Next.js 15..."
  }
}

差分更新用にコミットハッシュを取得します：

COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
COMMIT_DATE=$(git log -1 --format=%ci 2>/dev/null || date -u +"%Y-%m-%d %H:%M:%S")
echo "Pinning docs to commit: $COMMIT_HASH"

検出結果とルートに基づく抽出方法：

検出タイプ	＋ グリーンフィールド	＋ ブラウンフィールド
モノレポサービス	ビジネスロジックのみ（技術非依存）	実装全体と共有パッケージ（技術に準拠）
Nx アプリ	ビジネスロジックのみ（フレームワーク非依存）	Nx／Angular の実装詳細全体
一般的なアプリ	ビジネスロジックのみ	実装全体

• detection_type は、調べるパターン（共有パッケージ、Nx プロジェクト設定、モノレポ構造など）を決定します。
• route は、それらの文書化方法（技術非依存か、技術に準拠するか）を決定します。

---

フェーズ 1：コードベースの詳細分析

subagent_type=stackshift:stackshift-code-analyzer:AGENT を指定して Task ツールを使用し、分析を実行します。エージェントを利用できない場合は、Explore エージェントに切り替えます。

エラーからの復旧： サブエージェントが失敗する、またはサブフェーズで空の結果を返した場合は、Explore エージェントで 1 回再試行します。再試行も失敗した場合は、[ANALYSIS INCOMPLETE] マーカーを付けて不足箇所を記録し、残りのサブフェーズを続行します。

コンポーネントが見つからない場合： サブフェーズで関連コードが見つからない場合（例：バックエンドのみのサービスにフロントエンドがない場合）は、そのサブフェーズをスキップせず、対応する出力ファイルに存在しないことを記録します。

個別のサブエージェント呼び出しを使用して、サブフェーズ 1.1～1.6 を並行して起動します。フェーズ 2 に進む前に、すべての結果を収集します。

1.1 バックエンド分析

• すべての API エンドポイントを見つけ、メソッド、ルート、認証要件、パラメーター、目的を記録します。
• スキーマ、型、インターフェース、フィールド定義を含む、すべてのデータモデルをカタログ化します。
• 環境変数、設定ファイル、各種設定など、設定元をすべて一覧にします。
• API、サービス、データベースなど、すべての外部連携をマッピングします。
• サービス、ユーティリティ、アルゴリズムからビジネスロジックを抽出します。

1.2 フロントエンド分析

• すべてのページとルートについて、目的と認証要件を一覧にします。
• コンポーネントをカテゴリ別（レイアウト、フォーム、UI コンポーネント）にカタログ化します。
• 状態管理について、ストア構造とグローバル状態のパターンを記録します。
• API クライアント層について、フロントエンドからバックエンドへの呼び出し方法をマッピングします。
• デザインシステム、テーマ、コンポーネントのスタイルなど、スタイルのパターンを抽出します。

1.3 インフラストラクチャ分析

• IaC ツール、クラウドプロバイダー、サービスなど、デプロイ設定を記録します。
• CI/CD パイプラインとワークフローをマッピングします。
• 種類、スキーマ、マイグレーションなど、データベースの設定をカタログ化します。
• オブジェクトストレージ、ファイルシステム、キャッシュなどのストレージシステムを特定します。

1.4 テスト分析

• すべてのテストファイルを特定し、使用されているテストフレームワークを確認します。
• テストを単体テスト、統合テスト、E2E テストに分類します。
• モジュールごとのカバレッジ率を推定します。
• モック、フィクスチャ、シードデータなどのテストデータをカタログ化します。

1.5 ビジネスコンテキスト分析

• README、CONTRIBUTING、およびマーケティングページやランディングページを読みます。
• パッケージの説明とリポジトリのメタデータを抽出します。
• ユーザー向け機能を示すコメントのパターンを特定します。
• ペルソナを推測するため、エラーメッセージやユーザー向け文字列を収集します。
• 命名規則を分析し、ドメインの概念を明らかにします。
• 意思決定の経緯をたどるため、git の履歴を調べます。

1.6 意思決定の経緯の調査

• 依存関係のマニフェスト（package.json、go.mod、requirements.txt）を調べ、技術選定を確認します。
• 設定ファイル（tsconfig、eslint、prettier）を分析し、設計思想を把握します。
• CI/CD 設定を確認し、デプロイに関する決定を把握します。
• 主要なアーキテクチャファイルに対して git blame を実行し、意思決定のポイントを特定します。
• 「why」の説明を含むコメント（TODO、HACK、FIXME、NOTE）を収集します。
• git の履歴やコメントから、却下された代替案を探します。

進捗シグナル： すべてのサブフェーズが完了したら、次の内容をログに記録します：「Phase 1 complete: Analysis gathered for [結果が得られたサブフェーズの一覧]。」

---

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

docs/reverse-engineering/ ディレクトリを作成し、ドキュメントファイルを 11 個すべて生成します。各ファイルには、operations/output-file-specs.md で説明されているグリーンフィールドまたはブラウンフィールドのバリエーションを適用します。詳細なファイルごとの仕様を確認するため、今すぐそのファイルを読みます。

.stackshift-docs-meta.json がすでに存在する場合は、新しいメタデータで完全に上書きします。

ステップ 2.1：最初にメタデータファイルを作成する

COMMIT_HASH=$(git rev-parse HEAD 2>/dev/null || echo "unknown")
COMMIT_DATE=$(git log -1 --format=%ci 2>/dev/null || date -u +"%Y-%m-%d %H:%M:%S")
GENERATED_AT=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

docs/reverse-engineering/.stackshift-docs-meta.json を作成します：

{
  "commit_hash": "<COMMIT_HASH>",
  "commit_date": "<COMMIT_DATE>",
  "generated_at": "<GENERATED_AT>",
  "doc_count": 11,
  "route": "<greenfield|brownfield>",
  "docs": {
    "functional-specification.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "integration-points.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "configuration-reference.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "data-architecture.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "operations-guide.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "technical-debt-analysis.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "observability-requirements.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "visual-design-system.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "test-documentation.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "business-context.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" },
    "decision-rationale.md": { "generated_at": "<GENERATED_AT>", "commit_hash": "<COMMIT_HASH>" }
  }
}

ステップ 2.2：各ドキュメントにメタデータヘッダーを追加する

生成するすべてのドキュメントで、タイトルの直後に次のヘッダーを配置します：

# [Document Title]

> **Generated by StackShift** | Commit: `<short-hash>` | Date: `<GENERATED_AT>`
> Run `/stackshift.refresh-docs` to update with latest changes.

ステップ 2.3：チェックポイントを設けてファイルを生成する

次の順序でファイルを生成し、各ファイルの生成後に進捗をログに記録します：

バッチ 1（コアアーキテクチャ）：

1. functional-specification.md
2. data-architecture.md
3. integration-points.md
4. configuration-reference.md

ファイル 1～4 の作成後、次の内容をログに記録します：「Generated 4/11 files (core architecture complete).」続行する前に、出力ディレクトリにファイルが 4 個あることを確認します。

バッチ 2（運用と品質）： 5. operations-guide.md 6. technical-debt-analysis.md 7. observability-requirements.md 8. visual-design-system.md 9. test-documentation.md

ファイル 5～9 の作成後、次の内容をログに記録します：「Generated 9/11 files (operations and quality complete).」続行する前に、出力ディレクトリにファイルが 9 個あることを確認します。

バッチ 3（コンテキストと意思決定）： 10. business-context.md 11. decision-rationale.md

ファイル 10～11 の作成後、次の内容をログに記録します：「Generated 11/11 files. Phase 2 complete.」

出力構成：

docs/reverse-engineering/
├── .stackshift-docs-meta.json
├── functional-specification.md
├── integration-points.md
├── configuration-reference.md
├── data-architecture.md
├── operations-guide.md
├── technical-debt-analysis.md
├── observability-requirements.md
├── visual-design-system.md
├── test-documentation.md
├── business-context.md
└── decision-rationale.md

---

成功基準

• docs/reverse-engineering/ にドキュメントファイルが 11 個すべて生成されている
• アプリケーションのあらゆる側面が包括的に網羅されている
• フレームワークに依存しない機能仕様（グリーンフィールド向け）
• データモデルの完全なドキュメント
• ビジネスコンテキストが、明確な [INFERRED]／[NEEDS USER INPUT] マーカーとともに記録されている
• 意思決定の根拠が ADR 形式で記録されている
• データフロー図を用いて、統合ポイントがすべて詳細にマッピングされている
• .stackshift-docs-meta.json が作成され、インクリメンタル更新用のコミットハッシュが記録されている
• 各ドキュメントにコミットハッシュと生成日を含むメタデータヘッダーがある

---

次のステップ

すべてのドキュメントが生成されたら：

GitHub Spec Kit の場合（implementation_framework: speckit）： ステップ 3 に進み、/stackshift.create-specs を使用してドキュメントを .specify/ の仕様に変換します。

BMAD Method の場合（implementation_framework: bmad）： ステップ 6 に進み、BMAD の *workflow-init に引き継ぎます。BMAD の PM エージェントとアーキテクトエージェントは、リバースエンジニアリングのドキュメントをコンテキストとして使用します。

BMAD Auto-Pilot の場合（implementation_framework: bmad-autopilot）： /stackshift.bmad-synthesize に進み、BMAD の成果物を自動生成します。リバースエンジニアリングのドキュメント 11 個によって、BMAD が必要とする情報の約 90% が提供されます。

---

DO／DON'T

DO：

• システムが何をするかを説明し、どのように実現するかは説明しません（特にグリーンフィールドの場合）。
• README、コメント、命名、設定、Git の履歴など、推論に利用できるすべての情報を使います。
• 確信度を明示します。マーカーなし＝確信あり、[INFERRED]＝妥当な推論、[NEEDS USER INPUT]＝本当に不明。
• ドキュメント間の相互参照を行います（例：技術的負債をトレードオフの判断に反映します）。
• 推論ごとに具体的な根拠を示します。

DON'T：

• 機能仕様にフレームワーク名をハードコードしません（グリーンフィールドの場合）。
• ビジネスロジックと技術的な実装を混在させません（グリーンフィールドの場合）。
• 根拠のないビジネス目標をでっち上げません。
• 推論であることを明示せず、推論を事実として述べません。
• 推論が必要だからといってセクションを省略しません。分析を試み、確信度を明示します。

---

完全性チェックリスト

分析で次の項目を捉えられていることを確認します。

• すべての API エンドポイント（明白なものだけではありません）
• すべてのデータモデル（DTO、型、インターフェースを含みます）
• すべての設定オプション（複数のファイルを確認します）
• すべての外部連携
• すべてのユーザー向け文字列とエラーメッセージ（ペルソナやコンテキストの推論に使用します）
• すべての設定ファイル（判断理由の推論に使用します）

各ドキュメントは、包括的で、正確で、整理され、実行可能であり、推論に基づく情報と検証済みの情報を明確に区別している必要があります。