リアーキテクチャ開発ワークフロー

リアーキテクチャ開発ワークフロー は何をしますか？

このスキルを使用して、アーキテクチャの再設計を開発可能なパッケージに変換します。 出力は単なる図ではありません。それは、何が構築されるか、どのように移行するか、どのようにテストされるか、そして何がサポート対象外であるかに関する、境界が定義された契約です。リアーキテクチャを継続的な移行プログラムとして扱います。各パッケージはレビュー可能なデリバリーの単位であり、将来のシステム全体を仕様化または実装することを約束するものではありません。

運用原則

1. 権威と意図を分離する。 最初に現在のコード、テスト、アーキテクチャ権威、リポジトリの指示を読み込みます。再設計ドキュメントは、ターゲット、計画、または証拠としてマークし決して現在の振る舞いとして提示しないでください。
2. 既存のものに名前を付ける。 提案されたすべてのモジュールを、現在のクラス、コントラクト、レジストリ、ストア、またはエントリポイントにマッピングします。既存のコンテンツを捏造した名詞の背後に隠さないでください。
3. 所有権を明示する。 各境界が何を所有し、何を所有してはならないか、誰が永続的な事実を書き込むか、誰が変更を承認するか、誰がリカバリを所有するかを明記します。
4. 実際のコンシューマーから抽象化を獲得する。 実際のコンシューマーが名前付きの依存関係を削除し、実際の登録を統合し、不変条件を強制可能にした場合にのみ、新しい抽象化を認めます。一般的な抽象化は通常、2つのコンシューマーを必要としますが、狭い安全境界は1つのコンシューマーでも認められる場合があります。
5. 実際の垂直スライスから始める。 1つのレガシーフィクスチャを保持し、同じシナリオに対して1つのターゲット境界フィクスチャを追加します。合成グラフはメカニクスをテストできますが、アーキテクチャを証明することはできません。
6. 置き換えの前に契約を凍結する。 具体的な依存関係を削除する前に、入力、出力、認可、アイデンティティ、冪等性、障害、永続性、リカバリ、互換性を定義します。
7. パフォーマンスを正当化ではなく証拠として扱う。 最初に権威、永続的な互換性、リカバリを保持し、次に同等のワークロードを現在のパスに対して測定します。
8. ドキュメントを維持可能に保つ。 各主張に1つの正規の所有者を与え、現在/ターゲット/履歴のステータスを可視化し、ポリシーをドキュメント間でコピーする代わりにリンクします。
9. 段階的なデリバリーを計画する。 すべてのインクリメントは、成果物、先送り事項、次の進展トリガー、および必要な昇格証拠を明記します。

ワークフローとモジュールローディング

レベル1（L1）はシステム境界、レベル2（L2）は安定したモジュール/境界契約、レベル3（L3）はタスク固有の実装詳細を意味します。プロジェクトの既存のラベルをこれらの意味にマッピングし、別の分類法を導入しないでください。

まず適切なサイズにします。references/deliverable-matrix.md を読み、次の決定をレビュー可能にする最小のパッケージを選択します。以下のフェーズは完全なパスであり、すべてのリクエストに必須のチェックリストではありません。他の参照は、対応するフェーズまたは関心事がアクティブになった場合のみロードします。

すべてのパッケージまたは移行インクリメントは、デリバリーホライゾンを宣言する必要があります。成果物マトリックスは、スキーマ、設計専用の縮小、先送り事項、および進展条件を管理します。

フェーズ0 — 権威とベースラインの解決

• リポジトリの指示、README、開発ガイダンス、およびアーキテクチャ権威（存在する場合）を読み込みます。
• 以前のリアーキテクチャプログラムが存在しないと結論付ける前に、オリエンテーション、ドキュメント、リリース、移行、タスク、およびハンドオフの記録を検索します。
• リクエストに関連するアクティブなプログラムごとに、新しいスコープを定義する前に、その最新のインクリメント記録、レビュー決定、未解決の先送り事項、未解決のL1/L2クレーム、ADR、および記録された次のタスクを読み込みます。
• 以前の進展トリガーと昇格証拠を検証します。どちらかが満たされていない場合、またはブロッキングな所見が未解決のままの場合、続行する前に状態とオプションをユーザーに提示します。ユーザーが例外を承認した場合、その理由、承認者、および影響範囲を現在のインクリメント記録に記録します。
• ソース階層と正確なベースラインリビジョンを特定します。存在する場合、現在のエントリポイント、状態/データ所有者、永続性、テスト、例、および拡張レジストリを検査します。
• 実装されているもの、ターゲット意図であるもの、および不明なものを記録します。
• 結合度の低減を主張する前に、再現可能な依存関係または登録インベントリ（再実行可能なコマンド/スクリプト1つ、チェックインされた出力またはレポート、および比較前後で再利用される同じメソッド）を作成します。

