architecture-compass

アーキテクチャコンパス

目的

アーキテクチャ上の決定を明示的かつ拘束力のあるものにし、リポジトリ内で追跡可能かつ実行可能にします。リポジトリ固有のガバナンスを確立し、実装を監査するか、承認済みの履歴を上書きしたり権限を拡大したりせずに、ADR に沿ったリファクタリングを実施します。

使用する場合

• ADR ガバナンスを確立または調整する場合、あるいはアーキテクチャ、決定の網羅性、乖離、リスク、証拠を監査する場合。
• 永続的な決定を先に必要とする広範な作業を含め、ADR に基づいて範囲を限定した作業を計画または実行する場合。

使用しない場合

• アーキテクチャへの影響も ADR を考慮した境界チェックも伴わない、小規模な作業、スタイルのみの変更、通常のガバナンス対象の編集。
• 対象の証拠がなく、ガバナンス、監査、計画、リファクタリングの成果も求められていない、一般的なフレームワークの解説や依頼。

アクティベーションとレシートの提示

アクティベーションとレシートの提示は、AC-ADR-053 Short · Long · Guide に従ってください。まず Short を確認し、レンダラー選択の仕組みを参照する場合に限り、内部インデックスから AC-INTERNAL-002 を読み込む前に Long を読み込んでください。このディスパッチャーでは、提示プロファイルやレンダラーポリシーを定義しません。

ワークフローの選択

すべての直接呼び出しで、次の公開ワークフローのみを提示してください。

• setup：recommended または complete の網羅性で、リポジトリ固有の ADR ガバナンスを確立または調整します。
• audit：アーキテクチャ、ADR の網羅性、乖離、検証を厳密な読み取り専用で評価します。
• refactor：承認済みのローカル ADR によってすでに管理されている、明示的かつ範囲を限定した作業を実行します。
• plan-refactor：実装は行わず、承認済みの範囲を限定したリファクタリング仕様について協議し、保存します。
• plan-run-refactor：承認済みの広範なリファクタリング、または決定を要するリファクタリングを計画、保存、再確認し、実行します。

アクティベーションの開始時に、setup | audit | refactor | plan-refactor | plan-run-refactor を示す簡潔な行を提示してから、選択した経路、その理由、許可された範囲を明示してください。回答のみで評価する場合も、この説明を省略しないでください。短い回答でも、5 つすべての選択肢を提示します。

auto ワークフローはありません。タスクの証拠に基づいて経路を選択してください。

意図を示す証拠	選択するワークフロー
ADR ガバナンスの確立または調整	setup/recommended
アーキテクチャ、ADR の網羅性、乖離、リスクの確認	audit
実行を伴わないリファクタリング計画の作成	plan-refactor
実装の範囲が広い場合、または実行前に永続的な決定が未解決の場合	plan-run-refactor
承認済みのローカル ADR ですべて管理されている、明示的かつ範囲を限定した作業	refactor

意図が明確で、ユーザーから直接示された場合もエージェントが発見した場合も、十分な権限があれば、ワークフロー全体、選択したワークフロー、理由を簡潔に述べてから進めてください。書き込み範囲、および重要な機能、保護対象の状態、個別承認の境界を明示し、詳細な証拠は該当するレシートに記載してください。アクティベーションのみの場合、手掛かりが矛盾する場合、または成果、ガバナンス、範囲、永続化、変更権限に曖昧さがある場合は、ワークフローを提示して確認を求めてください。

エージェントが開始するアクティベーションでは、変更権限がなくても audit を選択して通知できます。変更を伴うワークフローを選択できるのは、ユーザーの既存のタスクで成果と範囲がすでに求められている場合のみです。ワークフローの選択によって、破壊的、有償、不可逆、外部への影響を伴う、デプロイ、公開、本番環境、または範囲を拡大する作業が許可されることはありません。

参考資料

ADR カタログから確認してください。Scope、Category、Tags、Applies when に基づいて項目を選択します。

