ln-72-current-architecture-documenter

現行アーキテクチャの文書化

目標： チェックアウト済みリポジトリに実装されているアーキテクチャの、信頼できるスナップショットを作成します。存在するものとその動作を記録し、評価や目標アーキテクチャの提案、コードの修正、意図された図を事実として扱うことはしません。

実行契約： 順序付けられたチェック項目が完了の定義です。各項目を内部で PENDING、具体的な証拠がある PROVEN、条件が存在しない証拠がある CLEARED、または不足がある UNPROVEN として管理します。読み取り、委任、ツールの失敗は証明になりません。各セクションの後に項目の状態を確認してください。返答前にすべての PENDING を解消し、PROVEN と CLEARED のみを数えます。不足がある場合は、スキルの判定ルールと承認ルールを適用してください。 ユーザーの意図、範囲、既存の承認を維持してください。承認済みの作業は続行し、重大な未解決の選択肢や必要な外部承認がある場合に限り、確認を求めてください。重要なリスクに応じて調査の深さを調整し、確認を黙って省略してはいけません。依存関係と安全性に関する順序を守り、それ以外は各義務に適した検証方法を選択してください。

ツールの使い分け

必要事項	推奨機能	代替手段
スナップショットの識別とワークツリーの状態	Git の状態、ブランチ、リモート、HEAD	提供されたスナップショットを UNVERIFIED として記録
構造と構成	ネイティブの一覧表示、検索、マニフェスト、ファイルの直接読み取り	対象を絞った手動調査
シンボル、依存関係、利用箇所	言語インテリジェンスまたは依存関係解決ツール	定義、登録、インポート、呼び出し元を検索
実行時およびデプロイのトポロジー	エントリーポイント、IaC、コンテナー、CI、構成、実行時の証拠	デプロイ関係を UNKNOWN として記録
ドキュメントの変更	承認済みアーキテクチャドキュメントへの最小限のパッチ	書き込み可能なパスが承認されていない場合は BLOCKED を返す

リモートリポジトリの状態より、ローカルの証拠を優先してください。実行可能な配線や正式な契約によって裏付けられるまでは、パス、図、命名規則は手掛かりにすぎません。

成果物のルール

• 明確な現行アーキテクチャドキュメントがあれば再利用し、なければ docs/architecture/current-state.md を使用します。
• リモート、ブランチ、HEAD、ワークツリーの状態、観察日をドキュメントに明記します。
• 重要な主張には、ファイルパス、シンボル、コマンド、構成キーなどの根拠を示します。
• 主張には OBSERVED、DOCUMENTED、INFERRED、UNKNOWN のいずれかのラベルを付けます。
• 実際の構造、意図された目標設計、監査結果を区別します。
• まず宣言されたシステム範囲を大まかに示し、重要な動作の説明に必要な部分だけを詳しく記述します。範囲が限定された依頼をリポジトリ全体の網羅的な一覧に広げてはいけません。
• ファイルを網羅的に列挙するより、責務を中心とした説明を優先します。
• 調査済みでない範囲と、本当に存在しないものを読者が区別できるよう、証拠のカットオフを記録します。
• アーキテクチャの理解に影響する場合に限り、変動しやすい件数や一覧を記載します。

チェックリスト

1. ドキュメントの契約を確立する

• リポジトリの範囲、想定読者、承認済みの保存先、必要な詳細度、言語を確認します。
• リポジトリの指示を読み、スナップショットの識別情報と、ワークツリーに変更がある場合の制約を記録します。
• 現行状態、ベースライン、目標設計、意思決定、図、デプロイに関する既存の成果物を検索します。
• 重複したプロジェクト知識を作成せず、曖昧さのない現行状態のドキュメントを再利用するか、既定のパスを選択します。
• 承認済みのアーキテクチャドキュメント以外は読み取り専用とします。

2. システムの全体像を把握する

• マニフェストと CI から、言語、フレームワーク、パッケージのルート、生成される成果物、および正式なビルドまたは実行コマンドを特定します。
• ユーザー、外部システム、エントリーポイント、アプリケーション、サービス、プロセス、ワーカー、スケジュールされたジョブ、およびデプロイ単位を特定します。
• 主要なドメインまたはモジュール、責務、所有者、および依存関係の方向を把握します。
• データストア、キャッシュ、キュー、ファイル、外部 API、スキーマ、および信頼できる唯一の情報源となるシステムを把握します。
• 公開インターフェース、実行時の検出、登録、設定の合成、および環境の境界を記録します。
• ディレクトリ名だけから独立性を推測せずに、ビルド、デプロイ、スケール、および障害の境界を記録します。