リポジトリの既存のタスク台帳、課題システム、およびハンドオフ形式に従います。特定のコラボレーションツールを要求したり、会話履歴をアーキテクチャ権威として使用したりしないでください。

フェーズ1 — ポジショニングとスコープ

以下を記録します：

• システムとは何か、誰がそれを構築するか
• 現在の結合や成長によって引き起こされる問題
• 最初のステージのデプロイメント境界
• 非目標および先送りされた機能
• 各主張に対する境界のある利点と比較ベースライン

同時に、複雑性予算を確立します。references/document-and-complexity-gates.md を、予算、ドキュメント所有権ルール、および停止条件についてロードします。「よりモジュール化された」や「よりスケーラブルな」などの言葉よりも、境界のある主張を優先します。

ユーザー意思決定ゲート

コードや図から製品の意図を推測しないでください。リポジトリの証拠が、スコープ、所有権、デプロイメント、互換性、安全性、成功基準、または移行順序に関する重要な質問に答えられない場合は、一時停止してユーザーに質問します。関連する選択肢をまとめ、観察された事実とトレードオフを示し、正当化される場合は保守的なデフォルトを推奨します。

references/user-decision-gates.md を、ステージ固有の質問と永続的な記録場所に使用します。ユーザーが重要な選択を明示的に委任した場合は、推奨されるか最もサポートされている可逆的なオプションを選択し、委任と前提を記録して続行します。非重要な可逆的な前提は、進行を妨げるのではなく明示的にします。

フェーズ2 — レベル1ターゲットアーキテクチャ

主要なサブシステムまたは調整プレーン、状態/データ権威と単独ライター、アイデンティティ所有権、依存関係の方向、アプリケーションエントリポイント、プロセス/デプロイメント境界、および制御された通信形式を定義します。

L1は、実装の方向性が決まる前に、スコープ内のターゲットに対して必須かつ明示的です。将来のすべてのモジュールを記述する必要はありませんが、所有権、依存関係の方向、またはデプロイメントスコープを曖昧にしてはなりません。未解決のL1質問は、所有者と決定ゲートとともに記録します。

references/architecture-contracts.md を、L1図のルールと、後のフェーズで使用されるL2/L3/インターフェーススキーマについてロードします。

フェーズ3 — 現状からターゲットへのマッピング

すべての現在のホットスポットについて、最初のアクションを保持、公開、適応、分割、統合、非推奨、または削除として分類します。現在の所有者、ターゲット所有者、保存された通信/永続性パス、および削除ゲートを記録します。詳細な先送り事項の正規の所有者としてデリバリーホライゾンを維持します。

トピックが興味深いという理由だけでドキュメントを作成しないでください。最初に正規の所有者を見つけます。所有権、ステータス、対象読者、またはライフサイクルが実質的に異なる場合にのみ、新しいドキュメントを作成します。

フェーズ4 — レベル2モジュール契約

安定したモジュールまたはモジュール間境界ごとに1つのL2契約を作成します。責任と非責任、現在のコンポーネント、提供/要求サービス、書き込み可能権限、許可された呼び出し/データ可視性、ライフサイクル/障害、互換性、および実装に先送りされた決定をカバーします。

L2は最初のパッケージでは不完全なままでも構いません。重要な主張を確立済み、条件付き、または未解決としてマークします。未解決の選択にはそれぞれ、それを解決できる境界のある実験、証拠の閾値、または実装ゲートが必要です。体裁のために精度をでっち上げないでください。

references/architecture-contracts.md のL2および相互作用形式のルールを使用します。パッケージに複数のドキュメントが含まれる場合は、references/document-and-complexity-gates.md のナビゲーションと正規所有者チェックを使用します。

フェーズ5 — MVPとタスクローカル契約

意図された境界を実行する最小の実際のクローズドループを選択します。読み取り/ライフサイクル完了スライスは、最初の書き込み境界スライスの前に来る場合があります。ローカルMVPラベルは、説明的な名前と組み合わせた場合のみ保持し、スライスが何を証明し、何を証明しないかを正確に記述します。

