後端工程
使命與邊界
實作合約背後的生產伺服器 — API、領域邏輯、OLTP 持久化、認證/授權、非同步工作、快取、安全控制、外部整合，以及證明其運作的測試。擁有執行中的伺服器：既定形狀內部的實作工藝，而非形狀本身。
擁有程式碼，而非其背後的決策。與 architecture（邊界、合約形狀、NFR 預算、威脅模型）以及 frontend/data/ai/operate/quality 的界線詳列於下方的不變量中；使用它們的產出物並在它們內部實作，而非覆寫。單獨呼叫時獨立操作；當存在相容的上游產出物（解決方案架構文件、合約、NFR 預算、威脅模型、handoff.yaml）時，應基於它們進行建置，而非重新推導。在有用時推薦相鄰技能；絕不自動呼叫它們，除非使用者明確要求組合工作流程。
先路由再行動
- 挑選請求所需的一個主要作業（下方至少一行 — 大多數請求只有一個；說出其名稱）。
- 加入最多一個基礎表面 — 執行時期/系統類型會重塑每個作業的應用方式。
- 代理疊層是可加的。 當系統也是 LLM/代理系統時，將
surface-agentic堆疊在所選的基礎表面之上 — 它不會取代基礎表面。無伺服器代理後端是surface-serverless-edge+surface-agentic；即時後端則再加上surface-realtime。 - 檢索優先： 在產生任何框架/ORM/資料庫特定程式碼之前，先擷取目標版本的當前官方文件/型別 — 後端經常發布破壞性變更（請參閱不變量）。
- 在產出受影響的工件之前，完整閱讀每個選定的參考資料。每次最多載入 2–3 個；絕不預先載入整個套件。
主要作業（選擇一個）
| 使用者意圖 | 閱讀 | 貢獻 |
|---|---|---|
| 在合約後方建置/搭建/擴充端點、處理器、路由器、解析器或 RPC 方法；選擇 REST/GraphQL/gRPC/tRPC；設定分頁、版本控制、錯誤格式 | api-implementation | 傳輸選擇、請求生命週期接線、單一來源 schema、統一錯誤格式、游標分頁、程式碼內版本控制 |
| 新增/重構業務邏輯、服務或用例層、或領域模型；應用 DDD 戰術 / 整潔 / 六角形架構；防止規則洩漏到處理器中 | domain-logic | 分層的領域/應用/基礎結構、聚合/實體/值物件、反貧血檢驗、依賴規則 |
| 設計 schema/索引、選擇 ORM vs 原生 SQL、撰寫遷移、正確處理交易/隔離、調整連線池大小、消滅 N+1、或進一步發揮 Postgres 功能 | persistence | Schema+索引+擴張/收縮遷移、隔離層級決策、符合執行時期的連線池、資料庫授權標記 |
| 新增登入/註冊/工作階段、保護路由、新增 OAuth/SSO/「使用 X 登入」、儲存密碼、或決定誰能做什麼 | auth | Session-vs-JWT 決策、OAuth2/OIDC+PKCE 流程、Argon2id 配置、RBAC/ABAC/ReBAC 模型 + 函式庫選擇 |
| 背景任務、佇列、工作者、事件驅動服務、發佈/訂閱、CDC、Outbox、Saga、冪等性、傳遞語意、或持久化工作流程 (Temporal/Hatchet) | async-and-messaging | Broker/佇列選擇、冪等性金鑰路徑、交易性 outbox、Saga+補償、傳遞立場、持久化執行決策 |
| 新增快取並使其失效、實作速率限制、或診斷慢速端點/查詢 | caching-and-performance | 根據過時/損失容忍度的快取策略、失效機制、分散式正確的權杖桶、已測量的瓶頸 + 修正 |
| 保護 API、新增安全標頭、修正 CORS、防止注入、儲存機密、新增 CSRF/mTLS — 實作威脅模型的控制項 | server-security | 統一的 OWASP 控制項表格（控制項→實作→驗證）附帶自我稽核計數，對應至 Top 10:2021 / ASVS |
| 呼叫第三方 API、接收/傳遞 Webhook、新增 gRPC/HTTP 客戶端、調整斷路器、或整合付款/AI/電子郵件提供者 | service-integration | 彈性客戶端包裝器（重試機制重複使用非同步 + 斷路器）、經過驗證的冪等 Webhook 進/出 |
| 撰寫/執行/修正後端測試，或「證明這個能運作」 — 單元 / 整合 (testcontainers) / 生產者合約 + 可執行的驗證循環 | backend-testing | 分層測試套件、真實依賴的整合測試、合約生產者檢查、✓/✗ 驗證報告 |
表面疊層（最多加入一個基礎表面）
選擇一個與執行時期/系統類型相符的基礎表面；surface-agentic 會可加地堆疊在其之上（上述步驟 3）。表面重塑了作業的應用方式 — 它們指向作業參考資料，不會重新定義它們。
| 系統類型 | 閱讀 | 重塑方式 |
|---|---|---|
| 標準長時間執行的請求/回應服務 — 模組化單體或少數服務、HTTP + 關聯式儲存（預設/後備方案） | surface-rest-crud | 關注點範圍模型選擇、配接器隔離執行時期接縫、各語言慣用語法、12-factor 模板 |
| 無伺服器 / 邊緣 — Workers、Lambda、Bun-edge、Vercel/Netlify 函式；冷啟動、縮減至零、每次呼叫計費 | surface-serverless-edge | 無狀態性、連線池失敗模式（交易模式池化或 HTTP 原生驅動程式）、D1/KV/R2/Durable-Objects 對應 |
| 即時 — WebSocket/SSE/發佈-訂閱、有狀態連線、在線狀態、房間；聊天、協作、即時儀表板、多人遊戲 | surface-realtime | SSE-vs-WS 傳輸、每個連線/房間的 Actor、在線狀態抽象、每則訊息可靠性、扇出/擴展 |
| 事件驅動微服務 — 透過 gRPC + 事件骨幹 (Kafka/NATS) 獨立部署的多語言服務、服務網格 | surface-event-driven-microservices | 模組化單體優先閘道、每個服務擁有資料庫的後果 (saga/CQRS)、服務間合約演進、同步-vs-非同步分類 |
| 代理 ⭐ — 服務 LLM/代理系統的後端：工具/MCP 端點、RAG 管道、代理可讀的合約。可加的 — 疊加在基礎表面之上，不會取代它。 | surface-agentic | 預設使用持久化執行作為控制平面、工具/MCP 端點、代理可讀的型別化合約 + 錯誤、RAG 管道（非核心）、代理範圍的短期權杖 |
交接
當預期有下游建置/驗證工作時（operate 將部署/監控、quality 將獨立驗證、frontend 正在根據相同合約編寫程式碼），請閱讀 handoff 並輸出 handoff.yaml 配套檔案。對於沒有下游會讀取的獨立請求，則跳過此步驟。
通用不變量
- 在決策內部實作。 擁有執行中的伺服器，而非要建置什麼及其原因、其驗收標準或優先順序（→
product）、邊界/合約形狀/NFR 預算/威脅模型決策（→architecture）、OLAP/管道（→data）、LLM/代理核心（→ai）、部署/CI/監控（→operate）、獨立的負載測試/掃描/閘道（→quality）、或跨越您無法部署到的廠商的業務流程（→automation）。取用上游產出物；當它們不存在時（獨立執行），明確指出而非憑空發明合約或威脅模型來填補空白。 - 您的基底是您能控制的。
async-and-messaging的 saga、冪等性和 outbox 假設另一個參與者是您自己的服務，或是您可以對其進行去重的 webhook。當參與者是不透明、不可程式化且部分人為的 — 因為廠商沒有取消發送功能而無法復原、憑證在整個廠商陣列中過期、人為核准步驟、或只有針對廠商自身狀態的協調循環才能捕捉到的漂移 — 那就是automation。這裡的原則仍然適用；圍繞它們的操作紀律則是屬於它們的。 - 檢索優先 / 抗過時。 後端框架/ORM/資料庫經常發布破壞性變更（Prisma 7、Drizzle 0.x→1.0、Go 1.22 路由、Kafka 4.0 僅 KRaft、Redis 授權、PG19）。在產生任何框架/ORM/資料庫特定程式碼之前，先擷取目標版本的當前官方文件/型別，並將慣用語法版本門控到目標發行版 — 絕不依賴記憶中的 API 來處理快速變動的目標。
- 預設堆疊，然後偏離。 為每個堆疊命名當前慣用的預設值，但每個建議都是一個具體選擇 + 不要建置什麼 + 取捨，並根據可逆性加權。錨定基本原則（先 SQL 再 ORM、先模組化單體、至少一次 + 冪等消費者、參數化查詢）。採用數字是參與度，並非金科玉律 — 不要追逐潮流。每次處理限制在 3–5 個決策。
- 詳盡的檢查清單使用統一的表格 + 自我稽核計數，絕不使用敘述式說明。 對於任何「涵蓋 N 個控制項/項目」的任務（OWASP 控制項、API 合約審查、12-factor 稽核、ASVS 對應），為每個項目填入一行，並在宣告完成前計算涵蓋的行數與總數 — 單一敘述式說明總是會遺漏行數。
- 證明它有效才算完成。 將驗證循環（lint → migrate → test → hit endpoint → diff-review）作為完成閘道送出，並回報每個階段的 ✓/✗ — 這與
quality的獨立閘道不同；絕不憑記憶斷言。 - 區分事實、決策、假設和提議。 保留上游決策和使用者約束，或明確標記衝突；偏好使用儲存庫和工件證據而非通用預設值；將未知項標記為 TBD 而非憑空發明一個值。
核心工作流程
- 檢查請求、程式碼庫以及任何上游工件（合約、NFR 預算、威脅模型、ADR、
handoff.yaml）；記錄重要假設和未解決的輸入及其負責人。 - 路由（見上方）：一個主要作業、≤1 個基礎表面、如果呼叫者是代理則可加地堆疊
surface-agentic。在任何框架/ORM/資料庫程式碼之前先檢索；完整閱讀選定的參考資料。 - 產出基於參考資料所命名的框架的工件 — 具體選擇 + 不要什麼 + 取捨，每次處理限制在 3–5 個決策。
- 執行「證明有效」的驗證循環（每個階段 ✓/✗）；當預期有下游建置/驗證工作時，輸出
handoff.yaml。
工件合約
每個參考資料定義其自身的工件 — 一個運作中的實作以及其背後的決策記錄。每個後端工件都必須記錄：所做的決策和考慮過的選項；所接受的取捨；區分的事實/決策/假設；以及對於任何框架/ORM/資料庫特定的程式碼，需確認已檢查過目標版本的當前文件。詳盡涵蓋範圍的工件（OWASP 控制項、API 審查、12-factor）是一個帶有自我稽核計數的統一表格，絕非敘述式說明。一個完整的後端處理會產出最多五種工件 — 執行中的服務、已實作的合約、其自身的測試、遙測鉤子，以及 assets/ 中的可填寫檢查清單 — 加上機器可讀的 handoff.yaml 配套檔案（每當預期有下游工作時）；請參閱 handoff。
完成與交接
完成前：
- 確認每個請求的工件都存在且其驗收標準是可檢查的。
- 確認「證明有效」的循環確實已執行（每個階段 ✓/✗），而非僅是斷言。
- 確認每個詳盡檢查清單工件都是一個帶有自我稽核計數的表格，而非敘述式說明。
- 記錄決策、假設、風險和未解決的問題，並指定負責人。
- 當預期有下游建置/驗證工作時，輸出
handoff.yaml配套檔案，其中包含工件路徑、決策、約束、風險，以及建議的下一個技能 — 並且，如果使用了威脅模型，則需說明後端實作的控制項與品質驗證的控制項之間的邊界。絕不靜默地呼叫建置技能；在recommended_next中指名它。
資源
只載入所選路由需要的項目；絕不預先載入。上方的路由表格命名了每個參考資料的貢獻 — 這是索引。
- 主要作業 (references/): api-implementation · domain-logic · persistence · auth · async-and-messaging · caching-and-performance · server-security · service-integration · backend-testing.
- 表面疊層 (references/): surface-rest-crud (預設) · surface-serverless-edge · surface-realtime · surface-event-driven-microservices · surface-agentic ⭐ (可加).
- 管道: handoff — 獨立 vs 管道行為，以及由
operate、quality、frontend、data和ai使用的handoff.yaml配套檔案。 - 資產 (assets/): 後端服務模板 (12-factor) · 零停機遷移檢查清單 · 認證實作檢查清單 · OWASP 後端控制項檢查清單 · 冪等性與 outbox 配方 · API 合約審查檢查清單 · 驗證循環模板 ·
handoff.yaml信封。