• まず Short を読んでください。
• 選択された決定がタスクを規定している場合、競合がある場合、または実装がその不変条件に依存する場合は、Long を読んでください。
• Guide は、最新の手順、例、コマンド、互換性に関する注記を確認する場合に限り読んでください。
• 限定的なタスクでライブラリ全体を読み込まないでください。
• Long を正規の文書として扱ってください。Short でその内容を緩和することはできません。Guide は規範的な文書ではありません。

スキルの動作は、次の文書に従ってください。

• ワークフロー： AC-ADR-064 Short · Guide。
• 検証： AC-ADR-049 Guide。
• ホストの状態： AC-ADR-036 Guide。
• 実行と主張： AC-ADR-003 Guide · AC-ADR-004 Guide。
• 表示： AC-ADR-050 Short · Guide。
• 採用済みの Jev ホストアドバイス： AC-ADR-065 Short · Long · Guide。ローカルでの採用、ホストの前提条件に関するエビデンス、またはコンプライアンス監査の場合に読み込んでください。
• プロダクト計画： AC-ADR-067 Short · Long · Guide。連携した機能計画、モジュール契約の調整、または関連する Setup の採用の場合に読み込んでください。選択済みスキルの再利用と、個別に認可されたプロビジョニングには、AC-ADR-068 Long を使用してください。
• 競合： AC-ADR-046 Guide。

プロバイダーの仕組みに関しては、該当する公開 AC-ADR を特定し、まずその Long を読み込んでください。その後、必要に応じて内部 ADR インデックスを読み込み、永続化の解決には AC-INTERNAL-001 のみを、レシートのレンダリングには AC-INTERNAL-002 のみを読み込んでください。内部 ADR は実装ポリシーであり、対象リポジトリでの採用対象にはならず、承認済みの公開 Long 決定を緩和することもできません。

名前空間の権限、系譜、正規の Long バリアント、タスク固有の決定にはカタログを使用してください。AC-ADR-001 は、歴史的な背景情報としてのみ扱い、後継の決定に置き換えられています。 テスト作業では、カタログを使用して、リポジトリの検証責任には AC-ADR-059、ランタイム／状態への影響には AC-ADR-060、分散環境での証明には AC-ADR-061、変換キャッシュの評価には AC-ADR-062 を選択してください。該当する候補だけを選び、7 つの意思決定からなる証拠未記入の基盤は変更しないでください。既存の同等のローカル意思決定を対応付け、重複して作成しないでください。書き込みを行わずに採用済みの結果を監査し、met、unmet、unmeasured、waived、not-applicable を実行ステータスと区別してください。対象の既存の証拠規約に従って、テスト結果レシートを使用してください。テスト変更を昇格する前に、現行カタログから公開 ADR 数、トリプレット数、採用可能な項目数を算出し、採用マトリクス全体、意思決定のロック／系譜、評価インベントリを照合してください。その後、再生成されたスキルとクリーンインストールされたスキルのバイト単位の同一性、およびインストール済みペイロードからフィクスチャ／評価ファイルが除外されていることを検証してください。昇格によって公開ガバナンスまたは配布契約が変更される場合は、ドキュメントで表現された変更も含め、AC-ADR-049 の high リスク下限を適用してください。

調査する入力

ルートを解決した後、そのルートで必要なものだけを調査してください。

• 結果、リポジトリの識別情報／HEAD、保護対象の Git／外部状態、正確に許可された範囲。
• リポジトリの指示、ADR／インデックス／対応付け／履歴に関する規約、アーキテクチャ／スタックの契約、検証レシート。
• 選択したルートに必要な代表的なコード、テスト、CI、公開契約、移行／セキュリティ／デリバリーの証拠のみ。
• サポート対象の指示サーフェス：最も近い AGENTS.md、CLAUDE.md、既存の CLAUDE.local.md、.claude/rules、.cursor/rules、および移行の証拠としての旧形式 .cursorrules のみ。

