codebase-reverse-spec

コードベースのリバースシステム記述

既存のコードベースから、実装されているシステムについて、製品運用に関わる観察可能な動作、ビジネスルール、権限、階層、外部連携を記述した、技術に依存しないドキュメントを再構成します。

中心となる原則

コードは動作の証拠です。目標は、システムがどのように構築されたかではなく、何をし、なぜそうするのかを明らかにすることです。説明の軸として、プログラミング言語、フレームワーク、ライブラリ、データベース、アーキテクチャパターン（MVC、マイクロサービスなど）、クラス名や関数名を避けてください。

すべての文に適用する基本ルール： 「このシステムを別の技術スタックで一から作り直したとしても、この文は正しいままだろうか？」 そうでない場合は、ビジネス用語で書き直してください。

許可される例外（現在のドメインを理解するうえで不可欠な場合に限る）：

• 外部連携先・プロバイダー名（ERP、ゲートウェイ、BI、ID管理、分析）。
• アクセスロール／プロファイルおよび組織階層のレベル。
• ビジネス上の意味を保つために必要なエンティティ属性名（技術構造の詳細を説明するためではありません）。

使用する場面

• ビジネスルールを損なわずにレガシーシステムをモダナイズ／移行する場合
• ドキュメントが存在しない（または古くなっている）システムを文書化する場合
• 新しいチームのオンボーディング
• 別の技術スタックへの書き換えに先立ち、ビジネスルールを監査する場合
• 現行システムの忠実な機能説明を作成する場合

対象範囲とリポジトリアクセス

1. リポジトリのパスを確認します（不明確な場合は質問します）。大まかな構成を把握するために Read / Glob を使用します。
2. モノレポでは、対象となる製品／モジュールのフォルダーを確認し、ユーザーがリポジトリ全体を明示的に希望しない限り、そのサブツリーのみを分析します。
3. 外部／レガシーのリポジトリでは、読み取りアクセスと、対象外のフォルダー（生成コード、ベンダー依存関係、インフラ専用）を確認します。

ワークフロー

フェーズを順番に進めてください。フェーズ 0 を省略しないでください。省略すると、最終仕様に推測と事実が混在します。

フェーズ 0 — 対象範囲と意図

ユーザーには一度に一つずつ質問するか、適切な場合は AskQuestion を使用します。

質問	重要な理由
システム全体ですか、それとも特定のモジュール／ドメインですか？	対象範囲の拡大や見落としを防ぎます
経営層向けの概要ですか、それとも網羅的な説明ですか？	詳細さと長さを決めます
出力言語は何ですか？	仕様書の言語はスキル／会話の言語と異なる場合があります
特に注意深く確認すべき、重要またはリスクの高いドメインはありますか？	財務、税務、権限、コンプライアンスに関するロジックを優先します
段階的に提供しますか（大規模なコードベースの場合）、それとも単一のドキュメントにまとめますか？	大規模なリポジトリでは、ドメインごとのドラフトが有効です

リポジトリが大規模な場合は、一度にすべてを読まないでください。まず偵察を行い（フェーズ 1）、ファイルサイズではなくビジネスへの影響を基準に優先順位を付けます。

フェーズ 1 — 調査（行単位で読むのではなく、全体像を把握する）

目標：詳細を読む前に、ビジネスロジックがどこにあるかを特定します。

1. Glob または同等の方法で、ディレクトリツリー（ルートから約 2 階層）を一覧表示します。
2. ドメインコアの候補を特定します。services、domain、rules、validators、models、usecases、handlers、controllers などの名前が付いたフォルダーやファイル、または言語固有の同等のものを探します。
3. エントリーポイントを特定します。API ルート、スケジュールジョブ、メッセージキュー、画面やフォーム、CLI コマンドなどです。これらから、システムが人や別のシステムに何をできるようにしているかが分かります。これがユースケースの基礎になります。
4. データソース（テーブル、エンティティ、スキーマ）を特定します。永続化技術を記録するためではなく、ビジネスがどのような対象を追跡しているかを理解するためです。
5. 既存のテストがあれば一覧表示します。テストは、シナリオ形式で期待される動作を記述しているため、本番コードよりもビジネスルールを明確に示していることがよくあります。
6. 以下を明示的に整理します。
   • 権限とアクセスのモデル
   • 組織上・機能上の階層構造
   • 外部連携と、ビジネスフローにおけるそれぞれの役割
