authoring-architecture-doc

authoring-architecture-doc — SKILL.md

バリアント： 標準 · 使用する場面： 承認済み PRD をもとにシステム全体のアーキテクチャ文書を作成し、新しいエンジニアがシステムを理解でき、機能の技術設計をその中に位置づけられる品質基準を満たす場合です。

概要

このスキルは、優れたシステム全体のアーキテクチャ文書を作成するための 方法、つまり作成者が適用する判断を扱います。セクション一覧を示すものではありません。3 つの協力要素を前提とします。セクションの 構成 を提供する アーキテクチャ文書テンプレートツール、単独で使用する意思決定記録の形式を提供する ADR テンプレートツール、そして各選択を根拠や確立された実践に基づいて行うための 詳細調査機能 です。作成者に渡されるのは、承認済み PRD と製品の方向性（スコープ、ペルソナ、非機能目標）であり、それを 具体化 します。汎用的な定型文で済ませてはいけません。対象となるのは システム全体 です。システム全体の基盤となるコンポーネント、トポロジー、境界、技術、NFR の実現方法を扱います。達成すべき基準は、新しいエンジニアが構造と主要な決定の 理由 を理解でき、機能の技術設計をその中に位置づけられることです。

使用する場面

• 承認済み PRD をもとに、システムまたは製品の新しいアーキテクチャ文書を作成する場合。
• 製品の方向性が簡潔な場合に、製品規模に合わせてシステム全体のアーキテクチャへと展開する場合。
• 調査に基づき、意思決定を網羅した内容でアーキテクチャ文書のテンプレートを埋め、主要な決定をリンクされた ADR ファイルとして記録する場合。

次の場合は使用しないでください：

• 完成済みのアーキテクチャ文書をレビューまたは評価する場合 → 専用レビュアーである reviewing-architecture-doc を使用してください。汎用の design-review は使用しないでください（アーキテクチャ文書の成果物は対象外です）。
• 単一機能 の実装を設計する場合 → 技術設計（TDD）スキルを使用してください。より低い抽象度を扱い、この文書を参照します。
• ワイヤー契約（すべてのエンドポイント）を規定する場合 → API 仕様スキルを使用してください。永続化モデル（すべてのテーブル）を規定する場合 → データモデルスキルを使用してください。この文書では、主要なサービスインターフェースとデータストアを 構造的に 示しますが、網羅的には扱いません。
• アーキテクチャ文書を必要としない、1 行のメモや些細な変更の場合。

入力

計画から渡される すべての文書、つまり depends_on セット（この文書に情報を提供すると発見プロセスで判断された上流文書）を読み、文書の内容をそれらにたどれるようにしてください。入力が固定されていると想定してはいけません。このスキルが挙げる一般的な上流文書は、手法のガイダンスであり、受け取る文書の上限ではありません。自己完結させてください。実際に受け取ったコンテキストが何であれ、それをもとに文書を作成します。想定される情報提供文書がない場合は、手元にある情報で進め、補うために捏造するのではなく、その不足を明示的な前提として示してください。また、文書をテンプレートの穴埋めにとどめず、包括的かつ網羅的にするため、利用可能な場合は 調査機能（deep-research）を使用してください。

機能のコンテキスト（提供された場合）： 呼び出し元から capability_record（capability-map.yaml product_capabilities のレコード）が渡された場合は、ステップ 1 の前に読み込んでください。これはスコープの境界を定めます。owns = 対象として扱うエンティティ、refs = 参照するが所有しないエンティティ、publishes／consumes = 表面化させるイベント、entry_points／exit_points = ユーザーの入口と出口、has_ui／has_api／has_persistence = 該当するサーフェスです。存在する場合は、厳格な制約として扱い、定義された境界の外に逸脱しないでください。

ワークフロー

Step 1: テンプレートツールの構成を使用する — アウトラインを独自に作成しない

