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.md
source content

變架構

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

用時

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

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

第一步:繪變之藍圖

謀由當前至目標之蛻路。

  1. 繪變為諸中間形之序:
    • 當前形 → 中間形一 → … → 目標形
    • 各中間形必可運(能受流量、過試)
    • 無一中間形難於當前者
  2. 識變之縫:
    • 當前形何處可「切」以納新架構?
    • 天然之縫:既有界面、模塊之界、數據之分
    • 人為之縫:為切而設之界面(防腐之層)
  3. 擇蛻變之式:
    • 絞榕:新系繞舊而長,漸代之
    • 蛹化:舊系裹以新殼,內換而外穩
    • 出芽:新系並舊而生,流量漸遷(群落出芽見
      scale-colony
    • 蛻變遷移:依賴之序分階易之(葉先,根末)
  4. 設界面之守層:
    • 外部消費者不可覺其擾
    • 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
)以開縫。若中間形不可運,則其步過大——析為更小之增。

第二步:築其鷹架

建支蛻變之暫設基礎。

  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
    — 審目標架構之補