adapt-architecture
About
This skill provides a methodical framework for executing gradual, low-risk architectural migrations, such as moving from a monolith to microservices. It employs patterns like the strangler fig, phased rollouts, and interface preservation to enable incremental change while the system remains operational. Use it when a prior assessment deems the system ready for transformation and a "big-bang" replacement is too risky.
Quick Install
Claude Code
Recommendednpx skills add pjt222/agent-almanac -a claude-code/plugin add https://github.com/pjt222/agent-almanacgit clone https://github.com/pjt222/agent-almanac.git ~/.claude/skills/adapt-architectureCopy and paste this command in Claude Code to install this skill
Documentation
變架構
執結構之蛻變,使系統由舊形而至新形,而運行不輟。用絞榕之遷、蛹化之階、界面之守,以全其功於變之中。
用時
- 形之察(見
assess-form)定系統為 READY 乃用 - 架構宜更以應新求而不停機乃用
- 由巨石遷至微服(或反之)乃用
- 易核心之部而餘依之系統仍運乃用
- 更數據之模而守舊約乃用
- 凡架構之變宜漸而非驟者乃用
入
- 必要:當前形之察(出
assess-form或同類之析) - 必要:目標架構(系統所當成者)
- 必要:運行連續之求(變中不可壞者)
- 可選:變之資(時、人、算力)
- 可選:退之求(可退至何處)
- 可選:並行之久(新舊並行幾何)
法
第一步:繪變之藍圖
謀由當前至目標之蛻路。
- 繪變為諸中間形之序:
- 當前形 → 中間形一 → … → 目標形
- 各中間形必可運(能受流量、過試)
- 無一中間形難於當前者
- 識變之縫:
- 當前形何處可「切」以納新架構?
- 天然之縫:既有界面、模塊之界、數據之分
- 人為之縫:為切而設之界面(防腐之層)
- 擇蛻變之式:
- 絞榕:新系繞舊而長,漸代之
- 蛹化:舊系裹以新殼,內換而外穩
- 出芽:新系並舊而生,流量漸遷(群落出芽見
scale-colony) - 蛻變遷移:依賴之序分階易之(葉先,根末)
- 設界面之守層:
- 外部消費者不可覺其擾
- API 版本、向後之約、適配之式
- 守層乃暫設之架——預其撤除
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)以開縫。若中間形不可運,則其步過大——析為更小之增。
第二步:築其鷹架
建支蛻變之暫設基礎。
- 建防腐之層:
- 新舊之間薄薄之譯層
- 依遷之狀,分派請求於舊或新
- 譯數據之形於新舊之間
- 此層為「繭」也,護其蛻變
- 設並行之基:
- 新舊二系可同時部署
- 功能旗掌何者受何流
- 比對之機驗新舊之輸出相等
- 立退之節點:
- 每中間形,驗可退至前形
- 退宜速於進
- 數據之遷可逆(或過渡中雙寫)
- 築驗證之架:
- 自動之試以驗連續運行
- 性能之量以測退化
- 數據完整之查以察遷誤
得: 鷹架(防腐層、並行、退機、驗證)具於遷前。鷹架本身已試已驗。
敗則: 若鷹架過費,可簡之:最少者一功能旗與退之程耳。防腐之層與並行雖增安,小變未必皆需。
第三步:執漸進之易
由舊形漸遷功能於新形。
- 定組件之序:
- 先取最疏、最輕險者以立信
- 漸進至要、至緊之組件
- 最要者最後(其時隊伍已熟)
- 每組件: a. 於防腐層後置新版 b. 並行:新舊同受其入 c. 比其輸出——當等(或所異當預而書之) d. 信足則移流於新(翻功能旗) e. 察異象(易後增監察之敏) f. 穩之後,除此組件之舊版
- 始終持續交付:
- 每易一步乃常部署,非特事
- 系統恆於已知、已試、可運之狀
- 若易生患,退至前狀(仍可運)
得: 功能逐組件而遷,每步有驗。系統恆可運。每易立信以進下一。
敗則: 若並行顯異,新實現有訛——易前修之。若易致性能降,新組件宜優化,或防腐層累贅過重。若隊伍半途失信,宜停而穩之——半遷於已知之狀遠勝於急而全遷。
第四步:守其蛹化之期
行最脆之時——系統介於二形之間也。
- 承蛹之實:
- 遷之中,系統半舊半新
- 此雜狀本繁於純狀
- 繁之峰在遷之半,後乃降
- 蛹之律:
- 蛹期無新功(唯蛻變)
- 外變至少(凍非要之部署)
- 增監與值守
- 日察遷之進與系之健
- 半蛹之察:
- 行至半途,察:目標形猶是正鵠乎?
- 市、求、隊有變乎,影及目標乎?
- 蛻變當續、當停、當轉乎?
- 護其蛹:
- 退之路恆清
- 書當前雜狀之詳(後之調試者需之)
- 莫誘於「清」暫設之架於遷未畢時
得: 蛹期作為有意、有期之段而守,律更嚴,察更密。隊知暫繁乃安蛻之價。
敗則: 若蛹期過長,雜狀成新常——此惡於新舊也。立時限。若逾限,或速其餘遷,或納雜狀為「新形」而穩之。
第五步:蛻成而穩
終其變,撤其架。
- 末易:
- 遷最後一組件入新形
- 行全驗套於新系
- 於產境等量之載下測其性能
- 撤鷹架:
- 除防腐層(無用矣)
- 除遷相關之功能旗
- 清並行之基
- 存(勿刪)舊系之碼為參
- 蛻後之穩:
- 於新形運二至四週,增察
- 解現實條件下所現之患
- 更文檔以映新架構
- 覆盤:
- 蛻中何者善成?
- 何者難於所料?
- 下次當作何異?
- 更隊伍蛻變之譜
得: 蛻已成。系統運於新形。鷹架已撤。文檔已更。隊伍捕獲所學,以利將來之蛻。
敗則: 若新形易後未穩,保退路而續穩之。若穩期逾所計,新架構或有設計之患——察是否宜修正或退最患之組件。
驗
- 蛻之藍圖顯可行中間形
- 鷹架(防腐層、退機、驗架)在遷前已具
- 組件由輕險至重險之序而遷
- 並行驗每步之等
- 蛹期有限而凍新功
- 蛻畢所有鷹架皆撤
- 蛻後之穩期無重患
- 覆盤捕學
陷
- 驟遷:欲一舉而盡變。棄漸易之安,最大其爆圍。必漸遷之
- 架不撤:防腐與功能旗久之不除乃成技債。撤架當作蛻之一段,非事後之想
- 諱蛹:假雜狀為常致新功建於浮基。宜承蛹期而守其律
- 目標之執:溺於目標而視更佳之路而不見。半蛹之察正為此設
- 蛻疲:久遷耗人。每步宜小,日計可成,非週計。慶里程以續其勢
參
assess-form— 前置之察,定系統是否宜蛻dissolve-form— 過剛而不可直蛻之系統;溶之以開縫repair-damage— 若蛻致損之復法shift-camouflage— 表層之適,或免深架之變coordinate-swarm— 群協之序啟分布式蛻變之次scale-colony— 長之壓常啟架構之適implement-gitops-workflow— GitOps 提供漸易之部署基review-software-architecture— 審目標架構之補
GitHub Repository
Related Skills
executing-plans
DesignUse the executing-plans skill when you have a complete implementation plan to execute in controlled batches with review checkpoints. It loads and critically reviews the plan, then executes tasks in small batches (default 3 tasks) while reporting progress between each batch for architect review. This ensures systematic implementation with built-in quality control checkpoints.
requesting-code-review
DesignThis skill dispatches a code-reviewer subagent to analyze code changes against requirements before proceeding. It should be used after completing tasks, implementing major features, or before merging to main. The review helps catch issues early by comparing the current implementation with the original plan.
connect-mcp-server
DesignThis skill provides a comprehensive guide for developers to connect MCP servers to Claude Code using HTTP, stdio, or SSE transports. It covers installation, configuration, authentication, and security for integrating external services like GitHub, Notion, and custom APIs. Use it when setting up MCP integrations, configuring external tools, or working with Claude's Model Context Protocol.
web-cli-teleport
DesignThis skill helps developers choose between Claude Code Web and CLI interfaces based on task analysis, then enables seamless session teleportation between these environments. It optimizes workflow by managing session state and context when switching between web, CLI, or mobile. Use it for complex projects requiring different tools at various stages.