アーキテクチャ文書テンプレートツール（包括版）からセクション構成を取得し、ADR テンプレートツールから単独の意思決定記録の形式を取得してください。ここでセクション一覧を言い換えたり、改めて作成したりしないでください。このスキルが提供するのは、各セクションを適切に埋める方法です。テンプレートが利用できない場合は、包括的なアーキテクチャ構成（依頼して作成してもらうか、標準的なアーキテクチャ文書のセクション構成を使用）と標準的な ADR の形式を用意してから、先に進んでください。

すべての能力レコードが注入されている場合は、能力の一覧全体をコンポーネント分解に使用し、depends_on DAG を依存関係図の入力として使用してください。分類フィールド（scale、security、infrastructure）を NFR の枠組みに使用してください。

Step 2: PRD と方向性を読み込み、ギャップを見つけ、詳細化する

承認済みの PRD とプロダクトの方向性を読んでください。草案の作成前に、知識のギャップを埋めてください — スコープに必要な実際のコンポーネント、外部依存関係、実際に使用されているスタック、PRD が定める NFR の目標を確認します。すべてのコンポーネント、境界、意思決定は、汎用的なテンプレートの穴埋めではなく、このプロダクトに根拠を持つ必要があります。入力情報が乏しい場合は、暗黙のうちに汎用的な内容で補わず、前提を明示してください（未解決の質問または明記した前提として）。

Step 3: 調査を行い、確立された実践に基づいて各選択を根拠付ける

確立されたアーキテクチャの実践（C4 などの定評ある文書化モデル、広く知られたリファレンスアーキテクチャ、プロジェクトで実際に使用されているスタックなど）に基づいて構成を定めるため、詳細な調査を行ってください。独自に考案するのではなく、特定のドメインと候補技術を調査してください。「アーキテクチャ全般」を調べるのではありません。調査機能が利用できない場合、トポロジー、ベンチマーク、根拠を捏造しないでください — 調査していない選択は、検証が必要な前提として明記してください。

ステップ 4：セクションごとの手法を適用する（見出しに加える内容）

テンプレートの各セクションを、次の手法に沿って記入します。

