結論先說
- 治好前後端字段打架的唯一根治法是「契約文件先行,嚴禁口頭傳話」:寫任何業務代碼前,先開 Plan Mode(規劃模式) 把
openapi.yaml(或共享 Zod Schema)定死,把它當成前後端子代理共同遵守的唯一法律。 - 用
settings.json的deny規則把自動生成的類型目錄焊死:前端的接口類型只准由腳本(如openapi-typescript)從契約文件單向導出,禁止智能體手改生成物欺騙編譯器。 - 契約敲定後,派前後端兩個獨立子代理(或雙工作樹)並行落地:各自只看契約和本端源碼,互不污染上下文窗口。
- 全棧多代理聯調對週期會話消耗較高:按開發強度可在本站選擇 Claude Pro 充值說明 或重度開發首選的 Claude Max 充值頁。

圖:本站結合 Claude Code 官方工作流文檔 整理的協作模式對比圖
本文根據 Anthropic Claude Code 官方文檔《Common workflows》《Subagents》《Permissions》(code.claude.com/docs)整理,資料核對於 2026-11-19。配圖為本站整理的示意圖,不是軟件截圖。本站(bigolab.com)不是 Anthropic 官方網站。
適用於誰
- 一個人用 Claude Code 全棧包辦前後端,經常遇到「後端返回
created_at,前端組件裏卻寫成createdAt」反覆返工的獨立開發者; - 團隊前後端分離在兩個目錄或兩個倉庫,想靠一份
openapi.yaml讓兩邊智能體一次對齊零扯皮的技術負責人; - 頭疼智能體為了偷懶消掉 TypeScript 紅線,直接跑去手改自動生成的
api-types.d.ts掩耳盜鈴的程式員。
一、搭好防改亂護欄:鎖定生成目錄 + 四步閉環

圖:本站根據 Claude Code 權限與子代理機制 整理的四步聯調流程示意圖
在開始發提示詞之前,先在項目根目錄 .claude/settings.json 加一條硬拒絕規則,徹底堵死智能體「改不動業務代碼就去把類型文件改成 any」的壞毛病(權限語法詳見 Claude Code 安全與 deny 拒絕規則配置):
json
{
"permissions": {
"deny": [
"Edit(frontend/src/generated/**)",
"Write(frontend/src/generated/**)"
]
}
}
如果前後端拆在兩個相鄰倉庫,啟動時用 --add-dir ../backend 把兩邊掛進同一視野(前端與後端單端搭建基礎見 用 Claude Code 搭前端項目 與 後端 API 與數據庫開發)。
Claude Code 免上號訂閱與高配額省心方案:在大倉庫跑百萬上下文、多子包重構或複雜慢查詢排障時,固定月費訂閱比純按量 API 更容易鎖死成本上限。本站支持支付寶、微信支付與 AlipayHK 卡密自助兌換 iOS 鏈路的 Claude Pro 自助充值、5 倍額度的 Claude Max 5x 與頂配 Claude Max 20x,無需交出帳號密碼。
二、三段可直接複製的契約聯調提示詞模板
1. 階段一:切規劃模式起草並評審 OpenAPI 契約
先按兩次 Shift+Tab 切進只讀 Plan Mode(詳見 Claude Code Plan Mode 規劃模式教學),發送:
text
我需要新增「批量導出發票申請與異步下載狀態查詢」兩組接口。
請先閱讀現有的 contracts/openapi.yaml 了解我們團隊的分頁包裝格式與統一錯誤碼結構,起草本次新增路由的完整 OpenAPI 3.1 Schema 變更草案(含請求校驗約束、可空字段 nullable 顯式標註及 400/403/409 狀態碼響應體),先不要修改任何前後端業務源碼。
2. 階段二:生成類型並分派前後端子代理並行實現
人工看一眼契約草案確認字段命名與可空性滿意後,切回正常模式發送(自定義子代理寫法見 Claude Code 自定義子代理實例):
text
契約已確認。請按以下順序推進:
1. 將上述定義寫入 contracts/openapi.yaml,並運行 npm run gen:api-types 更新前端只讀類型文件;
2. 派一個後端子代理在 backend/src/invoices 下嚴格對照新契約實現路由、入參校驗與集成測試;
3. 派一個前端子代理在 frontend/src/features/invoices 下基於生成的強類型接口完成列表輪詢、空狀態與報錯提示,嚴禁使用 as any 強轉類型。
3. 階段三:契約一致性收尾核驗
text
請運行後端集成測試捕獲真實接口返回的 JSON 載荷樣本,逐字段比對 contracts/openapi.yaml 的定義(特別檢查日期字符串格式、空數組與 null 是否完全一致),並確認 frontend 下運行 tsc --noEmit 零類型錯誤。
人工必查清單:合併代碼前,請親自抽查三點——分頁總數 total 在空列表時返回的是數字 0 還是 null、枚舉字段新增狀態後前端 switch 有沒有兜底分支、以及權限失敗時有沒有把後端內部堆棧直接暴露進響應體。
常見問題
問:項目沒用 openapi.yaml,前後端都是 TypeScript 用 Zod 怎麼套這個流程?
答:完全一樣的道理。把共享的 packages/contracts/invoice.schema.ts 當作第一步先審定的契約文件,前後端同時 import 它推導出來的 z.infer 類型,甚至連代碼生成腳本都省了。
問:已有老項目根本沒有契約文檔,怎麼補第一份?
答:先讓只讀子代理掃描後端現有的 Controller 路由與 DTO 類,反向抽取生成第一版基準 openapi.yaml,跑通一次響應比對確認與線上現狀一致後,從下一個新需求開始執行契約先行。
問:智能體被 deny 攔住改不了 generated/ 目錄時會卡死嗎?
答:不會卡死。看到權限拒絕提示後,它會意識到那是生成物目錄,轉而去讀你在 CLAUDE.md 裏寫明的「改契約後運行 npm run gen:api-types 重新生成」指令走正規途徑更新。
問:後端已經用 NestJS 或 FastAPI 裝飾器自動吐出 OpenAPI JSON,還需要手寫 openapi.yaml 嗎?
答:代碼優先(Code-first)框架不需要維護兩份重複的 YAML。你可以把順序微調成「先讓後端子代理只寫 DTO 數據模型類與路由空殼 → 運行導出腳本生成最新 openapi.json 給前端導類型 → 前後端再並行填滿數據庫查詢與頁面渲染細節」,核心依然是先鎖死接口形狀、禁止前端手敲野生類型。
問:聯調時前端需要假數據看頁面效果,怎麼防止 Mock 數據寫死忘刪?
答:要求前端子代理統一使用基於 OpenAPI 自動生成的 Mock 攔截層(如 MSW),通過環境變量開關控制僅在本地開發態掛載,嚴禁在業務組件代碼裏直接硬編碼假數組返回。
問:國內沒有海外銀行卡,怎麼給 Claude Code 開通 Pro 或 Max 訂閱最穩妥?
答:可在 Claude Code 訂閱說明頁 或 Claude Max 充值頁 選擇走蘋果 iOS 官方內購鏈路的自助卡密,自己複製登入憑證提交即可到賬,全程無需把密碼交給他人;若帳號偶發彈出身份核驗,也可查看 Claude KYC 人工協助(失敗不收費,封號不在質保範圍)。
0 條評論
還沒有評論,來搶沙發~