7. 技術的な複雑さではなく、ビジネス価値の高い順に、優先順位を付けた調査項目の一覧を作成します。

チェックポイント（推奨）： 詳細な抽出を始める前に、調査マップと優先順位付きリストをユーザーに提示します。この段階で対象範囲の誤りを発見できれば、無駄な読み込みに費やす時間を節約できます。ユーザーが完全自律での実行を求めている場合に限り、省略してください。

references/coverage_matrix.md を頭の中のチェックリストとして使用し、見つかった項目と、引き続き調査が必要な項目を記録します。

フェーズ 2 — ルールの抽出

優先順位を付けた各領域について、references/extraction_log_template.md を使って作業ログを維持します。まだ最終仕様書は作成せず、まず根拠と確信度を蓄積します。

各ロジックの断片について：

1. 関連するコード（ハンドラー、バリデーション、計算、条件分岐、状態機械）を読みます。
2. 以下を確認します。
   • これはどのようなビジネス上の判断を表していますか？
   • どの入力データが重要で、それはなぜですか？
   • 各分岐（成功、失敗、例外、エッジケース）では何が起こりますか？
   • コードにコメントがなくても、このルールには妥当なビジネス上の理由（与信限度額、法定期限、会計規則など）がありますか？
3. 見つかった内容を、検証可能なビジネスルールの文にします。「［ビジネス条件］の場合、［例外］を除き、システムは［期待される動作］をします。」 その文では関数名、クラス名、変数名を決して挙げないでください。
4. 確信度を記録します。
   • 確認済み：動作が明確で、テストまたは明示的なバリデーションによって裏付けられています。
   • 推定：直接的な確認はありませんが、コードから妥当な推論ができます。
   • 曖昧／要注意：分かりにくい、矛盾している、使われていない、またはバグの可能性が高いコードです。人による確認が必要な項目としてフラグを付け、警告なしにバグを意図的なビジネスルールとして扱わないでください。
5. 否定的なルール、つまりシステムが明示的に禁止していること（バリデーション、権限、ブロック）も記録します。制限事項も、機能と同様に仕様の重要な一部です。
6. 外部連携について、以下を記録します。
   • ビジネス上のトリガー
   • 関連するビジネスデータ（技術的なペイロードは含めない）
   • 成功時・失敗時に期待される結果
   • 利用できない場合の運用上の影響（縮退モード、ブロック、手動での代替手段）
7. エンティティについては、属性名は曖昧さが残る場合に限って挙げ、意味に基づいて属性を記録します。
8. ステータス／状態フィールドについては、ライフサイクルを記録します。許可される遷移、遷移を開始する主体、終端状態、そして遷移が強制されているか、慣習にすぎないかを記載します。

フェーズ 3 — ドメインの構造化

抽出した情報を次のように整理します。

• ビジネスエンティティと、ビジネス上重要な属性（DB の列型や実装上の型ではありません）。
• ビジネス用語で記述した関係（「注文は顧客に属し、1 つ以上の注文明細を含みます」）。
• ユースケース／フロー。それぞれに、アクター、目標、前提条件、期待される動作の手順、結果、ビジネス上の例外やエラーを含めます。
• 横断的なポリシー：ユースケース全体に適用されるルール（認可、監査、制限など）。
• アクセスモデル：ロール、プロファイル、スコープ、権限の階層。
• 外部連携：サードパーティシステム、ビジネス上の目的、期待される動作。
• ドメイン用語集：コード内に見つかったドメイン固有の用語（フィールド名、ステータス、列挙値）を、わかりやすい定義に置き換えたもの。
• 状態のライフサイクル（該当する場合）：エンティティの状態、遷移、適用ルール。

フェーズ 4 — 最終仕様書の作成