• まず境界を定めます。 コンポーネントを説明する前に、スコープを図示します。対象に含まれるもの、明示的に対象外となるもの（その代わりに誰が担当するかを含む）、アクター、およびすべての外部依存関係を列挙し、それぞれが提供するものを一行で説明します。境界は、新しい読者が最初に知る必要のあることです。
• ステークホルダーと関心事（網羅性の軸）。 ステークホルダーと、それぞれが持ち込む関心事（ISO/IEC/IEEE 42010）を特定し、名前を挙げたすべての関心事が、後続のセクションまたはビューのいずれかで扱われていることを確認します。これが、文書が関心事の一覧と照らして確認できる網羅性の基準であり、感覚に頼らずに済みます。規模に応じて調整します。小規模なプロダクトならステークホルダーや関心事も少なくて構いません。重要なのは、必須のマトリクスを作ることではなく、「名前を挙げた関心事を一つも未対応のまま残さない」ことです。
• 各コンポーネントに責任を一つ。 読者が後で目にする主要なコンポーネントやサービスはすべて、一度だけ名前を挙げ、単一の責任と種類（サービス／データストア／クライアント／ワーカー／キュー）を示します。後続の説明に、説明されていないボックスを残しません。
• 矢印ごとにプロトコルを示し、図と説明を一致させます。 トポロジーでは、どのコンポーネントがどのコンポーネントと、どの方向に、どの通信方式（同期リクエスト／レスポンスか、非同期イベント／メッセージか）で通信するかを示します。図のすべてのボックスと矢印を本文で説明し、その逆も同様にします。対応する説明のない要素を残しません。実行時のフローが分かりにくい場合に限り、シーケンス図を追加します。
• 境界ごとに障害時の動作を示します。 統合ポイントごとに、そこで何がやり取りされるか（スキーマを本文に直接記述せず、API 仕様／データモデルへのリンクを示す）、通信方式、契約の責任者とバージョン管理方法、および相手側の応答が遅い場合や停止している場合の動作（タイムアウト／リトライ／フォールバック／縮退）を記述します。
• 重要な技術選択には理由を添えます。 読者が疑問に思う、またはアーキテクチャを左右する選択（ランタイム、データストア、メッセージング、ホスティング／フレームワーク）のみを扱い、すべてのライブラリを列挙する必要はありません。各選択について、それが満たす動機（要件または NFR）と、何に優先して選んだかを記載します。「チームの標準」でも、そう明記されていれば問題ありません。
• 各 NFR 目標に実現方法を示します。 目標を定めるのは PRDであり、アーキテクチャが担うのは実現方法です。スケーラビリティ、可用性、セキュリティ、オブザーバビリティ、デプロイメントトポロジーといった各品質目標について、それを満たす仕組みを記述します。仕組みの説明がなく目標を言い換えているだけなら不十分です。目標に結び付かない仕組みは、過剰設計の候補です。重要な目標は、測定可能な品質属性シナリオ（ソース／刺激／成果物／環境／応答／応答測定値）として示します。「1000 rps で p99 < 200ms」のような応答測定値が、テスト可能な制約となります。小規模なシステムなら、通常の文章で十分です。
• オブザーバビリティをシステムの主要な関心事として扱います。 「ログを記録する」だけでは不十分です。本番環境でシステムを診断するオペレーターが使う、システムレベルのシグナル（ゴールデンシグナル、ヘルス／SLO の監視方針、主要なメトリクス／トレース／アラート）を明記します。これはシステム全体の運用方針であり、TDD が扱う単一機能のシグナルとは別のものです。
• 品質属性間のトレードオフに名前を付けます。 属性同士が衝突する場合（レイテンシと一貫性、コストと可用性、セキュリティとパフォーマンスなど）は、そのトレードオフを示し、どちらを選んだか、またその理由を記述します（ATAM の感度分析／トレードオフの枠組み）。アーキテクチャが明らかに直面している緊張関係に触れていない場合は、不足があります。
• 事実に基づき、作り上げず、不明点を明らかにします。 実際のプロダクトと技術スタックを反映します。不明点は答えを作り上げず、明示的な前提または未解決の質問として示します。

Step 5: 重要な判断を、それぞれ独立したリンク付きADRとして記録する（中核となる仕組み）

アーキテクチャ上の判断を本文中に埋め込んではいけません。 重要な判断はそれぞれ、独立したADRファイル（ADRテンプレートの「Status / Context / Decision / Alternatives / Consequences」に沿って、1ファイルにつき1つの判断）に記録し、アーキテクチャ文書には各ADRへのリンクを含む概要インデックスだけを載せます。この規律を守ります。

• 1ファイルにつき1つの判断。 2つの判断を1つの記録にまとめるのは誤りです。分割してください。
• 根拠と代替案を明記する。 各判断はドライバー（要件またはNFR）に結び付け、トレードオフの結果、採用されなかった現実的な代替案を示します。検討した代替案がない判断は、十分に検討されていないように見えます。
• 承認後は変更しない。 判断を変更する場合は、以前のADRを置き換える新しいADRを作成します（以前のADRのStatusは「superseded by …」に変更します）。承認済みの記録を書き換えてはいけません。これにより、インデックスは追記のみの履歴を忠実に保持できます。
• インデックスとファイルの整合性を保つ。 インデックスに載せた判断には、すべて有効なADRリンクが必要です。承認済みのADRはすべてインデックスに掲載します。インデックスとの不整合は欠陥です。

Step 6: 承認済みアーキテクチャ文書を改訂する（差分による変更）

アーキテクチャ文書は生きた文書です。全面的な書き直しではなく、差分によって進化させます。承認済み文書と変更要求（新たな重要な判断、コンポーネントの分割／統合、依存関係の置き換え、NFRの目標値の変更など）を受け取った場合、文書全体を再生成してはいけません。次の方法に従います。

