结论先说
- 治好前后端字段打架的唯一根治法是「契约文件先行,严禁口头传话」:写任何业务代码前,先开 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 条评论
还没有评论,来抢沙发~