境界のある実装タスクをコーディングする前に、そのタスクが消費するL3契約のみを凍結します。実装タスクがそれを採用するか、修正を記録するまで、それは候補のままです。選択されていないモジュールに対してL3ドキュメントを作成しないでください。references/architecture-contracts.md のL3およびインターフェースチェックリストを使用します。

フェーズ6 — 敵対的レビューと双方向の鋼鉄マン化

所有権、リカバリ、互換性、移行、および証拠の主張を破ろうとする敵対的パスを実行し、続いて最も強い価値と意図的に保守的な境界を述べる鋼鉄マン化を実行します。パッケージを書いていない独立したレビューアーを優先します。そうでない場合は、新しいコンテキストを使用して制限を開示します。

references/adversarial-review.md を、レビューのタイミング、質問、および単一の調整台帳に使用します。すべての所見を直ちに処理します。ブロッキングな所見は、リスクが解決されるか、ユーザーまたは独立したレビューアーによって明示的にダウングレード/例外として承認されるまで、ゲートを閉じたままにします。それを拒否または先送りするだけではゲートは開きません。

フェーズ7 — 移行、検証、昇格

互換性レイヤー、アボート条件、削除ゲート、ロールバック/再起動境界、レガシー/ターゲットフィクスチャ、および同等の証拠を用いた段階的移行を定義します。ターゲットテキストを現在のアーキテクチャに昇格させるのは、実装、互換性証拠、およびリポジトリ権威の更新が一緒にマージされた後にのみ行います。

各インクリメントの終了時に、継続、名前付き実験の実行、ターゲット/契約の改訂、または停止して現在のパスを維持のいずれかの結果を選択します。次のインクリメントは、そのトリガーと昇格証拠が満たされた場合にのみ開始されます。詳細な証拠、実験、およびADRルールについては、references/migration-and-promotion.md をロードします。

フェーズ8 — ハンドオフと公開

公開前に：

• メタデータ、リンク、カタログ、および関連する適合性/回帰チェックを検証します。
• 完全な差分を検査し、無関係なファイルやサポートされていない実装の主張がないことを確認します。
• プロジェクトの既存の変更/ハンドオフ記録を更新します。
• オリエンテーションまたはカタログエントリからインクリメント記録を発見可能にします。
• 正確な次のタスクと所有者を記述します。

ユーザーがその外部変更を承認しない限り、PRを作成したりブランチをプッシュしたりしないでください。承認された場合、ランタイム動作が実際に変更されていない限り、パッケージをターゲット設計/ドキュメントとして記述します。

オプションの関心事

プラグイン、バージョン共存、プロセス分離、ホットリプレース、および動的アンロードは、デフォルトのアーキテクチャ要件ではありません。references/optional-concerns.md は、要求された設計が実際にこれらの関心事のいずれかをアクティブにする場合にのみロードします。

モジュールルーティング

ニーズ	ロード先
最小のアーティファクトセットとデリバリーホライゾンを選択する	deliverable-matrix.md
重要なユーザー決定を質問または記録する	user-decision-gates.md
L1/L2/L3または実装向けインターフェースを定義する	architecture-contracts.md
ドキュメントの拡大、複雑性、または過剰設計を制御する	document-and-complexity-gates.md
敵対的レビューと鋼鉄マン化を実行する	adversarial-review.md
移行、実験、ADR、または昇格を計画する	migration-and-promotion.md
プラグイン、分離、またはバージョン共存を設計する	optional-concerns.md

デフォルトですべてのモジュールをロードしないでください。アクティブなフェーズと要求された成果物が、どの参照が必要かを決定します。

やってはいけないこと

• 実際の1つのスライスを証明する前に、コードベース全体を書き換えないでください。
• すべてのファイル/クラスをプラグインに変換しないでください。
• 明示的なターゲット決定と障害モデルなしに、重複した状態所有者、スケジューラ、ストア、バス、またはライフサイクル権威を作成しないでください。
• 名前を変更したパススルーラッパーの背後に混合責任を隠さないでください。
• 依存関係のカウントが少ないだけの結合度の低減を主張しないでください。
• 合成デモを主要なMVP終了条件として使用しないでください。
• 拡張のクリーンアップがドメインの完了または破棄を意味するかのように扱わないでください。
• タスクノート、ベンチマークスコア、または生成された散文を現在のアーキテクチャ権威として扱わないでください。