• 変更範囲を、影響を受ける判断／コンポーネント／境界／NFRの実現方法／横断的な方針に絞り、安定したセクションID・判断IDとレビュー履歴を保持したまま、該当箇所を直接編集します。
• 判断を変更するときは、直接編集せず、必ず置き換えます。 判断を変更する場合は、以前のADRを置き換える新しいADRを作成します（以前のADRのStatusを「superseded by NNNN」に変更し、「supersedes NNNN」の相互参照注記を追加）。新しいADRと置き換え済みのStatusが反映されるよう、判断インデックスを更新します。承認済みADRの書き換えは、改訂における最も重大な欠陥です。履歴を破壊してしまいます。
• 内部の連鎖を再確認します。 トポロジーは引き続き成り立っていますか。図と本文は一致していますか。NFRの実現方法は引き続き目標を満たしていますか。影響を受ける境界の障害時の挙動は、引き続き明記されていますか。
• 文書自体のバージョンと変更履歴を更新します（誰が／いつ／何を／なぜ。作成した文書のVersionであり、このスキルのsemverとは別です）。
• 下流に広がる影響を分析します。 アーキテクチャ文書特有の影響範囲は、変更後の構造内に位置付けられた機能ごとのテクニカルデザイン文書群まで及びます（それぞれ個別に改訂が必要になる場合があります）。また、変更が影響するapi-spec／data-model／deployment／release-runbookにも及びます。上流については、要件に起因する変更の場合、まずPRD／product-directionを改訂します（spec→plan→implの順序）。影響を受ける下流文書をすべて明示し、古い状態のまま黙って放置してはいけません。

ステップ 7：引き渡す前にユーザビリティ基準に照らして自己チェックする

以下がすべて満たされていることを確認します（これは専任レビュー担当の reviewing-architecture-doc が適用する基準です。10 項目の条件は、このチェックと一元管理されています）。

1. 構造を把握でき、境界と懸念事項が網羅されている — 新しいエンジニアがコンテキスト、コンポーネント、トポロジーを読んで、システムとは何か、各部分がどのように連携するかを説明できます。境界（内外と所有者）が明示され、すべての外部依存関係が列挙され、特定されたすべてのステークホルダーの懸念事項に、いずれかのセクションまたはビューで対応しています。
2. コンポーネントと境界に責務が明記されている — 主要なコンポーネントとすべての統合境界に名前が付けられ、責務またはその境界を越えるものが明記されています。説明のない箱や継ぎ目があれば不合格です。システム全体のレベルを保ちます（機能の TDD の詳細や、API 仕様／データモデルの列挙には踏み込みません）。
3. 図と説明文が一致している — すべての箱と矢印が説明文に登場し、その逆も同様です。図は単独で読めるようにし、重要な場合は実行時／デプロイメントのビューを含めます。
4. 重要な決定は、リンクされた独立した ADR として作成され、インデックス化され、変更されない — 重要な決定はそれぞれ独自の ADR ファイルとして作成され（1 ファイルにつき 1 件）、インデックスに有効なリンクとともに掲載されています。インデックスとファイルの内容は一致しています。承認済みの ADR は書き換えません（変更時は後続の ADR で置き換えます）。記録全体を文書内に埋め込む、リンク先のないインデックスを作る、承認済み ADR を書き換えるといった場合は不合格です。
5. 重要な技術選択に根拠が示されている — それぞれに、選択理由（判断の根拠と、採用案に劣ると判断した実際の代替案）が記載されています。重要な選択に根拠がなければ不合格です。
6. 各 NFR の目標に実現方法があり、トレードオフが明示されている — PRD に記載されている品質目標すべてに、文書化された実現メカニズムがあります（重要な場合は測定可能なシナリオを含めます）。品質特性間のトレードオフが明示され、解決されています。目標を言い換えただけで実現メカニズムがなければ不合格です。
7. システムに該当する範囲で、横断的な懸念事項に対応している — 統合境界ごとのレジリエンス方針、セキュリティ（信頼境界／認証／シークレット）、機微データの流れに関するプライバシー、システムレベルの可観測性戦略が含まれています。
8. 要件／ASR を網羅している — アーキテクチャ上重要な要件すべてに、それを実現する構造または決定が対応し、孤立した構造がありません。後続工程で利用でき、機能の技術設計を担当する人が、作成者に尋ねずに自分の設計をアーキテクチャ内に位置付けられます。
9. 定型文ではなく、根拠に基づいている。前提が明示され、実態と一致している — 構造と技術選択は実際のプロダクトを反映し、確立された実践に基づいています。不明点は前提または未解決の質問として明らかにします（黙って既定値を適用したり、捏造したりしません）。システムの実態に関する記述は、実際のコード／トポロジーと一致しています。
10. （改訂のみ）変更範囲が適切に限定されている — 変更依頼では、差分の範囲を限定して既存箇所を編集し、変更された決定は後続の決定で置き換え（インデックスも一致させ）、文書のバージョンと変更履歴を更新し、下流への影響（依存する TDD、API 仕様／データモデル／デプロイメント）を明示します。グリーンフィールドでの初回構築では対象外です。

