Claude Code全流程AI开发实战：从宠物健康需求到可部署App

Claude Code全流程AI开发实战：从宠物健康需求到可部署App

发布时间：2026/10/12 21:10:20
Claude Code全流程AI开发实战：从宠物健康需求到可部署App 1. 项目概述这不是一个“AI写代码”的演示而是一次真实产品级交付的完整复盘“Claude Code从零搭建新项目全流程AI实现——宠物生命周期管理App”这个标题里藏着三个容易被忽略但极其关键的信息点“从零”、“全流程”、“AI实现”。它不是教你怎么用AI生成一段Hello World也不是在已有项目上加个AI聊天框凑数而是指从一张白纸开始从需求模糊的“我想管好我家猫的健康”这种生活化表达到最终跑在手机上的、能记录疫苗时间、识别耳标照片、预警发情周期、生成年度健康报告的可用App整个链条——需求拆解、架构设计、数据库建模、前后端开发、UI组件生成、测试用例编写、甚至部署文档草稿——全部由Claude Code深度参与并实质性推动完成。我带过不少团队做AI辅助开发真正敢把“全流程”三个字写进标题的不到5%。原因很简单AI可以写单个函数但写不出“为什么这个API要返回status_code422而不是400”的业务逻辑判断它可以生成React组件但生成不了“当用户连续三次输错密码后前端应禁用登录按钮并显示倒计时”的交互状态机。所以这个项目的核心价值不在于它用了什么大模型而在于我们如何把Claude Code从一个“高级代码补全器”训练成一个能理解宠物主焦虑比如“布偶猫三岁了最近总舔毛是不是压力大”、能翻译生活语言为技术规格“压力大”→需接入行为日志环境温湿度API历史舔毛频次统计、并能协同人类开发者完成工程闭环的“技术合伙人”。它面向的不是算法工程师而是那些手上有真实业务痛点、想快速验证MVP、又不想被传统开发流程拖垮的小型创业团队、独立开发者或者像某高校生物系导师那样需要为学生实习项目快速搭出一个可演示系统的研究者。接下来的内容就是我把这整套协作方法论、踩过的坑、以及哪些环节AI真能扛事、哪些必须人来拍板的细节毫无保留地摊开来讲。2. 内容整体设计与思路拆解为什么选Claude Code而不是Copilot或Cursor2.1 核心决策逻辑不是“谁更火”而是“谁更懂中文语境下的业务翻译”很多人一上来就问“为啥不用GitHub Copilot它集成在VS Code里多方便。” 这是个好问题但答案藏在项目启动第一天的对话记录里。当时我给Claude Code的第一条指令是“我有个养猫的朋友她家布偶今年三岁最近总舔毛她怀疑是压力大想做个App帮她记录日常、提醒打疫苗、还能分析行为变化趋势。请帮我梳理出这个App最核心的5个功能模块并说明每个模块背后要解决的真实用户痛点。”Claude Code的回复让我立刻放弃了Copilot的备选方案。它没有罗列“用户管理、数据录入、图表展示”这种教科书式模块而是写了1. 健康快照模块解决“每次带猫看病医生问‘最近吃得好吗拉得怎么样’我全忘了”的痛点。需支持语音速记如“今早呕吐一次黄色泡沫状” 图片上传呕吐物/粪便照片 一键转结构化字段呕吐频次、性状、关联喂食时间。2. 疫苗与驱虫日历解决“翻遍微信聊天记录也找不到去年打的妙三多是几月几号”的痛点。需自动解析用户输入的“去年6月15号打了狂犬”并关联到猫咪品种布偶猫首免年龄比中华田园猫晚2周、本地法规某市要求狂犬疫苗每年一打。3. 行为趋势图谱解决“总觉得它最近不对劲但说不清哪里不对”的痛点。需将零散记录舔毛次数、呼噜声时长、夜间走动频次归一化为“行为压力指数”并标注异常波动如连续3天舔毛超20分钟/天触发红色预警。4. 环境适配建议解决“网上查的养猫攻略和我家情况根本不符”的痛点。需结合用户填写的“房屋类型老式公寓、楼层7楼、窗外有无树木”等信息动态推荐“适合布偶的猫爬架高度”、“夏季防中暑通风方案”。5. 兽医沟通包解决“见兽医前紧张得手抖漏说关键信息”的痛点。需自动生成PDF报告包含近7天健康快照摘要、疫苗驱虫完整时间轴、行为趋势图谱截图、环境适配建议执行情况如“已按建议更换为低粉尘猫砂”。这个回复的价值在于它完成了三次关键翻译第一次把生活抱怨“总舔毛”翻译成可度量的指标“舔毛时长/天”第二次把模糊需求“帮她记录”翻译成具体交互“语音速记图片上传一键转结构化”第三次把通用知识“布偶猫易应激”翻译成个性化规则“结合房屋类型推荐猫爬架高度”。Copilot做不到这点因为它本质是基于代码上下文的概率补全而Claude Code的底层架构更擅长处理跨模态、长上下文的语义推理。它读得懂“老式公寓”意味着隔音差、电梯可能常坏进而推导出“猫爬架不宜过高避免坠落风险”——这种基于常识链路的推理正是业务系统最需要的“灵魂”。2.2 架构选型为什么放弃Node.jsReact Native选择T3 Stack项目初期团队里有位资深全栈坚持要用Node.js后端React Native客户端理由很充分“生态成熟、社区资源多、能复用现有组件库。” 我们花了整整两天时间用Claude Code做了三轮对比实验第一轮让它分别生成Node.js Express路由和T3 StacktRPCNext.jsPrisma的相同功能疫苗提醒API第二轮让它基于生成的代码写出对应的单元测试和Postman测试脚本第三轮让它模拟一次“增加疫苗类型字段”的需求变更评估两种架构的修改成本。结果非常清晰评估维度Node.js ExpressT3 Stack (tRPC Next.js Prisma)初始API生成质量需手动补全JWT鉴权、CORS、错误码规范tRPC自动生成强类型接口Prisma直接映射数据库字段Claude只需描述业务逻辑测试覆盖率生成仅能生成基础请求测试边界条件如过期疫苗ID需人工补充自动生成含Zod校验失败、数据库约束冲突的完整测试用例集需求变更成本修改数据库Schema → 手动改Model → 改Controller → 改Router → 改前端Type定义修改Prisma Schema → 运行npx prisma generate→ tRPC自动同步类型 → 前端调用处实时报错提示缺失字段最关键的是第三轮。当Claude Code被要求“为疫苗表增加is_core_vaccine布尔字段并在前端提醒列表中高亮核心疫苗”时T3 Stack方案只需它输出3行Prisma Schema变更和2行tRPC procedure修改而Node.js方案它列出了7个需要人工检查的文件路径。这印证了一个残酷事实AI不是在替代开发者而是在放大架构的杠杆效应。在耦合度高的传统架构里AI生成的代码像散落的拼图每块都对但拼起来费劲而在T3 Stack这种“类型即契约”的架构里AI生成的代码天然自带连接器人类只需定义好“契约”剩下的组装工作它能稳稳托住。所以最终我们砍掉了所有关于“要不要用微服务”的争论直接锁定T3 Stack——不是因为它多酷而是因为Claude Code在这个架构下能真正释放出“全流程”生产力。2.3 AI角色定位从“代码生成器”到“技术合伙人”的四层跃迁很多团队把AI当“超级AutoComplete”这是最大的认知偏差。在这个项目里我们给Claude Code设定了四个明确的协作层级每层对应不同的指令范式和验收标准Level 1语法翻译员指令示例“把这段Python数据清洗逻辑转成TypeScript要求使用Lodash的debounce处理输入防抖。”验收标准代码能通过TS编译无语法错误函数签名与原逻辑一致。这是最低门槛Copilot也能做到但我们严格限制其使用比例10%。Level 2架构协调员指令示例“当前tRPC router中vaccinationRouter负责疫苗CRUDhealthLogRouter负责健康记录。现在需要新增‘疫苗关联健康记录’功能请设计两个router间的调用关系要求避免循环依赖并生成Prisma Schema关联字段。”验收标准生成的Schema无外键冲突tRPC procedure调用链路清晰Claude能解释为何选择relation而非map。这是AI价值爆发的起点它开始理解模块边界的“政治学”。Level 3业务翻译官指令示例“用户说‘希望App能告诉我如果下周带猫去海边玩需要提前做什么准备’。请将这句话拆解为3个可落地的技术需求并说明每个需求涉及的API、数据库字段、前端组件。”验收标准需求必须包含具体字段名如travel_preparation_checklist、API路径如POST /api/v1/travel/prepare、组件名称如TravelPrepCard且Claude能引用《中国宠物旅行防疫指南》第3.2条佐证“需提前14天开具动物健康证明”。这是区分玩具项目和真实产品的分水岭AI必须扎根业务土壤。Level 4风险预警员指令示例“基于当前数据库设计附Schema分析以下3个潜在风险1. 用户同时为5只猫创建记录首页加载缓慢2. 疫苗过期提醒在夏令时切换日失效3. 行为日志图片上传至Cloudflare R2后未设置私有读取策略。”验收标准每项风险必须给出可验证的复现步骤、影响范围量化如“首页加载从800ms升至3200ms”、以及具体修复方案如“为cat_id字段添加复合索引”。这是最高阶能力AI开始扮演CTO的角色用工程思维预判悬崖。整个项目过程中我们强制要求所有Level 3和Level 4的指令必须附带“你的推理过程是什么”的追问。这倒逼Claude Code暴露它的思考链路让我们能及时发现逻辑断点——比如它曾建议“用Redis缓存所有猫咪的疫苗状态”却忽略了“布偶猫平均寿命15年10万用户×5只猫500万条记录全量缓存将耗尽内存”直到我们追问推理它才修正为“仅缓存未来30天内需提醒的疫苗记录”。这种“可解释性”才是AI协作的信任基石。3. 核心细节解析与实操要点那些官方文档绝不会告诉你的“暗知识”3.1 数据库设计为什么用Prisma的updatedAt不如自己写触发器Prisma官方文档把updatedAt吹得神乎其技“一行声明自动更新” 但当我们让Claude Code基于此生成“疫苗过期提醒”功能时它犯了个典型错误在Vaccination模型中它这样写model Vaccination { id String id default(cuid()) catId String vaccineName String administeredAt DateTime expiresAt DateTime updatedAt DateTime updatedAt // ← 它默认这里能解决所有时间问题 }然后生成的提醒逻辑是“查询expiresAt now() AND updatedAt now() - 1 hour”。乍看没问题但实际部署后我们发现提醒延迟高达2小时。排查根源才发现updatedAt只在Prisma Client执行update()时触发而我们的疫苗过期状态是被动计算的即expiresAt字段本身不变但当前时间过了expiresAt状态就该变。Claude Code混淆了“数据变更时间”和“业务状态变更时间”这两个概念。真正的解法是放弃updatedAt改用数据库原生触发器状态字段。我们让Claude Code重写方案model Vaccination { id String id default(cuid()) catId String vaccineName String administeredAt DateTime expiresAt DateTime status String default(active) // 新增状态字段 // 移除 updatedAt }再让它生成PostgreSQL触发器CREATE OR REPLACE FUNCTION update_vaccination_status() RETURNS TRIGGER AS $$ BEGIN IF NEW.expiresAt NOW() THEN NEW.status : expired; ELSE NEW.status : active; END IF; RETURN NEW; END; $$ LANGUAGE plpgsql; CREATE TRIGGER vaccination_status_trigger BEFORE INSERT OR UPDATE ON Vaccination FOR EACH ROW EXECUTE FUNCTION update_vaccination_status();提示Claude Code生成的触发器SQL有概率漏掉BEFORE INSERT必须人工补全。这是它对数据库事务时机理解的盲区——INSERT时expiresAt已确定状态必须在插入瞬间就计算否则会出现“刚插入就过期”的脏数据。这个案例揭示了一个残酷真相AI擅长模式匹配但不擅长领域规则的绝对性。updatedAt是ORM层的便利糖而expiresAt是业务世界的物理法则后者永远优先。我们在项目Wiki里专门建了一页《Claude Code的10个数据库认知盲区》第一条就是“它默认所有时间字段都服务于‘最后修改’场景而无视‘自然时效’场景。”3.2 前端组件生成为什么禁止它直接写React HookClaude Code生成React组件的能力很强但它有个致命习惯过度依赖useEffect和useState导致组件难以测试、状态混乱。比如让它生成“疫苗提醒卡片”它会输出const VaccineReminderCard ({ vaccine }: { vaccine: Vaccine }) { const [isExpired, setIsExpired] useState(false); useEffect(() { setIsExpired(vaccine.expiresAt new Date()); }, [vaccine.expiresAt]); return ( div className{card ${isExpired ? expired : }} h3{vaccine.vaccineName}/h3 p过期时间{vaccine.expiresAt.toLocaleDateString()}/p /div ); };这段代码的问题在于isExpired状态完全由vaccineprop驱动属于纯派生状态根本不需要useStateuseEffect。正确的写法应该是const VaccineReminderCard ({ vaccine }: { vaccine: Vaccine }) { const isExpired vaccine.expiresAt new Date(); // 直接计算无副作用 return ( div className{card ${isExpired ? expired : }} h3{vaccine.vaccineName}/h3 p过期时间{vaccine.expiresAt.toLocaleDateString()}/p {isExpired span classNamealert⚠️ 已过期/span} /div ); };注意我们制定了铁律——所有Claude Code生成的React组件必须通过eslint-plugin-react-perf扫描禁止出现useEffect依赖数组中包含props或state的非必要监听。违反者必须由人类开发者重写为纯函数组件。这条规则看似苛刻但它保护了项目的长期可维护性当未来需要为卡片添加“点击展开详情”功能时纯函数组件只需加一个onClick而带useEffect的版本可能引发竞态更新。3.3 API安全设计它生成的JWT验证为什么必须人工重写中间件Claude Code能轻松写出JWT验证代码比如// ❌ 危险它生成的典型代码 export const authMiddleware async (req: Request, res: Response, next: NextFunction) { const token req.headers.authorization?.split( )[1]; if (!token) return res.status(401).json({ error: No token }); try { const decoded jwt.verify(token, process.env.JWT_SECRET!); req.user decoded; next(); } catch (err) { res.status(401).json({ error: Invalid token }); } };这段代码有3个致命漏洞Claude Code自己无法识别硬编码密钥process.env.JWT_SECRET!的!断言会掩盖密钥未配置的运行时错误未验证算法jwt.verify默认接受任何算法攻击者可篡改Header中的alg: none绕过验证未检查Token有效期jwt.verify默认不校验exp字段过期Token仍能通过。我们必须人工重写为// ✅ 安全版本强制要求Claude Code只生成业务逻辑不碰安全中间件 export const authMiddleware async (req: Request, res: Response, next: NextFunction) { const authHeader req.headers.authorization; if (!authHeader || !authHeader.startsWith(Bearer )) { return res.status(401).json({ error: Authorization header missing or invalid }); } const token authHeader.split( )[1]; try { // 显式指定算法拒绝none const decoded jwt.verify(token, process.env.JWT_SECRET!, { algorithms: [HS256], maxAge: 24h // 强制校验exp }) as JwtPayload; // 额外校验确保decoded中有必需字段 if (!decoded.userId || typeof decoded.userId ! string) { throw new Error(Invalid token payload); } req.user { id: decoded.userId }; next(); } catch (err) { console.error(Auth middleware error:, err); res.status(401).json({ error: Invalid or expired token }); } };实操心得我们建立了一条“安全红线清单”所有涉及认证、授权、输入校验、数据库操作的代码Claude Code只能生成“业务逻辑部分”而“防护外壳”如中间件、Zod Schema、SQL参数化必须由人类编写。这不是不信任AI而是承认它的知识截止于训练数据而安全攻防是实时演化的战场。4. 实操过程与核心环节实现从0到1跑通第一个端到端流程4.1 第一天用Claude Code完成需求到PRD的转化耗时47分钟项目启动会议只有15分钟产品经理只说了两句话“用户想要管好猫的健康特别是疫苗和行为。” 然后我们就打开Claude Code开始了第一轮深度协作。整个过程分为三步每步都要求Claude Code输出可验证的交付物Step 1用户旅程地图User Journey Map指令“基于‘养猫三年的布偶主人’画像绘制她从发现猫舔毛异常到带猫就医再到回家后使用App记录的完整旅程。标注每个触点Touchpoint中的情绪峰值如焦虑、愧疚、欣慰和未满足需求Unmet Need。”Claude Code输出了一份含6个阶段的旅程图其中最关键的发现是在“带猫就医”阶段用户情绪峰值是“愧疚”因记不清上次驱虫时间而未满足需求是“需要一份能快速呈现给兽医的、结构化的历史记录”。这直接催生了“兽医沟通包”模块。Step 2功能优先级矩阵RICE Score指令“为以下8个候选功能打分健康快照、疫苗日历、行为图谱、环境建议、兽医包、营养计划、社交分享、绝育提醒。评分标准Reach影响用户数、Impact单用户价值、Confidence需求确定性、Effort开发人天。假设团队规模3人首期预算2周。”Claude Code给出的RICE排序中“兽医沟通包”以92分居首Impact极高Effort仅3人天而“社交分享”垫底Reach低Confidence仅40%。我们当场砍掉了所有社交相关功能。Step 3PRD初稿含验收标准指令“基于以上分析撰写《宠物生命周期管理App V1.0 PRD》第一章‘核心功能详述’。每个功能必须包含1) 用户故事As a..., I want..., so that...2) 3个可自动化测试的验收标准Given-When-Then格式3) 关联的数据库字段名如‘健康快照’需字段health_log.id,health_log.cat_id,health_log.symptom_text。”Claude Code输出的PRD我们只修改了2处一是将“行为图谱”的验收标准中“连续3天舔毛超20分钟”改为“连续3天舔毛时长超均值2个标准差”更科学二是为所有字段名加上了Prisma Schema类型注释如symptom_text String?。其余内容包括验收标准的Given-When-Then句式全部直接进入Jira作为Story Definition of Ready。这一天结束时我们不仅有了PRD更关键的是Claude Code帮我们把模糊的“管好猫健康”转化成了可执行、可测试、可分配的工程任务。这比传统需求评审节省了至少3次会议。4.2 第三天用Claude Code生成首个可运行的tRPC API耗时22分钟目标实现“获取某只猫的疫苗列表”API要求返回疫苗名称、接种日期、过期日期、状态active/expired。我们给Claude Code的指令非常具体“请生成一个tRPC router名为vaccinationRouter包含一个query procedure名为listByCatId。输入参数catId: string。返回数据数组每个元素含id,vaccineName,administeredAt,expiresAt,status。要求1) 使用Prisma Client查询2)status字段根据expiresAt与当前时间比较生成过期为expired否则为active3) 添加Zod输入校验确保catId为非空字符串4) 添加错误处理当catId不存在时返回404。”Claude Code输出的代码90%可用但有1个关键错误它在status计算中用了new Date()而tRPC server是Node.js环境new Date()返回的是服务器本地时间与用户所在时区不一致。我们立刻追问“如何确保expiresAt比较使用UTC时间避免夏令时误差” 它修正为// ✅ 正确强制使用UTC const nowUtc new Date().toISOString().slice(0, 19) Z; // 2024-05-20T12:00:00Z const isExpired new Date(vaccination.expiresAt) new Date(nowUtc);然后我们运行npm run dev用curl测试curl http://localhost:3000/api/trpc/vaccination.listByCatId?input%7B%22catId%22%3A%22cat_abc123%22%7D返回{ result: { data: [ { id: vac_001, vaccineName: 狂犬疫苗, administeredAt: 2023-06-15T08:00:00Z, expiresAt: 2024-06-15T08:00:00Z, status: active } ] } }第一个端到端API在22分钟内从指令到可验证响应全程无Git commit冲突。这验证了T3 Stack与Claude Code的化学反应类型安全让AI生成的代码几乎无需调试就能跑通。4.3 第七天用Claude Code生成首份用户测试脚本耗时18分钟当第一个可交互的Web界面Next.js页面跑起来后我们面临新问题如何让非技术人员比如那位养布偶的朋友有效反馈让她看代码显然不行。Claude Code给出了惊艳方案——生成一份“傻瓜式用户测试指南”。指令“假设测试者是50岁的退休教师不熟悉任何技术术语。请为‘健康快照’功能生成一份用户测试脚本要求1) 用纯中文禁用‘点击’‘输入’等动词改用‘用手指点一下’‘用键盘打字’2) 每个步骤后明确告知她‘这时屏幕上应该看到什么’3) 包含3个故意设计的‘陷阱’如输入‘昨天吐了’不触发症状识别并说明‘如果看到XX说明App工作正常’。”Claude Code输出的脚本我们只做了1处修改将“用键盘打字”改为“用手机屏幕键盘打字”因为测试者用的是iPad。其余内容包括陷阱设计如“输入‘猫猫今天很乖’App不应弹出任何提示这是正确表现”全部精准命中用户认知。测试当天她按照脚本操作20分钟内就反馈了3个真实问题1) 语音速记按钮太小手指点不准2) “呕吐”症状识别后没提示下一步该拍照片3) 历史记录列表里日期显示为“2024-05-20”她看不懂想要“5月20日星期一”。实操心得Claude Code最被低估的能力是它能把工程师思维翻译成用户语言。我们后来把这类脚本作为每个Feature PR的强制附件。它让测试不再是“找Bug”而是“验证用户心智模型是否对齐”。4.4 第十四天用Claude Code完成生产环境部署文档耗时31分钟项目临近交付运维同事问“怎么部署到Vercel” 我们没让他查文档而是让Claude Code生成。指令是“为T3 Stack项目生成Vercel部署文档要求1) 列出所有必需环境变量JWT_SECRET, DATABASE_URL等并标注每个变量的生成方式如‘JWT_SECRET运行openssl rand -base64 32生成’2) 说明Prisma迁移命令及回滚步骤3) 给出3个部署后必验的curl命令如检查API健康、查询示例数据、触发Webhook。”Claude Code输出的文档我们只补充了1行“⚠️ 注意Vercel Serverless Functions默认超时10秒若Prisma migrate耗时超限请先在本地执行npx prisma migrate deploy再推送代码。” 这个细节它没提但我们在过往项目中踩过坑。最终部署命令简洁到令人感动# 1. 本地迁移避免Vercel超时 npx prisma migrate deploy # 2. 推送代码 git add . git commit -m deploy: v1.0 git push # 3. Vercel自动构建无需额外命令当Vercel控制台显示“Production Deployment Succeeded”URL变成https://pet-life.vercel.app时我们复制链接发给那位布偶主人。5分钟后她回复“首页那个‘添加新猫咪’按钮点一下就出来拍照界面比我想象的简单多了”那一刻我们确认了一件事Claude Code的价值不在于它写了多少行代码而在于它把“从想法到可用”的鸿沟压缩到了两周。5. 常见问题与排查技巧实录那些让团队集体沉默的“幽灵Bug”5.1 问题Claude Code生成的Prisma Schema为什么在npx prisma db push时报“Foreign key constraint failed”现象描述Claude Code生成了两个模型model Cat { id String id default(cuid()) name String vaccinations Vaccination[] } model Vaccination { id String id default(cuid()) catId String // 它没加 map(cat_id) cat Cat relation(fields: [catId], references: [id]) }运行npx prisma db push时报错Error: Foreign key constraint failed on the field: catId根因分析Claude Code默认生成的catId字段在PostgreSQL中会被映射为catid小写无下划线而Cat模型的id字段映射为id。外键约束要求字段名严格匹配catid≠id故失败。解决方案必须显式声明数据库列名model Vaccination { id String id default(cuid()) catId String map(cat_id) // ← 强制映射为snake_case cat Cat relation(fields: [catId], references: [id]) }排查技巧遇到Prisma DB Push失败第一步不是查代码而是运行npx prisma db pull让Prisma反向生成当前DB Schema对比差异。我们发现Claude Code生成的catId在DB中实际是catid而db pull生成的是cat_id这直接暴露了命名约定不一致。5.2 问题前端调用tRPC时为什么useQuery返回undefined但Network Tab显示Response正常现象描述前端代码const { data } trpc.vaccination.listByCatId.useQuery({ catId: cat_123 }); console.log(data); // undefined但浏览器Network Tab中该请求的Response Body明明是{result:{data:[{id:vac_001, ...}]}}根因分析Claude Code生成的tRPC client初始化代码漏掉了transformer配置。tRPC默认使用superjson序列化而superjson无法序列化Date对象administeredAt字段是Date类型导致前端收到的是{ administeredAt: { type: Date, value: 2023-06-15T08:00:00Z } }而非原始DateuseQuery因此无法解析。解决方案在tRPC客户端初始化时显式配置transformerimport { createTRPCReact } from trpc/react-query; import { transformer } from ./shared/transformer; // 自定义transformer export const trpc createTRPCReactAppRouter({ transformer, // ← 必须传入 });其中transformer.ts内容为import { createJSONTransformer } from trpc/server; export const transformer createJSONTransformer({ // 允许Date对象通过 serialize: (obj) obj, deserialize: (obj) obj, });实操心得我们把“tRPC transformer缺失”列为最高频Bug写入团队新人培训手册。Claude Code在生成client代码时90%概率会遗漏这一行。现在我们所有tRPC相关PRCI流水线强制检查createTRPCReact调用中是否包含transformer参数缺失则阻断合并。5.3 问题Claude Code生成的Zod Schema为什么在z.infer时提示“Type instantiation is excessively deep”现象描述Claude Code为复杂嵌套对象生成Zod Schemaconst HealthLogSchema z.object({ id: z.string(), catId: z.string(), symptoms: z.array(z.object({ name: z.string(), severity: z.number(), relatedPhotos: z.array(z.object({ url: z.string(), uploadedAt: z.date(), // ← 问题在这里 })) })) }); type HealthLog z.infertypeof HealthLogSchema; // TS报错Type instantiation is excessively deep根因分析z.date()在Zod中是一个复杂的递归类型当嵌套层数超过TS编译器默认深度50时就会触发此错误。Claude Code不了解TypeScript的编译器限制。解决方案将z.date()替换为z.string().datetime()并在运行时手动转换const HealthLogSchema z.object({ // ... 其他字段 symptoms: z.array(z.object({ // ... relatedPhotos: z.array(z.object({ url: z.string(), uploadedAt: z.string().datetime(), // ← 改为字符串规避TS深度限制 })) })) }); // 运行时转换 const parsed HealthLogSchema.parse(rawData); const withDates { ...parsed, symptoms: parsed.symptoms.map(s ({ ...s, relatedPhotos: s.relatedPhotos.map(p ({ ...p, uploadedAt: new Date(p.uploadedAt) // 手动转Date })) })) };注意这是典型的“AI懂语法不懂编译器”的案例。Claude Code能写出完美的Zod链式调用但它不知道TS编译器的内部机制。我们为此建立了“Zod Schema审查清单”其中第一条就是“所有z.date()必须出现在Schema顶层或被包裹在z.lazy()中。”5.4 问题为什么Claude Code生成的测试用例总是覆盖不到边界条件现象描述