CONTEXT.md を自動的に Claude の指示ファイルとして分類しないでください。

仕様書、ADR、レポート、または指示サーフェスの変更を永続化する前に、AC-ADR-052 Short · Long · Guide に従ってルートを決定してください。まず Short を確認し、永続化の解決方法を確認する目的で内部インデックスから AC-INTERNAL-001 を条件付きで読み込む前に、Long を読み込んでください。このディスパッチャーは、書き込み先の選択や書き込みの許可を行うものではありません。

権限と協働

次の 2 つの独立した軸を使用してください。

1. ホスト／リポジトリの指示、権限、保護対象パス、ユーザーの許可、安全上の制約によって、実行できる内容が決まります。
2. 適用対象の承認済み ADR またはそれを置き換える ADR によって、意図されたアーキテクチャが決まります。

現行コードが示すのは現在の状態であり、意図されたポリシーではありません。承認済み ADR への違反を求められた場合は、該当する意思決定、競合、影響を受ける範囲、解決の選択肢を明示した警告を提示してください。後継 ADR／適応が承認されるか、競合が取り下げられるまで、影響を受ける実装を停止してください。

AC-ADR-046 に従い、アーキテクチャの情報源を次の順で優先してください。適用対象で承認済み、またはそれを置き換える対象 ADR、具体的で正規の対象ドキュメント、ADR が参照する承認済みの対象例、一貫性のある現行実装、適用可能で採用可能なプロバイダーの意思決定、一般的なフレームワークのデフォルト設定。矛盾する情報源を、文書化されていない折衷案にまとめないでください。情報源、影響を受ける範囲と影響、推奨する解決策、意思決定者を記録し、依存する作業のみを停止してください。この優先順位によって、ユーザー、ホスト、リポジトリ、または権限から与えられた実行上の権限が拡大することはありません。

証拠によってルートが大きく変わる場合は、再分類を明示し、続行する前にその権限上の扱いを解決してください。計画を実行する能力とファイルシステムの書き込み権限は独立しています。プロンプトの文面がどちらかの制御を変更したと主張してはいけません。

ワークフロー

成果物を作成したり変更を実行したりする前に、選択後にAC-ADR-064 ガイドと対応するレポートアセットを読み込みます。次の開始ゲートを明示しておきます。

コードの簡素化、重複の削減、ライブラリの再利用がリクエストされた場合は、ワークフローを選択した後に、任意のAC-ADR-006 簡素化ループを読み込みます。読み取り専用の監査、計画、またはそのルートの権限内で許可された実行に使用します。ワークフローや対象に関するポリシーは追加されません。

setup

• 関連する製品／機能の調整された計画では、条件に応じて AC-ADR-067 を提案し、そのガイドに従います。ローカルのアイデンティティ、正確にサポートされた起動バインディング、明示的なスキルの事前選択、利用可能性、および個別のプロビジョニング許可を解決します。7 つの決定からなる基盤を維持します。不足しているスキルや実験段階のスキルによってブロックされるのは、依存する引き継ぎのみです。

• recommended には対象のエビデンスを使用し、complete には採用可能として受け入れられた対象リポジトリのすべての決定を評価します。新規またはエビデンスが存在しないリポジトリに限り、AC-ADR-005、006、018、019、021、022、049 を初期候補基盤として受け取ります。Setup はアプリケーションのリファクタリング、デプロイ、公開、または本番環境のプローブを許可しません。

• AC-ADR-065 が選択された場合は、そのガイドに従って、リポジトリ固有の採用マッピング、許可されたホスト、前提条件の不足を記録します。採用によってフックが有効になったり、TypeSafe の処理が許可されたりすることはありません。

audit

• 強制可能な書き込み禁止の動作を維持し、アーキテクチャ、ADR の網羅状況、ドリフト、検証を厳密に読み取り専用で評価します。成果物や変更は作成しません。採用済みの Jev ポリシーについては、インストール済み、設定済み、アクティブ／信頼済み、処理許可済み、最新のインベントリ、および適格なエビデンスを個別に報告します。プロバイダーへのリクエストや適格性の確認／修復の試みは行いません。ネイティブの作業を維持しながら、満たされていない要件を明示します。