すべての条件に比例原則を適用します。 機能が少ないプロダクトでは、存在しないものを適切に省略できます（コンポーネントが 1 つ → トポロジーなし。単一プロセス → デプロイメントビューなし。厳しい NFR なし → §6 は簡潔に。初稿 → 変更履歴なし）。省略できない最低条件は、捏造しないこと、境界と外部要素一式を明示すること、システム全体のレベルを保つこと、承認済み ADR を書き換えないこと、そして実際に存在するすべての目標に実現方法を示すことです。

ルール

厳守事項（決して違反しないこと）：

• 重複させず、組み合わせて構成します。 セクション構成はテンプレートツールから、ADR の形は ADR テンプレートツールから採用します。このスキルは、それらを埋めるための手法です。競合するアウトラインを貼り付けてはいけません。
• 決定は埋め込まず、リンクします。 重要な決定はすべて、独立した ADR ファイルにします。ドキュメントにはリンク付きの索引のみを載せます。決定記録全体をインラインで記載してはいけません。
• コンポーネントごとに責務を一つ、ADR ごとに決定を一つにします。 説明のないボックスを作ってはいけません。一つの記録に二つの決定をまとめてはいけません。
• 重要な選択には根拠を示します。 根拠（採用理由と代替案）のない重要な技術選択は、未完了です。
• すべての NFR 目標を実現します。 目標を定めるのは PRD です。実現手段を示さずに目標を言い換えるだけでは不十分です。ここで目標を設定してはいけません。
• システム全体の視点を保ちます。 主要なデータストアとサービスインターフェースを構造的に示します。すべてのエンドポイント（API 仕様）やテーブル（データモデル）を列挙したり、特定機能の実装設計（技術設計）に踏み込んだりしてはいけません。
• 決して捏造しません。 セクションを埋めるために、トポロジー、ベンチマーク、ベンダーの主張、根拠を作り上げてはいけません。不明点は、検証が必要な仮定として明示します。仕組みを捏造するより、正直に不足を認める方が適切です。
• 与えられた入力を具体化します。 詳細は PRD と調査結果から得るものであり、一般的な定型文を使ってはいけません。
• 図と説明文の整合性を保ちます。 図の各要素は説明文にも記載し、その逆も同様です。
• 書き直さず、差分を加えて旧版に優先させます。 変更要求では差分の範囲を特定して、既存の箇所を編集します。決定は新しい ADR で置き換えます（承認済みの ADR は決して編集しません）。索引を同期し、ドキュメントのバージョンと変更履歴を更新し、依存する技術設計ドキュメントと API 仕様／データモデル／デプロイメントへの波及を明示します。
• ケイパビリティの境界（capability_record が提供されている場合）。 ドキュメントの出力範囲は、そのレコードの境界内に限定します。境界外の内容を出力すること（refs エンティティを自分の担当範囲であるかのように扱う、exit_point を越えるフローを設計するなど）は、仕様にない内容を捏造するのと同等のスコープ違反です。

推奨事項（上書き可能）：

