ns-harness-codebase-reverse-spec

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

既存のコードベースから、実装されているシステムを説明するテクノロジーに依存しないドキュメントを再構成します。対象には、観察された動作、ビジネスルール、権限、階層、製品運用に関連する外部連携が含まれます。

出力言語（厳守）

次の両方の成果物は英語のみで作成します。

• {product_root}/docs/context/system-reverse-spec.md（本文）
• {product_root}/docs/context/system-reverse-spec.agent.md（エージェント用インデックス）

言語を混在させないでください。チャットや製品 UI が別の言語であっても、セクションタイトル、ラベル、ビジネスルールのパターン（When …, the system …）、用語集、ユースケース、本文はすべて英語にしてください。ドメイン用語は明確な英語に翻訳し、固有名詞や製品名はそのままにしてください。

中心原則

コードは動作の証拠です。目的は、システムがどのように構築されたかではなく、何を、なぜ行うかを明らかにすることです。プログラミング言語、フレームワーク、ライブラリ、データベース、アーキテクチャパターン（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 を使って、人間が読む本文を作成します。タイトルや強調表現は「実装済みシステムの説明」に合わせて調整します。文体は、観察された製品の動作を現在形で記述する断定的なものにします。本文全体を英語で記述します（テンプレートのラベルは英語のままにし、すべてのプレースホルダーを英語で埋めます）。

詳細度（フェーズ 0／準備段階から）:

モード	人間が読む本文（system-reverse-spec.md）	エージェントインデックス
エグゼクティブ（デフォルト）	概要は簡潔にします。エンティティ／ユースケース／ルールは、長文ではなく、簡潔な表または箇条書きにします	references/agent_index.template.md から system-reverse-spec.agent.md を必ず作成します
網羅的	テンプレートに沿った全セクションを作成し、フローをより詳しく記述します	エージェントインデックスも引き続き作成します（表の内容は本文と対応させます）

エージェントインデックスのルール：表と一行の記述のみとし、段落形式の文章は使いません。両方がある場合、エージェントは最初にインデックスを読み込みます。

保存前にエージェントインデックスだけに適用： system-reverse-spec.agent.md を書く前に、../ns-harness/references/agent-artifact-compress.md を適用します（超簡潔な文体）。人間が読む本文 system-reverse-spec.md には、同様の簡略化を適用しないでください。

納品前に、以下の健全性チェックを行います。

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. 文書では何を、（推測できる場合は）なぜを説明し、どのように実装されたかは説明しません。
9. 成果物全体を英語で記述します。ポルトガル語と英語が混在するセクションタイトル、ラベル、ルール文は使いません。

フェーズ 5 — 納品と検証

以下を納品します。

1. 最終仕様書 — {product_root}/docs/context/system-reverse-spec.md（Markdown。DOCX は依頼があった場合のみ）。
2. エージェントインデックス — {product_root}/docs/context/system-reverse-spec.agent.md（エグゼクティブ／準備段階では必須、網羅的な場合も作成を推奨）。
3. 抽出ログ（共有は任意）— ユーザーが証跡の追跡性を希望する場合の作業ログ。
4. 人間が読む本文の付録に「チームで確認が必要な項目」を記載し、エージェントインデックスにも一行ずつ反映します。

モジュールをさらに掘り下げるか、網羅的モードに切り替えるか、次のドメイン範囲を納品するか、別の形式でエクスポートするかをユーザーに確認します。

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

リポジトリが1回の処理で無理なく扱える範囲を超える場合：

1. 対象範囲全体についてフェーズ0～1を完了し、ドメインマップのチェックポイント承認を得ます。
2. ドメインを1つずつ抽出して草案を作成します（各ドメインでフェーズ2～4を実施）。それぞれをセクションまたは別ファイルとしてまとめます。
3. 統合パスを実施します。ドメインを統合し、用語集の項目を重複排除し、横断的なポリシーを調整して、システム全体についてカバレッジマトリクスを一度確認します。
4. カバレッジ100％の達成を納品の条件にしないでください。完了したドメインを、「未分析」の項目を明記して納品します。

よくある避けるべき間違い

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

参照ファイル

ファイル	読むタイミング
references/spec_template.md	フェーズ4 — 人が読みやすい最終文書
references/agent_index.template.md	フェーズ4 — エージェント向けの高密度な補助インデックス
../ns-harness/references/agent-artifact-compress.md	保存前 — エージェントインデックスのみ
references/extraction_log_template.md	フェーズ2 — 抽出時の作業メモ
references/coverage_matrix.md	フェーズ1および4 — 完全性の確認
references/anti_leakage_checklist.md	フェーズ4 — 納品前の健全性チェック
scripts/scan_leakage.sh	フェーズ4 — 任意の自動初回チェック