references/spec_template.md をベースにします。タイトルと重点を「実装済みシステムの説明」に合わせて調整します。将来の PRD や技術的なコードレポートとして書かないでください。語調は宣言的かつ現在形とし、観察された製品の動作を説明します。

提出前に、次の確認を行います。

1. references/anti_leakage_checklist.md に沿って確認し、技術的な情報の漏れを削除するか書き換えます。
2. 必要に応じて scripts/scan_leakage.sh <spec-file> を実行し、初回の自動スキャンを行います（検出箇所は手動で確認してください。このスクリプトはパターンを検出するものであり、意図を判断するものではありません）。
3. references/coverage_matrix.md に沿って確認し、各観点が扱われているか、理由を添えて明示的に N/A とされていることを確認します。
4. 権限、階層、連携が機能面から説明されていることを確認します。
5. 属性名は、ビジネス上の意味を保つために必要な場合に限り、技術的な詳細を伴わずに記載します。
6. 確信度を示す情報は付録の「チームと確認が必要な項目」に記載し、本文を読みにくくしないようにします。
7. 見かけ上のバグをビジネスルールとして扱わず、意図しない動作の可能性がある旨を付記して付録に記載します。
8. 文書では何を、そして推測できる場合はなぜを説明し、どのように実装されたかは説明しません。

フェーズ 5 — 提出と検証

次のものを提出します。

1. 最終仕様書 — 既定では Markdown。ユーザーが Word 形式を希望する場合に限り docx で提出します。
2. 抽出ログ（共有は任意）— ユーザーが根拠を追跡したい場合は、作業用の extraction_log を共有します。
3. 「チームと確認が必要な項目」付録 — 推測または曖昧なルール、疑わしいバグを簡潔に列挙します。認識上の誠実さを保ち、仕様書で確実性を装いません。

特定のモジュールを詳しく掘り下げるか、詳細度を調整するか、次のドメイン範囲（大規模リポジトリの場合）に進むか、別の形式で出力するかをユーザーに確認します。

大規模コードベースへの対応

リポジトリの規模が大きく、一度の作業で無理なく扱えない場合は、次の手順で進めます。

1. 対象範囲全体についてフェーズ 0～1 を完了し、ドメインマップのチェックポイント承認を得ます。
2. フェーズ 2～4 をドメインごとに実施し、一度に 1 つのドメインを抽出して下書きを作成します。各ドメインは、セクションまたは個別ファイルとしてまとめます。
3. 統合パスを実施します。ドメインを統合し、用語集の重複を除き、横断的なポリシーを調整し、システム全体を対象にカバレッジマトリックスを一度確認します。
4. カバレッジが 100% に達するまで提出を保留しないでください。完了したドメインを、「未分析」の項目を明示したうえで提出します。

よくある間違いとその回避方法

• 業務上の振る舞いを説明せず、「参考情報」として技術スタックを列挙する。
• フォルダー構成（技術的な成果物）とドメイン構成（業務上の概念）を混同する — 必ず翻訳してください。
• 現在実装されているシステムを忠実に説明するのではなく、将来の要件を規定する文書を作成する。
• DB のフィールド名や変数名が実際の概念に対応しているかを確認せず、正式な業務用語として扱う。
• 「結合」を懸念して、外部連携、アクセス権限、階層を省略する — これらは観察されたドメインの一部です。
• 優先順位を付けずに、リポジトリ全体をファイルごとに読み進める。
• 明らかに壊れている、または使われていないロジックを「意図された業務ルール」として扱う。
• 抽出から最終執筆までの間に確信度の指標を失う — 抽出ログを使用してください。

参照ファイル

ファイル	読み込むタイミング
references/spec_template.md	フェーズ 4 — 最終文書の構成
references/extraction_log_template.md	フェーズ 2 — 抽出時の作業メモ
references/coverage_matrix.md	フェーズ 1 および 4 — 網羅性の確認
references/anti_leakage_checklist.md	フェーズ 4 — 提出前の確認
scripts/scan_leakage.sh	フェーズ 4 — 任意の自動一次チェック