• 「包括的」は出力の目指す水準を示しますが、比例性を保ちます。必要な決定事項とカバー範囲の最低限を満たすことが重要であり、文字数は重要ではありません。薄いプロダクトでは、不要なセクションを正当にまとめられます（コンポーネントが一つ、メッセージングなし、単純なデプロイメントなど）。
• 現在の媒体では、すべてをテキストで表現します。説明文、コンポーネント／コンテナ／デプロイメントの図、決定事項の索引テーブルを使います。将来、設計ツールのバックエンドに移行しても、変わるのは媒体だけであり、この手法や基準は変わりません。
• 構造を伝えるために必要な最小限の図を優先します（通常、コンテキスト図とコンテナ／トポロジー図で十分です）。実行時の動作が分かりにくい場合に限り、シーケンス図を追加します。

注意点

• 決定の埋め込み。 コンテキスト／代替案／結果をインラインにすべて貼り付け、ADR にリンクしないと、各決定に個別にアクセスできなくなり、ドキュメントが肥大化します。索引を作り、独立した ADR ファイルにリンクしてください。
• 承認済み ADR の編集。 承認済みの決定を書き換えると履歴が失われます。代わりに、それを置き換える新しい ADR を作成してください。
• 説明のないボックス。 図にコンポーネントがあるのに責務が説明されていない場合、コンポーネントのセクションで一度は説明してください。
• 目標の言い換え。 PRD の「99.9% の稼働率」を冗長化／フェイルオーバーの仕組みなしにドキュメントへコピーするのは、目標の言い換えであり、実現ではありません。すべての目標について、実現方法を示してください。
• 薄いプロダクトの過剰設計。 CLI ツールが使うことのないメッセージバス、キャッシュ層、三つの環境を捏造してはいけません。実際のスコープに合わせ、どの目標にも寄与しない仕組みは警告サインとして扱ってください。
• 視点の逸脱。 「この関数があのクラスを呼び出す」（機能単位の TDD）や「GET /v1/users は…を返す」（API 仕様）に踏み込んではいけません。システム全体の視点を保ち、インターフェースを示して契約にリンクしてください。
• 図と説明文の不整合。 説明文にはあるのに図にはないワーカー（またはその逆）があってはいけません。両者の内容を一致させてください。

アンチパターン

• 「概要は自分で書きます。」 テンプレートツールの内容と重複します。構成はテンプレートツールから、ADRの形式はADRテンプレートツールから引き継いでください。
• 「ここに意思決定を列挙するセクションを設けます。」 独立したリンク付きADRにすべき内容を埋め込んでいます。意思決定は1つずつファイルにまとめ、索引化してリンクしてください。
• 「技術スタックは何でもいいので、妥当なものを選びます。」 重要な選択に根拠がありません。それぞれに判断要因と、実際の代替案が必要です。実際のプロダクトに基づいて検討してください。
• 「PRDにp99で100msとあるので、そのまま書きます。」 目標を言い直すだけでは実現方法を示したことになりません。目標を達成する仕組みを記録してください。
• 「念のため、キューとキャッシュを追加します。」 仮定上のニーズに備えた先回りの構造です。プロダクトの実際の範囲に合わせて設計してください。
• 「調査は省きます。アーキテクチャは分かっています。」 調査は、アーキテクチャ理論ではなく、このプロダクトのトポロジーと技術を確立された実践に基づいて定めるためのものです。
• 「各機能の実装方法まで詳しく説明します。」 それは、より詳細な技術設計ドキュメントの役割です。このドキュメントでは、そうしたドキュメントが準拠するシステム全体の構造を定義します。

出力

Step 7 の使いやすさの基準（把握しやすい構造と懸念事項の網羅、責任範囲を明示したコンポーネントと境界、図と説明の整合性、独立したリンク付きの不変なADRとして記録・索引化され、内容の同期も保たれた重要な意思決定、根拠のある技術選択、各NFR目標の実現方法と明示されたトレードオフ、横断的な懸念事項への対応、ASRの網羅、定型文に頼らず現実と一貫した内容、差分による修正が可能）を満たすシステム全体のアーキテクチャドキュメントと、ドキュメントの重要な意思決定の索引からリンクされる独立したADRファイル一式です。抽象的な利用者には、システム内で開発するすべてのエンジニア、このドキュメントの範囲内で作成される下流の機能ごとの技術設計ドキュメント、そして同じ10条件の基準を適用する reviewing-architecture-doc が含まれます。ドキュメントの構成はテンプレートツールが定め、このスキルは内容の品質と意思決定を記録する仕組みを提供します。