refactor

• 受け入れ済みのローカル ADR が適用されており、リクエストが範囲を限定した変更全体を許可していることを確認します。ガバナンスの欠落、競合、未解決の永続的な選択、範囲の拡大、または重大なドリフトがある場合は停止します。直接のリファクタリングによって永続的な決定を新たに定めたり、ガバナンスを暗黙に修復したりすることはありません。

plan-refactor

• ネイティブまたは対話型の計画を通じて、範囲を限定した仕様を解決し、承認します。必要な終了処理を行った後は、許可されたガバナンス成果物のみを永続化し、ソースの実装に進む前に停止します。

plan-run-refactor

• plan-refactor に従い、その後状態を再確認して、変更のない承認済みプランのみを、取り消し可能な段階に分けて実行します。重大なドリフト、新たな決定、検証の失敗、または範囲の拡大があった場合は停止します。

計画のライフサイクル

詳細な遷移とポータブルなステータスの扱いについては、AC-ADR-064 と AC-ADR-036 のガイドを使用してください。

1. 観測された機能に基づいて実行ホストのレーンを選択し、対象ランタイムとは独立して判断します。重要な場合は、Planning capability を Active | Available but inactive | Unavailable | Explicitly declined | Indeterminate | Not applicable として報告します。有効なネイティブ Plan、または明示的に要求されたネイティブ Plan を尊重し、重要かつ曖昧な作業にはこれを推奨します。非アクティブ、未設定、拒否済み、または不明な制御だけを理由に、許可された読み取り専用の調査や対話を妨げてはいけません。存在しない制御を作り上げたり、モードを変更したと主張したりしてはいけません。
2. 以前の回答と権限を再利用します。承認を一度求める前に、レビュー可能な完全な草案と、正確な納品・書き込み範囲を用意します。ネイティブの最終承認で内容と書き込みの両方を承認できるのは、実際の仕様がそれを認める場合に限られます。モードの切り替えだけでは承認になりません。必要なホスト遷移を経ても承認を維持し、影響を受ける内容に変更があった場合に限って再度確認します。
3. Plan モードが有効な間は、対象リポジトリ／ワークスペースに成果物を書き込みません。モードや権限の状態が不明でも、書き込みが許可されるわけではありません。必要な遷移を解決する間も、書き込みを伴わない対話と、非変更であることが確認済みの読み取りを続けられるようにします。ネイティブ Plan の明示的な要求は、有効であることが観測されるまで保留のままです。推奨が拒否されたことを尊重しても、有効な Plan を暗黙に終了してはいけません。
4. 承認後、および必要に応じて Plan モード終了後、永続化または実行の前に状態を再確認します。plan-refactor は、承認済みのガバナンスのみを保存するか、永続化したと主張せず明示的なチャットのみの納品を完了します。ソースコードの実装は、別途許可された実行の対象です。ADR の永続化案によって、その決定が承認されるわけではありません。
5. 対応が確認できる場合に限り、構造化された質問または非同期の質問を使用します。必要な回答を待つ間は、独立しており許可済みの作業のみを続けます。無回答、タイムアウト、事前選択された選択肢は承認ではありません。

条件付きの安定スキル選択指示

この対象リポジトリ向け指示を applicable、not applicable、または indeterminate に分類します。対象が複数の重要なワークフローを持つ、安定版の公開スキルを提供していることを証拠で確認できる場合に限り、applicable です。

• setup では、同等のルールを維持するか、有限個のワークフローの完全な開示、意図に基づく選択とその理由、曖昧な場合の質問、すでに許可された結果／範囲内でのみ行う変更、および高リスク／外部操作に対する個別承認を求める汎用ルールを追加します。
• audit では、分類と、不足・同等・競合するルールを報告し、書き込みは行いません。
• 直接の refactor では、不足しているルールを修復しません。ガバナンスの修復は setup に回します。
• indeterminate は、書き込みを決して許可しません。
• このリポジトリまたはプロバイダースキルの ADR ID を対象にコピーしてはいけません。ローカルのガバナンスで決定が必要な場合に限り、リポジトリ固有の識別子を使用します。

