# Adapt Architecture

> Execute structural metamorphosis using strangler fig migration, chrysalis phases, and interface preservation. Covers transformation planning, parallel running, progressive cutover, rollback design, and post-metamorphosis stabilization for system architecture evolution. Use when assess-form has classified the system as READY for transformation, when migrating from monolith to microservices, when replacing a core subsystem while dependents continue operating, or when any architectural change must be gradual rather than big-bang.

- Skill: `pjt222/adapt-architecture-5` (Agent Skill)
- Install (CLI): `npx get-skill add pjt222/adapt-architecture-5`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pjt222/adapt-architecture-5/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-5

---


# 變架構

執結構之蛻變，使系統由舊形而至新形，而運行不輟。用絞榕之遷、蛹化之階、界面之守，以全其功於變之中。

## 用時

- 形之察（見 `assess-form`）定系統為 READY 乃用
- 架構宜更以應新求而不停機乃用
- 由巨石遷至微服（或反之）乃用
- 易核心之部而餘依之系統仍運乃用
- 更數據之模而守舊約乃用
- 凡架構之變宜漸而非驟者乃用

## 入

- **必要**：當前形之察（出 `assess-form` 或同類之析）
- **必要**：目標架構（系統所當成者）
- **必要**：運行連續之求（變中不可壞者）
- **可選**：變之資（時、人、算力）
- **可選**：退之求（可退至何處）
- **可選**：並行之久（新舊並行幾何）

## 法

### 第一步：繪變之藍圖

謀由當前至目標之蛻路。

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`）以開縫。若中間形不可運，則其步過大——析為更小之增。

### 第二步：築其鷹架

建支蛻變之暫設基礎。

1. 建防腐之層：
   - 新舊之間薄薄之譯層
   - 依遷之狀，分派請求於舊或新
   - 譯數據之形於新舊之間
   - 此層為「繭」也，護其蛻變
2. 設並行之基：
   - 新舊二系可同時部署
   - 功能旗掌何者受何流
   - 比對之機驗新舊之輸出相等
3. 立退之節點：
   - 每中間形，驗可退至前形
   - 退宜速於進
   - 數據之遷可逆（或過渡中雙寫）
4. 築驗證之架：
   - 自動之試以驗連續運行
   - 性能之量以測退化
   - 數據完整之查以察遷誤

**得：** 鷹架（防腐層、並行、退機、驗證）具於遷前。鷹架本身已試已驗。

**敗則：** 若鷹架過費，可簡之：最少者一功能旗與退之程耳。防腐之層與並行雖增安，小變未必皆需。

### 第三步：執漸進之易

由舊形漸遷功能於新形。

1. 定組件之序：
   - 先取最疏、最輕險者以立信
   - 漸進至要、至緊之組件
   - 最要者最後（其時隊伍已熟）
2. 每組件：
   a. 於防腐層後置新版
   b. 並行：新舊同受其入
   c. 比其輸出——當等（或所異當預而書之）
   d. 信足則移流於新（翻功能旗）
   e. 察異象（易後增監察之敏）
   f. 穩之後，除此組件之舊版
3. 始終持續交付：
   - 每易一步乃常部署，非特事
   - 系統恆於已知、已試、可運之狀
   - 若易生患，退至前狀（仍可運）

**得：** 功能逐組件而遷，每步有驗。系統恆可運。每易立信以進下一。

**敗則：** 若並行顯異，新實現有訛——易前修之。若易致性能降，新組件宜優化，或防腐層累贅過重。若隊伍半途失信，宜停而穩之——半遷於已知之狀遠勝於急而全遷。

### 第四步：守其蛹化之期

行最脆之時——系統介於二形之間也。

1. 承蛹之實：
   - 遷之中，系統半舊半新
   - 此雜狀本繁於純狀
   - 繁之峰在遷之半，後乃降
2. 蛹之律：
   - 蛹期無新功（唯蛻變）
   - 外變至少（凍非要之部署）
   - 增監與值守
   - 日察遷之進與系之健
3. 半蛹之察：
   - 行至半途，察：目標形猶是正鵠乎？
   - 市、求、隊有變乎，影及目標乎？
   - 蛻變當續、當停、當轉乎？
4. 護其蛹：
   - 退之路恆清
   - 書當前雜狀之詳（後之調試者需之）
   - 莫誘於「清」暫設之架於遷未畢時

**得：** 蛹期作為有意、有期之段而守，律更嚴，察更密。隊知暫繁乃安蛻之價。

**敗則：** 若蛹期過長，雜狀成新常——此惡於新舊也。立時限。若逾限，或速其餘遷，或納雜狀為「新形」而穩之。

### 第五步：蛻成而穩

終其變，撤其架。

1. 末易：
   - 遷最後一組件入新形
   - 行全驗套於新系
   - 於產境等量之載下測其性能
2. 撤鷹架：
   - 除防腐層（無用矣）
   - 除遷相關之功能旗
   - 清並行之基
   - 存（勿刪）舊系之碼為參
3. 蛻後之穩：
   - 於新形運二至四週，增察
   - 解現實條件下所現之患
   - 更文檔以映新架構
4. 覆盤：
   - 蛻中何者善成？
   - 何者難於所料？
   - 下次當作何異？
   - 更隊伍蛻變之譜

**得：** 蛻已成。系統運於新形。鷹架已撤。文檔已更。隊伍捕獲所學，以利將來之蛻。

**敗則：** 若新形易後未穩，保退路而續穩之。若穩期逾所計，新架構或有設計之患——察是否宜修正或退最患之組件。

## 驗

- [ ] 蛻之藍圖顯可行中間形
- [ ] 鷹架（防腐層、退機、驗架）在遷前已具
- [ ] 組件由輕險至重險之序而遷
- [ ] 並行驗每步之等
- [ ] 蛹期有限而凍新功
- [ ] 蛻畢所有鷹架皆撤
- [ ] 蛻後之穩期無重患
- [ ] 覆盤捕學

## 陷

- **驟遷**：欲一舉而盡變。棄漸易之安，最大其爆圍。必漸遷之
- **架不撤**：防腐與功能旗久之不除乃成技債。撤架當作蛻之一段，非事後之想
- **諱蛹**：假雜狀為常致新功建於浮基。宜承蛹期而守其律
- **目標之執**：溺於目標而視更佳之路而不見。半蛹之察正為此設
- **蛻疲**：久遷耗人。每步宜小，日計可成，非週計。慶里程以續其勢

## 參

- `assess-form` — 前置之察，定系統是否宜蛻
- `dissolve-form` — 過剛而不可直蛻之系統；溶之以開縫
- `repair-damage` — 若蛻致損之復法
- `shift-camouflage` — 表層之適，或免深架之變
- `coordinate-swarm` — 群協之序啟分布式蛻變之次
- `scale-colony` — 長之壓常啟架構之適
- `implement-gitops-workflow` — GitOps 提供漸易之部署基
- `review-software-architecture` — 審目標架構之補

