# Adapt Architecture

> ストラングラーフィグ移行、クリサリスフェーズ、インターフェース保全を用いた 構造的変態を実行する。変換計画、並行稼働、段階的カットオーバー、ロールバック設計、 変態後の安定化をカバーする。assess-formがシステムを変換READYと分類した時、 モノリスからマイクロサービスへの移行時、依存システムが稼働し続ける中でコア サブシステムを置き換える時、またはビッグバンではなく段階的なアーキテクチャ変更が 必要な時に使用する。

- Skill: `pjt222/adapt-architecture-3` (Agent Skill)
- Install (CLI): `npx get-skill add pjt222/adapt-architecture-3`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/adapt-architecture-3/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: pjt222 (https://skillmd.com/u/pjt222)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/pjt222/adapt-architecture-3

---


# アーキテクチャの適応

構造的変態を実行する — 運用の継続性を維持しながら、システムのアーキテクチャを現在の形態からターゲット形態に変換する。ストラングラーフィグ移行、クリサリスフェーズ、インターフェース保全を用いて、変換中もシステムが停止しないことを保証する。

## 使用タイミング

- フォーム評価（`assess-form`参照）がシステムをREADYと分類した場合
- ダウンタイムなしで新しい要件に対応するためにアーキテクチャを進化させる必要がある場合
- モノリスからマイクロサービスへの移行（またはその逆）
- 依存システムが稼働し続ける中でコアサブシステムを置き換える場合
- 後方互換性を維持しながらデータモデルを進化させる場合
- ビッグバンではなく段階的なアーキテクチャ変更が必要な場合

## 入力

- **必須**: 現在のフォーム評価（`assess-form`または同等の分析から）
- **必須**: ターゲットアーキテクチャ（システムがどうなるべきか）
- **必須**: 運用継続性の要件（変換中に壊してはいけないもの）
- **任意**: 利用可能な変換予算（時間、人員、コンピュート）
- **任意**: ロールバック要件（どこまで戻れる必要があるか？）
- **任意**: 並行稼働期間（新旧を同時に稼働させる期間）

## 手順

### ステップ1: 変換ブループリントの設計

現在の形態からターゲット形態への変態パスを計画する。

1. 変換を中間形態のシーケンスとしてマッピングする:
   - 現在の形態 → 中間形態1 → ... → ターゲット形態
   - 各中間形態は運用可能でなければならない（トラフィックを処理でき、テストに合格する）
   - 中間形態は現在の形態よりも保守が困難であってはならない
2. 変換の継ぎ目を特定する:
   - 現在の形態のどこを「切断」して新しいアーキテクチャを挿入できるか？
   - 自然な継ぎ目: 既存のインターフェース、モジュール境界、データパーティション
   - 人工的な継ぎ目: 切断を可能にするために作成されたインターフェース（腐敗防止レイヤー）
3. 変態パターンを選択する:
   - **ストラングラーフィグ**: 新システムが旧システムの周りに成長し、徐々に置き換える
   - **クリサリス**: 旧システムを新しいシェルで包む; シェルが外部インターフェースを保持しながら内部を置き換える
   - **バディング**: 新システムが旧システムと並行して成長; トラフィックが徐々に移行する（コロニーバディングについては`scale-colony`を参照）
   - **変態移行**: 依存関係の順序でコンポーネントを段階的に置き換える（末端から先に、根幹は最後に）
4. インターフェース保全レイヤーを設計する:
   - 外部の利用者は中断を経験してはならない
   - APIバージョニング、後方互換性のある契約、アダプターパターン
   - 保全レイヤーは一時的な足場 — 撤去を計画する

```text
Metamorphosis Patterns:
┌───────────────┬───────────────────────────────────────────────────┐
│ Strangler Fig │ New code intercepts routes one by one;            │
│               │ old code handles everything else until replaced   │
│               │ ┌──────────┐                                     │
│               │ │ Old ████ │ → │ Old ██ New ██ │ → │ New ████ │  │
│               │ └──────────┘                                     │
├───────────────┼───────────────────────────────────────────────────┤
│ Chrysalis     │ Wrap old system in new interface; replace         │
│               │ internals while external shell stays stable       │
│               │ ┌──────────┐     ┌──[new]───┐     ┌──[new]───┐  │
│               │ │ old core │ → │ old core │ → │ new core │  │
│               │ └──────────┘     └──────────┘     └──────────┘  │
├───────────────┼───────────────────────────────────────────────────┤
│ Budding       │ New system runs in parallel; traffic shifts       │
│               │ ┌──────┐ ┌──────┐     ┌──────┐ ┌──────┐         │
│               │ │ Old  │ │ New  │  →  │ Old  │ │ New  │         │
│               │ │ 100% │ │  0%  │     │  0%  │ │ 100% │         │
│               │ └──────┘ └──────┘     └──────┘ └──────┘         │
└───────────────┴───────────────────────────────────────────────────┘
```

**期待結果:** 中間形態、継ぎ目、選択された変態パターン、インターフェース保全戦略を示す変換ブループリント。各ステップは具体的かつテスト可能。

**失敗時:** クリーンな継ぎ目が見つからない場合、変換前に予備的な溶解（`dissolve-form`参照）で継ぎ目を作る必要があるかもしれない。中間形態が運用不可能な場合、変換ステップが大きすぎる — より小さな増分に分解する。

### ステップ2: スキャフォールディングの構築

変態を支える一時的なインフラストラクチャを構築する。

1. 腐敗防止レイヤーを作成する:
   - 新旧システム間の薄い変換レイヤー
   - 移行状態に基づいて適切なシステム（新または旧）にリクエストをルーティングする
   - 新旧の表現間でデータフォーマットを変換する
   - このレイヤーは変換を保護する「繭」である
2. 並行稼働インフラストラクチャを構築する:
   - 新旧両方のシステムが同時にデプロイ可能でなければならない
   - フィーチャーフラグがどのシステムがどのトラフィックを処理するかを制御する
   - 比較メカニズムが新旧が同等の結果を生成することを検証する
3. ロールバックチェックポイントを確立する:
   - 各中間形態で、前の形態へのロールバックが可能であることを確認する
   - ロールバックは前方への変換ステップよりも速くなければならない
   - データ移行は可逆的でなければならない（または移行中にデータを二重書き込みする）
4. バリデーションハーネスを構築する:
   - 各中間形態での運用継続性を検証する自動テスト
   - リグレッションを検出するパフォーマンスベンチマーク
   - 移行エラーを検出するデータ整合性チェック

**期待結果:** スキャフォールディングインフラストラクチャ（腐敗防止レイヤー、並行稼働、ロールバック、バリデーション）が変換開始前に整っている。スキャフォールディング自体がテスト・検証済み。

**失敗時:** スキャフォールディングが高コストすぎる場合、簡素化する: 最小限のスキャフォールディングはフィーチャーフラグとロールバック手順。腐敗防止レイヤーと並行稼働は安全性を追加するが、小規模な変換には常に必要ではない。

### ステップ3: 段階的カットオーバーの実行

旧形態から新形態へ機能を段階的に移行する。

1. 移行のためにコンポーネントを順序付ける:
   - 最も結合度が低く、リスクが最も低いコンポーネントから開始する（信頼を構築）
   - より重要で結合度の高いコンポーネントに進む
   - 最も結合度が高い/重要なコンポーネントは最後に残す（その時点でチームは経験を積んでいる）
2. 各コンポーネントについて:
   a. 腐敗防止レイヤーの背後に新バージョンを実装する
   b. 並行稼働: 新旧両方が同じ入力を処理する
   c. 出力を比較する — 同等であるべき（または差異は想定内で文書化されている）
   d. 確信が持てたら、トラフィックを新バージョンに切り替える（フィーチャーフラグの切り替え）
   e. 異常を監視する（カットオーバー後は監視感度を上げる）
   f. 安定期間後、このコンポーネントの旧バージョンを廃止する
3. 全体を通じて継続的デリバリーを維持する:
   - 各カットオーバーステップは通常のデプロイメントであり、特別なイベントではない
   - システムは常に既知の、テスト済みの、運用可能な状態にある
   - カットオーバーで問題が発生した場合、前の状態にロールバックする（それはまだ運用可能）

**期待結果:** 機能がコンポーネントごとに移行し、各ステップでバリデーションが行われる。システムは常に運用可能。各カットオーバーが次への信頼を構築する。

**失敗時:** 並行稼働で不一致が明らかになった場合、新しい実装にバグがある — カットオーバー前に修正する。カットオーバーでパフォーマンスが劣化した場合、新コンポーネントの最適化が必要か、腐敗防止レイヤーのオーバーヘッドが大きすぎる可能性がある。チームが移行途中で信頼を失った場合、一時停止して安定化する — 既知の状態にある半移行システムは、急いだ完全移行よりもはるかに良い。

### ステップ4: クリサリスフェーズの管理

最も脆弱な期間 — システムが形態の間にある時 — を乗り越える。

1. クリサリスの現実を認識する:
   - 移行中、システムは部分的に旧で部分的に新である
   - このハイブリッド状態はどちらの純粋な状態よりも本質的に複雑である
   - 複雑性は移行の中間点でピークに達し、その後減少する
2. クリサリスの規律:
   - クリサリスフェーズ中は新機能なし（変換のみ）
   - 外部変更を最小限に（必須でないデプロイメントを凍結）
   - 監視とオンコール体制を強化
   - 移行進捗とシステム健全性の毎日のチェックイン
3. 中間クリサリス評価:
   - 中間点で評価: ターゲット形態は依然として正しい目標か？
   - 何か変わったか（市場、要件、チーム）がターゲットに影響するか？
   - 変換を続行するか、一時停止するか、方向転換するか？
4. クリサリスを保護する:
   - ロールバックパスを常にクリアに保つ
   - 現在のハイブリッド状態を徹底的に文書化する（将来のデバッガーが必要とする）
   - 移行完了前に一時的なスキャフォールディングを「整理」する誘惑に抵抗する

**期待結果:** クリサリスフェーズが、規律と監視を強化した意図的な期限付きの期間として管理される。一時的な複雑性は安全な変換のコストであることをチームが理解している。

**失敗時:** クリサリスフェーズが長引きすぎると、ハイブリッド状態が新しい常態になる — これは新旧どちらよりも悪い。期限を設定する。期限に達した場合、残りの移行を加速するか、ハイブリッド状態を「新しい形態」として受け入れて安定化する。

### ステップ5: 変態の完了と安定化

変換を完了し、スキャフォールディングを撤去する。

1. 最終カットオーバー:
   - 最後のコンポーネントを新形態に移行する
   - 完全な新システムに対してフルバリデーションスイートを実行する
   - 本番相当の負荷でパフォーマンステストを行う
2. スキャフォールディングの撤去:
   - 腐敗防止レイヤーを廃止する（もう不要）
   - 移行関連のフィーチャーフラグを削除する
   - 並行稼働インフラストラクチャをクリーンアップする
   - 旧システムコードをアーカイブする（削除ではなく参照用に保持）
3. 変態後の安定化:
   - 強化された監視で2〜4週間、新形態で稼働する
   - 実世界の条件で発生する問題に対処する
   - 新しいアーキテクチャを反映するようにドキュメントを更新する
4. レトロスペクティブ:
   - 変換でうまくいったことは何か？
   - 予想よりも困難だったことは何か？
   - 次回は何を変えるか？
   - チームの変換プレイブックを更新する

**期待結果:** 変換が完了。システムが新形態で稼働。スキャフォールディングが撤去済み。ドキュメントが更新済み。チームが将来の変換のための学びを記録済み。

**失敗時:** カットオーバー後に新形態が不安定な場合、ロールバックパスを維持して安定化を続ける。安定化が計画期間を超える場合、新アーキテクチャに設計上の問題がある可能性がある — 最も問題のあるコンポーネントの部分的ロールバックまたはターゲットフィックスが適切かどうかを検討する。

## バリデーション

- [ ] 変換ブループリントが実行可能な中間形態を示している
- [ ] スキャフォールディング（腐敗防止レイヤー、ロールバック、バリデーションハーネス）が移行開始前に整っている
- [ ] コンポーネントが最低リスクから最高リスクの順に移行される
- [ ] 並行稼働が各ステップで同等性を検証している
- [ ] クリサリスフェーズがフィーチャーフリーズ規律で期限付きである
- [ ] 変換完了後にすべてのスキャフォールディングが撤去されている
- [ ] 変態後の安定化期間が重大な問題なく完了している
- [ ] レトロスペクティブが学びを記録している

## よくある落とし穴

- **ビッグバン移行**: すべてを一度に変換しようとすること。段階的カットオーバーの安全性を放棄し、影響範囲を最大化する。常に段階的に移行すること
- **恒久的なスキャフォールディング**: 撤去されない腐敗防止レイヤーやフィーチャーフラグは技術的負債になる。スキャフォールディングの撤去を変換の一部として計画し、後付けにしない
- **クリサリスの否認**: ハイブリッド状態が正常であると装うことは、不安定な基盤上での機能開発につながる。クリサリスフェーズを認識し、その規律を強制する
- **ターゲット固定**: ターゲットアーキテクチャにあまりにもコミットしすぎて、より良い代替案の兆候を無視すること。中間クリサリス評価はこのために存在する
- **変換疲労**: 長期の移行はチームを疲弊させる。各変換ステップを数週間ではなく数日で完了できる大きさに保つ。モメンタムを維持するためにマイルストーンを祝う

## 関連スキル

- `assess-form` — システムが変換の準備ができているかを判断する前提条件の評価
- `dissolve-form` — 直接変換するには硬直しすぎたシステム用; 溶解がここで必要な継ぎ目を作る
- `repair-damage` — 変換が損傷を導入した場合の回復スキル
- `shift-camouflage` — 深いアーキテクチャ変更なしで十分かもしれない表面的な適応
- `coordinate-swarm` — 分散システム全体での変換の順序付けにスウォーム調整が参考になる
- `scale-colony` — 成長圧力はアーキテクチャ適応の一般的なトリガー
- `implement-gitops-workflow` — GitOpsが段階的カットオーバーのためのデプロイメントインフラストラクチャを提供する
- `review-software-architecture` — ターゲットアーキテクチャを評価するための補完的なレビュースキル