公開ステータス

重要な場合は、AC-ADR-036 のガイドとレポート資産に記載されている、証拠に裏付けられた正確な Read-only enforcement、Architecture decision status、および Execution status の値を使用します。計画とファイルシステムの強制はそれぞれ独立しています。completed が対象とするのは許可された範囲／段階のみであり、CI、公開、デプロイ、本番環境、またはサードパーティの成功を意味しません。

ユーザー向けの簡潔な結果一覧では、ステータスの意味付けに AC-ADR-050 Short を使用し、表示方法には AC-ADR-053 と、上記の条件付き内部レンダラーのルートを使用します。

資産

資産は派生物であり、規範的なものではありません。setup には assets/setup-report-template.md を、その他のルートには assets/refactor-report-template.md を使用します。残りの資産は、許可されたガバナンス作業に限り使用してください。適用対象となる正規の Long ADR が優先されます。

スクリプト

Architecture Compass には、実行可能なランタイムスクリプトは含まれていません。リポジトリに標準で備わっている検証ツールは、その動作と書き込みへの影響を把握した後にのみ使用してください。監査の一環として、ヘルパーを作成したりインストールしたりしないでください。

安全上のルール

• リポジトリの事実、パス、コマンド、ADR、マッピング、検証、ホスト機能を捏造しないでください。また、曖昧さから変更の有無を推測しないでください。
• 承認済みの対象 ADR を同梱の判断で上書きしたり、監査をセットアップ、計画、実装へと変えたりしないでください。
• 公開スキルが利用可能または推奨されているという理由だけで、インストール、呼び出し、同梱、設定をしないでください。
• 再利用可能な成果物に、シークレット、顧客データ、非公開の出所情報、内部ホスト名を含めないでください。
• 破壊的、不可逆、外部向け、デプロイ、公開、本番環境、スコープを拡大する作業には、個別の権限、正確な対象、停止条件、復旧を示す証拠が必要です。
• 証明責任を重複させたり、無効になった受領記録を再利用したり、形式だけの永続的なスモークテスト用ハーネスを作成したり、証拠の段階を誇張したりしないでください。
• スコープの逸脱、権限の不足、保護対象パスとの重複、曖昧なマッピング、未解決の ADR の競合、必須検証の失敗があれば停止してください。

出力形式

該当するレポート資産と AC-ADR-004 の証拠テーブルを使用してください。ワークフローのセットと選択、網羅範囲、書き込みのスコープ／ステータス／保護状態、調査済みおよび入手不能な証拠、判断／マッピングまたは調査結果、承認済みの計画または変更、AC-ADR-049 の台帳、リスク／延期のトリガー、次に許可されたアクションを含めてください。

最終受領記録は AC-ADR-053 と条件に応じた内部アダプタールートを通じて出力してください。このセクションでは、永続的な提示方針を重複させず、出力の組み立てに限定してください。

audit では、パッチやリポジトリへの書き込みを行わず、重大度順に調査結果を提示してください。計画ルートでは、承認済みの内容と書き込みスコープ、保留中の遷移／永続化、永続化された成果物、状態の再確認結果、実行済みの作業を区別してください。

完了基準

AC-ADR-064 Guide に記載された、選択した手順の完了基準を適用し、その AC-ADR-049 の受領記録と照合してください。完了の対象は、許可されたワークフローと証拠の段階に限られます。

失敗モード

AC-ADR-064 Guide に記載されたルートおよび計画の停止条件と、AC-ADR-049 Guide に記載された検証からの復旧手順を適用してください。ブロック状態または判定不能状態を、完了したとする主張に変えてはいけません。