3. 重要な動作を追跡する

• ビジネス上の重要性とアーキテクチャへの影響範囲に基づいて、代表的な重要フローを選択します。
• 各フローを、アクターまたはトリガーから、エントリーポイント、実行時の調整、ドメイン動作、永続化または連携、観測可能な結果まで追跡します。
• 根拠がある場合は、同期および非同期の処理段階、トランザクションの所有者、一貫性、再試行、タイムアウト、冪等性、およびエラーの伝播を記録します。
• リポジトリの証拠から確認できるデプロイ、起動、終了、ヘルスチェック、可観測性、および復旧の経路を説明します。
• 複雑さや不確実性がアーキテクチャの理解に影響するサブシステムのみ詳しく調べ、通常の実装詳細はアーキテクチャ文書に含めないようにします。

4. 現状を示す成果物を作成する

• スナップショットの識別情報、システムコンテキスト、コンポーネント一覧、責務、依存関係とデータフロー、実行時トポロジー、重要なフロー、デプロイ、所有者、および証拠の一覧を記載します。
• 必要最低限の有用な図をインラインで含めるか、既存の図の成果物をパスで参照します。
• 実装で確認した内容と文書化された意図を区別し、重大度を割り当てずに、乖離や矛盾を明示します。
• リポジトリの証拠で権威ある裏付けが得られない限り、リモートのみ、実行時のみ、組織に関する事実、または本番環境に関する事実は UNKNOWN とします。宣言されたデプロイ設定と、実際に観測された稼働中のトポロジーを区別します。
• 手動で維持されている、出典のあるコンテキストは証拠のステータスを保ったまま残します。矛盾を記録し、裏付けのない過去の主張にはラベルを付け、観測済みの事実として引き継がないようにします。

5. 検証して報告する

• すべての引用を調査済みのスナップショットの証拠と照合し、裏付けのない主張を削除します。ソースを再確認するのは、ソースが変更された場合、または以前の調査で主張が立証されていない場合に限ります。
• 重要な動作がどのように検出、実行、永続化、およびデプロイされるかを、全体像で説明できていることを確認します。
• 抽象化レベルが混在していないこと、文章と図で名称が一貫していることを確認します。
• スナップショットが証拠に基づいており有用な場合は DOCUMENTED を、トポロジーの重要な部分が不明なままの場合は INCONCLUSIVE を、リポジトリの識別情報、対象範囲、または出力先を安全に確定できない場合は BLOCKED を使用します。

セルフチェック

• 返却前に整合性を確認します。 項目ごとの証拠、要件の網羅性、矛盾、対象範囲、判定、および該当するクリーンアップを確認します。報告書または許可された成果物を修正します。有効な証拠を再利用し、リポジトリを自動的に再スキャンしたり、成功済みのコマンドを再実行したりしないでください。関連する変更、失敗、または未解決の証拠がある場合にのみ、確認を繰り返します。残っている不足点は明示します。

出力契約

ユーザーの言語で、次の順序で報告します。5つのフィールドをすべて保持し、各事実は一度だけ記載します。結果が少ない場合は、各フィールドを1行で記載できます。空の表は省略し、リンク先の成果物はコピーしないでください。

1. 結果： スキル固有の判定と、裏付けのある成果。
2. スコープ： レビューまたは変更した範囲、除外事項、ベースライン、および重要な前提。
3. エビデンス： 以下のスキル固有のフィールドを記載します。事実、推論、未検証の主張を区別してください。成果物へのリンクを記載し、必要に応じて表を使用してください。
4. 検証： チェックと結果、確認できないエビデンス、該当するクリーンアップや外部状態。
5. 完了： Checklist: X/Y complete。Incomplete: None、または各 UNPROVEN 項目について、その理由、成果への影響、具体的な次のアクションを記載します。残存リスクと必要な判断事項も記載してください。

スキル固有のエビデンス： 成果物のパスとスナップショットの識別情報（リモート、ブランチ、HEAD、ワークツリー、日付）。マッピングしたコンテキスト、モジュール、ランタイム／デプロイ、データ／インターフェース、所有者、重要なフロー。変更したセクション／図、およびランタイム、組織、外部での確認が必要な主張や領域について、ステータス、確認したエビデンス、具体的な次のアクションを特定してください。