関連項目

• アーキテクチャドキュメントのテンプレートツール（コンテンツ／テンプレートのゲートウェイなど）— このスキルで内容を埋める、包括的なアーキテクチャセクションの構成を提供します。
• ADRテンプレートツール — リンク先の意思決定ファイルで使う、独立した意思決定記録の形式（Status / Context / Decision / Alternatives / Consequences）を提供します。意思決定を作成するための別個のスキルはありません。この形式は定型化されています。
• ディープリサーチ機能 — 構造と技術選択の根拠を、確立された実践と証拠に基づいて示します。
• 上流のPRDとプロダクトの方向性 — このスキルが詳細化する入力コンテキスト（範囲、ペルソナ、NFRの目標）です。白紙の状態から始めるものではありません。
• 下流の機能ごとの技術設計ドキュメント — このアーキテクチャ内での位置付けを明確にする利用者です。
• reviewing-architecture-doc — このスキルのStep 7の基準（自己チェックと一元管理された10条件のゲート）を適用し、VERDICT: approve|revise を出力する専任のレビュー担当です。完成したアーキテクチャドキュメントとリンク先のADRファイルは、ここに回します。汎用の design-review には回しません。これはアーキテクチャドキュメントの成果物を対象外としており、一般的な設計ドキュメント、RFC、独立したADR、仕様書、計画書のゲートは引き続き担います。

段階的な開示

• references/architecture-method.md — 境界と懸念事項／分解とトポロジー／図の同期／ADRの仕組み／NFRの実現と測定可能なシナリオ／可観測性とレジリエンスに関する詳細です（該当セクションを埋める際に読み込みます）。
• references/amend.md — supersede規約に基づく修正手順、索引の同期、下流への広範な波及について説明します（承認済みドキュメントを修正する際に読み込みます）。
• references/sources.md — 手法、ADRの仕組み、品質基準の調査根拠です（指針の出典を監査する場合にのみ読み込みます）。

本文の分量

• description は 1,024 文字以下にしてください（agentskills.io の上限）。
• 本文は約 500 行／5,000 トークンを目安にしてください（品質を優先するソフトな目標です。700 行／7,000 トークンを継続的に超える場合は指摘してください）。
• 大量のコンテンツは references/ に置き、必要に応じて読み込みます。

変更履歴

• 1.3.0（2026-06-21）— capability_record のコンテキスト注入：呼び出し元から注入されるすべての capability レコード（Step 1 で消費。全リストからのコンポーネント分解、depends_on の DAG、分類フィールドを含む）を任意で追加；capability_boundary ルールを追加；本文の分量目標を緩和。レコードが注入されない場合は適切にフォールバックします。
• 1.2.0（2026-06-14）— 本番環境向けの全面的な再構成：反復・修正方式（Step 6 — 差分＋ADR の置き換え＋下位への幅広い波及）、ステークホルダー／関心事項の網羅性を担保する基盤、測定可能な品質属性シナリオ、第一級のシステム課題としての可観測性、品質属性間のトレードオフを追加；新たに専用のレビュアー reviewing-architecture-doc と単一の基準を共有する 10 条件の基準に合わせて、セルフチェック（Step 7）を拡張；レビューをツインに振り分け（design-review は architecture-doc の成果物から切り離されています）。追加のみの変更です。従来の手法（境界優先、単一責務のコンポーネント、単独リンク型 ADR の仕組み、重要な選択の正当化、NFR ごとの実現、図と説明文の同期、詳細度のルール）に変更はありません。
• 1.1.0（2026-06-04）— 以前のレビュー済みリリース。