ソフトウェアアーキテクチャエンジニアリング は何をしますか?
目的
ソフトウェアが変更されている間(AIエージェントによる変更も含む)、アーキテクチャの整合性を維持します。これは運用上のスキルであり、すべてのプロジェクトを再設計するよう指示するものではありません。その再利用可能な原則は、ソフトウェアアーキテクチャの基礎 第2版(Richards and Ford、2025年)に基づいています。継続的なエージェントワークフローと成果物は独自の拡張です。特定のモデル、プログラミング言語、リポジトリホスト、CIツール、フレームワークは必要ありません。
以下の3つの法則を適用します:
- すべてはトレードオフである。 コストとベネフィットの両方を、実際のコンテキストに基づいて評価し、状況が変化したら再評価します。
- 「なぜ」が「どのように」よりも重要である。 図やコードだけでなく、根拠、却下されたオプション、リスク、意思決定者を保存します。
- 決定はスペクトラム上にある。 偽の二分法、一律のマイクロサービスルール、アーキテクチャファッションを拒否します。
インパクトに応じた労力の選択
| モード | 典型的なトリガー | アクションと期待されるアウトプット |
|---|---|---|
| Light(軽量) | 孤立したバグ、フォーマット、契約/境界に影響を与えないローカルな実装 | 関連するコードと制約を検査。最小限の変更を行う。関連するチェックを実行。重要事項のみを報告。ADRは必須ではない。 |
| Standard(標準) | モジュールをまたがる機能、新しい統合、API/スキーマ変更、重要なリファクタリング | プロジェクトのコンテキストを確立。依存関係を検査。現実的なオプションを比較。インクリメントで実装。境界と契約を検証。重要な決定を記録。 |
| Deep(深層) | 新しいプラットフォーム、サービス分割、大規模な移行、高リスクなデータ/セキュリティ/信頼性の変更、アーキテクチャレビュー | 完全なコンテキストとアーキテクチャ分析、代替案、明示的なデータ/障害モード、移行とロールバック、測定可能なフィットネス関数、ADR、リスクと承認の境界。 |
エスカレーション:一見小さな編集が、所有権の境界を越える、公開契約を変更する、永続性を変更する、新しいランタイム/デプロイコンポーネントを導入する、障害インパクトを拡大する、またはアーキテクチャのドリフトを明らかにする場合に実施します。デエスカレーション:調査の結果、アーキテクチャに意味のある影響がないことが判明した場合に実施します。ユーザー/プロジェクト/安全に関する指示が優先されます。些細なタスクに重厚なレポートを強制することはありません。
必須のコーディングエージェントループ
既存のリポジトリでの作業には、このループを実行します。正確な手順、障害対応、並行エージェントのルールについては、エージェント実装ガバナンスを参照してください。
0. 現在のシステムを発見する - 発明しない
- アクセス可能な場合、関連するコード、テスト、パッケージ/ビルドファイル、インフラストラクチャ、設定、ドキュメント、ADR、ディレクトリレイアウト、実際の依存関係パスをアクセス可能な場合に検査します。
- プロジェクトのアーキテクチャコントラクト(例:
docs/architecture/CONTRACT.md)と受理されたADRを探します。これらをプロジェクトの制約として扱いますが、不変の真実としては扱いません。 - 観測された / 提供された / 仮定された / 未知の を別々に記録します。コードやツールにアクセスできない場合は、結果が検証されたリポジトリ分析ではなく提案であることを明記します。
- 既存のアーキテクチャを、好みのスタイルで静かに置き換えないでください。
1. 編集前に影響を評価する
- 変更範囲、影響を受けるビジネス機能、所有者モジュール、API/契約、データ責任、依存関係、セキュリティ境界、デプロイ単位、障害パスを定義します。
- タスクをLight / Standard / Deepに分類し、最小限の適切なレビューを選択します。
- 重要な決定については、スコープ、目標、測定方法を伴う、優先順位付けされたいくつかのアーキテクチャ特性(例:セキュリティ、レイテンシ、可用性、スケーラビリティ、弾力性、保守性、テスト容易性、デプロイ容易性、回復可能性、コスト)を導き出します。明示的な要件と暗黙的で未確認のニーズを分離します。
- 低リスクの未知のものに対しては、最小限で可逆的なデフォルトを選択します。サポートされていない高リスクの仮定を確認済みであるかのように進めないでください。
2. 境界を維持し、必要に応じて代替案を比較する
- 高い凝集度と低い結合度を優先します。ビジネス責任、依存関係の方向、時間的結合、データ所有権を明確にします。論理モジュールと独立してデプロイされたサービスを区別します。
- ディレクトリ構造だけでなく、運用アーキテクチャとデータアーキテクチャへの影響を確認します。共有データベース、トランザクション境界、同期呼び出しは、見かけ上のモジュール性を無効にする可能性があります。
- 重要な変更については、コンテキストに基づいたトレードオフを使用して、少なくとも2つの実行可能なオプションを比較します。候補には、レイヤード、モジュラーモノリス、パイプライン、マイクロカーネル、サービスベース、イベント駆動、スペースベース、オーケストレーション駆動SOA、マイクロサービス、またはそれらのハイブリッドが含まれます。どのアーキテクチャスタイルも普遍的なデフォルトではありません。
- 分散設計は、ネットワーク障害/レイテンシ、可用性、一貫性、トランザクション境界、リトライ、冪等性、可観測性、セキュリティ、運用コストを該当する場合に対処する必要があります。
- その決定を覆す条件を明記します。スタイル、分散設計、基礎を選択的に使用します。
3. 安全なインクリメントで実装を計画する
- 予想されるファイル/モジュールの変更、安定させなければならない契約、移行順序、必要な場合はロールバック戦略を特定します。
- アーキテクチャ不変条件(真であり続けなければならないルール)を記述します:許可される依存関係の方向、内部APIの所有権、データ書き込み権限、テナント/認証境界、後方互換性、エラーハンドリングなど。
- 実装前に、それらの不変条件に対する客観的なチェックを選択します。必要に応じて、プロジェクトアーキテクチャコントラクトと変更影響テンプレートをコピー/適応します。許可なく、または明確なタスクスコープなしにプロジェクトファイルを作成しないでください。
- 人間/ビジネスの権限を必要とする、不可逆的または影響の大きい決定を要求するか延期します。承認を偽造しないでください。
4. アーキテクチャドリフトなしで実装する
- 現在のアーキテクチャと一致する、最小限の一貫性のある変更を行います。実証された必要性なしに、サービスを分割したり、ブローカー、グローバル抽象化、新しいフレームワークを導入したりしないでください。
- インターフェースとデータ所有権を明確に保ちます。別のモジュールの内部をショートカットしたり、認証/検証をバイパスしたり、イベントスキーマを黙って変更したり、無関係な変更を混在させたりしないでください。
- 実装によって計画に重大な欠陥が明らかになった場合は、回避コードで隠蔽するのではなく、停止して影響を受ける決定を再評価します。正当な場合にのみADR/契約を更新します。
- マルチエージェント作業では、コンポーネント/ファイルの所有権、安定した契約、統合責任者を定義します。並行変更は共有アーキテクチャ制約をオーバーライドしません。
5. 機能だけでなくアーキテクチャを検証する
- 利用可能で許可されている場合、関連する既存の単体テスト、統合テスト、契約テスト、ビルドチェックを実行します。
- アーキテクチャ固有のフィットネス関数を検証します:禁止された依存関係、循環、モジュール所有権、API互換性、スキーマ移行、冪等性、パフォーマンス予算、可観測性、回復力、セキュリティ、デプロイ/ロールバック(該当する場合)。
- 変更前後の依存関係構造と影響を受ける不変条件を比較します。オプションのstdlib インポート境界チェッカーとサンプル設定は、選択されたPython/JS/TSのインポートルールを強制できます。これは意図的に制限されており、完全なアーキテクチャの正確性を証明するものではありません。
- 証拠をPASS / FAIL / NOT RUN / NOT APPLICABLEでラベル付けします。実際の実行や証拠なしに、テスト、スケーラビリティ、本番対応、セキュリティ、デプロイが検証されたと主張しないでください。
- 必須ゲートが失敗した場合は、修正/ロールバックするか、未解決の問題と意思決定者を明示的に特定します。失敗したゲートを完了作業として提示しないでください。
6. 重要な決定を記録し伝達する
- アーキテクチャ上重要な変更に対してのみ、簡潔なADRを作成または更新します:タイトル、ステータス、コンテキスト、選択されたソリューション、理由、代替案、トレードオフ、結果、強制、再評価トリガー。ADRテンプレートを使用します。
- 過去の決定が新しい決定に置き換えられた場合も保持します。図は実装や検証の証拠ではなく、コミュニケーションの補助として扱います。
- 最終報告では、何が変更されたか、アーキテクチャへの影響、合格/不合格/未実行のチェック、未解決のリスク、必要な人間の決定を記載します。Light変更の場合、1つの簡潔なパラグラフで十分なことが多いです。
設計のみおよび監査タスク
リポジトリを編集しない場合は、ステップ0~3と6を比例的に適用し、何も実装またはテストされたふりをせずに、設計、トレードオフ分析、アーキテクチャブリーフ、またはレビューを作成します。完全なアーキテクチャ監査の場合は、コンポーネント、データ所有権、境界、デプロイ、チーム/インフラストラクチャの制約を棚卸しし、証拠に基づいて具体的なリスクをランク付けし、全面的な書き換えを推奨する前に、段階的な改善策とフィットネス関数を提案します。
譲れない安全策
- 検証不可能な事実は禁止: 発明されたリポジトリ検査、テスト出力、負荷レベル、コンプライアンスステータス、ステークホルダーの承認、測定結果はありません。
- 偽の普遍性は禁止: マイクロサービスもモノリスもイベント駆動システムも、本質的に最良ではありません。テーブル/エンティティだけでサービスを分割しないでください。
- スコープの混同は禁止: 論理モジュール、デプロイ単位、データ所有権、アーキテクチャ特性のスコープは異なる概念です。
- 隠れた結合は禁止: 共有スキーマ、共有ライブラリ、時間的結合、クロスサービス呼び出し、イベント契約を調査します。揮発性のドメインロジックを再利用すると、結合が増加する可能性があります。
- リスクの消去は禁止: 分散一貫性、トランザクション処理、スキーマ変更、障害回復、ロールバックは、関連する場合に明示的な検討が必要です。
- プロセスの茶番は禁止: 完了したチェックリストや自己評価は証拠ではありません。実際のチェックとコードの証拠を優先します。
- サイレントなアーキテクチャ変更は禁止: 重要な逸脱をフラグ付けし、理由を文書化し、責任を人間/プロジェクトの意思決定者に留めます。
- 著作権で保護された書籍の配布は禁止: このスキルは独自の統合物です。書籍やその図をダウンロード先のリポジトリにコピーしないでください。
オンデマンドリファレンスファイル
タスクに必要なファイルのみを読み取ります(このスキルディレクトリからの相対パス):
- AIコーディングと継続的アーキテクチャガバナンス — 実質的なリポジトリ編集、PRレビュー、並行エージェント、アーキテクチャドリフト診断に必須。
- 基礎とアーキテクチャ特性 — 要件、結合、凝集度、コンポーネント、特性のスコープ。
- アーキテクチャスタイル — 9つのスタイルと選択条件。
- 分散システムとパターン — ネットワークの現実、イベント、トランザクション、一貫性、オーケストレーション、CQRS。
- 決定、フィットネス関数、リスク — ADR、ガバナンス、リスクストーミング、図。
- 人、データ、インフラストラクチャ、AI — チームと運用上の制約。
- ソースマップ — 全27の書籍章と、書籍のアイデアとエージェント固有の拡張の区別。
- 検証ルーブリック — 主要な設計決定と実装レビューの品質基準。
成果物:アーキテクチャブリーフ、アーキテクチャコントラクト、変更影響、ADR、トレードオフマトリックス、リスクレジスタ、アーキテクチャレビュー、境界ポリシー例。動作シナリオ:境界ドリフトなしのAIコーディング。他のモデル/ランタイムの指示はオプションです。移植性を参照してください。