Agent-almanac adapt-architecture
install
source · Clone the upstream repo
git clone https://github.com/pjt222/agent-almanac
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/wenyan/skills/adapt-architecture" ~/.claude/skills/pjt222-agent-almanac-adapt-architecture-5b9f84 && rm -rf "$T"
manifest:
i18n/wenyan/skills/adapt-architecture/SKILL.mdsource content
變架構
執結構之蛻變,使系統由舊形而至新形,而運行不輟。用絞榕之遷、蛹化之階、界面之守,以全其功於變之中。
用時
- 形之察(見
)定系統為 READY 乃用assess-form - 架構宜更以應新求而不停機乃用
- 由巨石遷至微服(或反之)乃用
- 易核心之部而餘依之系統仍運乃用
- 更數據之模而守舊約乃用
- 凡架構之變宜漸而非驟者乃用
入
- 必要:當前形之察(出
或同類之析)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
— GitOps 提供漸易之部署基implement-gitops-workflow
— 審目標架構之補review-software-architecture