ln-75-architecture-diagram-builder

アーキテクチャ図の作成

目標： 現在または提案中のアーキテクチャを伝えるために必要な、理解しやすく、根拠に裏付けられた最小限の図を作成します。承認済みのアーキテクチャ文書のみを変更し、関係性を作り上げたり、ビジュアルデザインを行ったり、文章による根拠を置き換えたり、適合性を監査したり、実装を編集したりしないでください。

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

ツールの使い分け

必要なもの	優先する機能	代替手段
アーキテクチャの根拠	リポジトリ内のファイル、実行時の配線、IaC、契約、承認済み成果物	UNVERIFIED ラベルを付けたユーザー提供のモデル
関係性の追跡	言語インテリジェンス、依存関係ツール、対象を絞った検索	プロデューサー、コンシューマー、登録箇所の直接確認
図の形式	リポジトリ内の既存規約とレンダラー	Markdown 内の Mermaid、次にプレーンな ASCII
構文検証	リポジトリのレンダラー、パーサー、プレビュー	コードフェンス、識別子、関係性の手動確認
ドキュメントの変更	承認済みの図の成果物への最小限のパッチ	パスまたは根拠の境界が安全でない場合は BLOCKED を返す

図はモデルを伝えるものです。現在の状態については、実行可能な動作が引き続き正とされます。現状、目標、移行の各ビューを明確に区別してください。

成果物のルール

• 既存の図の規約を再利用するか、docs/architecture/diagrams/<view>.md を使用してください。
• レビュー可能なテキスト形式のソースには Mermaid を含む Markdown を優先し、Mermaid がサポートされていない場合は ASCII を使用してください。
• 静的な構造については、求められた問いに答えるコンテキスト、コンテナ、コンポーネントのレベルを選択してください。既存のコンテキスト図で十分な場合、前提となる概要図を作成しないでください。
• バージョン管理でレビューできる状態に図のソースを保ってください。
• 1 つの図に複数の無関係な説明が必要な場合は、ビューを分割してください。
• 色だけで意味を伝えないでください。
• 安定した要素識別子と簡潔な表示ラベルを使用し、修正差分をレビューしやすくしてください。
• ノードや関係性が煩雑にならないよう、詳細な根拠は図の近くに記載してください。
• 理解しやすい既存の記法を維持してください。新しい記法は、対象者の問いにより適切に答えられる場合に限り導入してください。

チェックリスト

1. 図の契約を確立する

• 対象者、問い、現状または目標の状態、範囲、承認済みの保存先、必要な記法を確定します。
• リポジトリの指示、関連するアーキテクチャ成果物、既存の図の規約を読みます。
• 有用な最小限のビューを選び、関係性を明確にしない図は採用しません。
• 根拠の境界を定め、ユーザー提供の要素や提案中の要素には別途ラベルを付けます。
• 承認済みのアーキテクチャ図ドキュメント以外は変更せず、作業中は読み取り専用に保ちます。

2. アーキテクチャモデルを構築する

• 関連する人、システム、アプリケーション／データストア（C4 を使用する場合は C4 コンテナー）、コンポーネント、キュー、外部依存関係を特定します。論理コンテナーと、OS／コンテナーランタイムのデプロイ単位を区別します。
• 各要素について、責任、種類、意思決定に関わる場合はテクノロジー、判明している場合は所有者、現状／目標のステータスを記録します。
• 該当する場合、関係の方向、ラベル、プロトコルまたはデータ、同期性、信頼境界またはネットワーク境界を明確にします。
• 現状のルート、ハンドラー、ジョブ、プラグイン、コンシューマーを含める前に、実行時の検出と登録を追跡します。
• 不確かな要素や関係は、見栄えを整えるために補完せず、UNKNOWN として記します。

3. ビューを選択して描画する

• 読者がシステムの範囲と外部アクターを把握する必要がある場合は、システムコンテキストビューを作成します。
• 責任、デプロイ可能性、ストア、運用トポロジーを示すコンテナビューまたはデプロイメントビューを作成します。対象読者の疑問に関係する場合は、ノード、リージョン、ネットワーク、スケーリング、フェイルオーバーを含めます。
• 複雑な領域の内部境界が理解に影響する場合に限り、コンポーネントビューを作成します。
• 重要な成功、失敗、再試行、タイムアウト、復旧、移行のやり取りには、シーケンスビューまたは動的ビューを作成します。
• セキュリティ、プライバシー、データレジデンシー、システムオブレコードに関する疑問への対応に必要な場合は、データフローまたは信頼境界のビューを作成します。
• 明示的かつ必要な例外がない限り、1 つのビューに異なる抽象化レベルを混在させないでください。

4. 図だけで内容が分かるようにする

• タイトル、図の種類、対象範囲、現状／目標の表示、対象読者、観察日または提案日を追加します。
• 形状、色、線種、略語、不確実性を示すマーカーの凡例を追加します。
• すべての関係に意図またはデータのラベルを付けます。汎用的な矢印や説明のない頭字語は避けます。
• コード、コントラクト、共有アーキテクチャドキュメントと一貫した名称を使用します。
• 現状に関する主張を追跡するのに十分な、簡潔な根拠の注記またはリンクを追加します。

5. 検証して報告する

• リポジトリのレンダラーで構文を検証するか、構文を手作業で完全に確認します。
• プレビューが利用できる場合は、レンダリング後の読みやすさを確認します。ラベルを小さくするのではなく、情報過多のビューを分割します。レンダラーがない場合、視覚的な読みやすさは UNPROVEN と記録します。構文の手作業による確認は、レンダリングの証明にはなりません。
• 現状の要素と関係を実装上の根拠と照合し、目標状態の要素を明示された提案または明確にラベル付けされた仮定と照合します。
• 図が有効で、対象範囲が明確で、根拠が示されている場合は READY を使用します。重要な関係が不明なままの場合は INCONCLUSIVE を、対象範囲、根拠、形式、出力先のいずれかによって信頼できる図の作成が妨げられる場合は BLOCKED を使用します。

セルフチェック

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

出力仕様

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

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

スキル固有の根拠： 成果物のパス、各ビューの現在／目標状態、想定される質問、根拠となる情報。構文／レンダリングの検証と、現在の状態に関する関係性のチェック、未知の関係性、および解釈に影響するレンダリング上の制約を報告してください。