1. 项目概述为什么是“宠物生命周期管理”1.1 这个项目到底在解决什么问题宠物生命周期管理说白了就是给养宠家庭做一个“数字管家”。它要管的事情很具体这只宠物什么时候打的疫苗、下次什么时候要驱虫、体重有没有异常变化、每天的喂养计划是什么、要不要提醒去看医生。这些事单拎出来都不复杂但组合在一起就是一个典型的“业务状态多、时间节点多、用户角色不同、数据关联复杂”的中小型业务系统。选这个项目作为 AI 搭建案例性价比很高。它比“待办事项”复杂比“电商系统”轻量恰好适合展示 AI 辅助开发的完整链路需求分析、数据建模、接口设计、前端交互、测试验证。哪怕你完全不懂养宠物也不影响你理解这个项目的工程结构因为核心逻辑都是通用的用户管理、时间提醒、数据记录、状态流转。1.2 AI 在这个项目中承担什么角色Claude Code 不是“代替你写代码”的魔法棒它更像一个“理解力极强、执行力极高、但需要你把话说明白”的结对程序员。它能把 PRD 变成目录把目录变成代码把代码变成可运行的服务。但前提是你需要把“做什么、为什么做、做到什么程度”这三个问题想清楚。我在这个项目里给 Claude Code 分配的角色是后端 API 生成器、数据库模型设计助手、前端页面搭建辅助、测试用例生成器、代码审查员。它全程参与但每一步都需要我给出明确的校验点和验收标准。这不是不信任它而是对 AI 生成的代码保持应有的工程审慎。1.3 核心功能范围与验收标准在让 AI 动手之前先把项目边界划清楚。我定义的最小可行产品包含以下功能宠物档案管理添加宠物、编辑信息、查看详情、删除。字段包括昵称、品种、性别、生日、体重。疫苗记录管理给宠物添加疫苗记录包括疫苗名称、接种日期、下次接种提醒。驱虫管理记录驱虫时间设定提醒周期按月或按季度。健康事件记录记录就医、用药、异常情况支持备注和日期。日历提醒根据疫苗、驱虫等时间节点生成待办提醒列表。我明确告诉 Claude Code不需要用户登录、不需要支付、不需要社交分享、不需要多角色权限。这些不在本轮范围内避免 AI 发挥过度。这个决策非常关键因为模型天然倾向于“多做一点”而工程最怕的是“多做的那一点”带来失控的复杂度。验收标准也算清楚后端 API 能跑通增删改查数据库表结构能初始化前端页面能展示数据、能提交表单、能删除记录、能展示提醒列表。每个功能点都有对应的测试用例覆盖核心路径。2. 技术选型与项目初始化2.1 技术栈选择的背后逻辑工欲善其事必先利其器。针对这个项目选型时我主要考虑两个因素主流程度和与 AI 的适配度。模型对主流框架的训练数据足够多上下文理解更准确生成的代码更贴近可运行状态。冷门技术栈可以让 AI 能力大打折扣这是很多人的教训。我最终敲定的技术栈如下系统Windows 11 WSL2 环境。WSL2 的磁盘 IO 和网络转发在某些场景下比 Windows 原生终端更适合跑开发服务实测下来更稳。运行时Node.js 18 pnpm。选 pnpm 不是因为跟风而是它的依赖管理更严格不会出现隐式提升导致的“我本地能跑你本地跑不了”的问题。数据库SQLite Prisma ORM。SQLite 零配置适合项目快速启动Prisma 负责模型定义和迁移管理后期真要切换到 PostgreSQL改动成本也低。API 框架Express。经典、稳定、生态成熟Claude Code 对它的掌握程度最高生成代码的出错率最低。前端React TypeScript Vite。Vite 启动快、配置简洁TypeScript 提供类型约束能显著减少 AI 生成代码中的低级类型错误。这套组合不是唯一的答案但它非常配合 Claude Code 的能力边界。你可以根据自己项目的情况替换但原则是别选太偏门的技术否则 AI 的“经验”就不灵了。2.2 目录结构先定骨架再填血肉项目启动后我给 Claude Code 下达的第一个指令不是“生成代码”而是“分析并确认目录结构”。我先自己画了一个骨架让它在此基础上完善pet-lifecycle-manager/ ├── prisma/ # 数据库模型与迁移文件 ├── src/ │ ├── server/ # 后端入口、路由、控制器 │ ├── client/ # 前端组件、页面、状态管理 │ └── shared/ # 前后端共享的类型定义 ├── tests/ # 接口测试、组件测试 ├── scripts/ # 数据初始化、工具脚本 ├── docs/ # 设计文档与接口说明 └── package.json这个结构的好处是前后端分离清晰、共享类型有地方放、测试与源代码分开、文档有独立目录。Claude Code 在这种约定明确的目录结构下生成代码时的“自主发挥空间”被压缩到可控范围生成的路径引用、模块关系也更规范。有一点值得强调不要直接让 AI“帮我创建一个项目”它可能会生成一个庞杂但无用的目录。你需要的不是全而是准。先自己定骨架让 AI 填充血肉这是 AI 辅助开发中最重要的姿势。2.3 初始化实操全过程分步骤执行的初始化记录如下第一步创建项目目录进入目录用 pnpm init 初始化 package.json。这个文件是后续所有依赖安装的基础。第二步安装核心依赖。后端装 express、prisma/client开发依赖装 typescript、tsx、prisma、vitest、supertest。前端在 client 目录下通过 Vite 脚手架创建然后安装 axios、react-router-dom。第三步初始化 TypeScript 配置文件。我采用的是 strict 模式路径别名配置成 server/、client/、shared/*这样前后端引用共享代码时路径干净类型推导也不会因为相对路径绕晕。第四步初始化 Prisma。执行 npx prisma init生成 prisma/schema.prisma 文件后续所有模型定义都在这个文件里完成。初始化完成后我让 Claude Code 检查了一遍 package.json 和 tsconfig.json要求它找出版本冲突和配置缺失并解释每一个依赖的用途。这步在很多人看来有点多余但实际操作下来非常值得。你能借此对项目“吃得透”AI 也能更准确地理解你的技术栈基线后续生成代码时不会引入风格不一致的写法。3. 数据模型与后端 APIAI 协作的核心战场3.1 如何让 AI 准确理解业务需求同样的需求用两种方式描述Claude Code 的表现会天差地别。模糊描述做一个宠物管理系统能记录宠物的各种信息做好提醒功能。清晰描述宠物信息包括昵称、品种、性别、生日、体重。疫苗记录需要记录疫苗名称、接种日期、下次接种日期。驱虫记录需要记录驱虫药品名、上次驱虫日期、驱虫周期天。提醒功能根据疫苗和驱虫记录中的日期生成待办项需要在每次访问首页时计算并展示。差异非常明显。模糊描述下AI 会“自由发挥”字段你会得到一套需要反复改的数据模型清晰描述下AI 的生成结果与需求对齐度很高后续几乎不需要返工。这说明一个道理跟 AI 协作最核心的能力不是命令模型而是拆解业务。你要把自己当成一个产品经理把页面流程、字段清单、约束条件一条条列出来。AI 不需要你写得很有文采但需要你写得很结构化。3.2 数据模型设计从字段清单到 Prisma Schema我把字段和约束以表格形式贴在对话里让 Claude Code 基于它生成 Prisma schema模型名字段清单约束说明Petid, name, breed, gender, birthday, weight, createdAt, updatedAtname 必填weight 默认 0Vaccinationid, petId, vaccineName, vaccinatedAt, nextDueDate, notesvaccineName 与 vaccinatedAt 必填Dewormingid, petId, medicineName, dewormedAt, cycleDays, nextDueDatecycleDays 默认 90HealthEventid, petId, eventType, description, occurredAteventType 枚举Claude Code 生成 schema 后我逐字段核对了一遍发现两个问题。第一个nextDueDate 在第一版里不是独立存储而是通过计算得出。我要求改成显式存储因为显式存储更直观、便于后续查询排序也不容易因为时区问题导致日期错乱。第二个HealthEvent 的 eventType 没有设置默认值我要求加上必填约束避免前端误提交空类型。这两个改动都不大但说明一个关键点AI 生成的代码必须经过人工审查。它给出的方案可能合理但未必符合你的业务约束。你才是最终的决策者。修改确认后执行 npx prisma migrate dev --name init 生成迁移文件并同步数据库。到这里数据库层的工作已经具备可验证的基础。3.3 后端 API 设计与 RESTful 路由数据模型稳定后我开始设计 API 接口并让 Claude Code 用 Express 实现。接口全部采用 RESTful 风格按资源划分GET /api/pets - 获取宠物列表含疫苗、驱虫简要信息POST /api/pets - 新增宠物GET /api/pets/:id - 获取宠物详情含疫苗、驱虫、健康事件完整列表PUT /api/pets/:id - 编辑宠物信息DELETE /api/pets/:id - 删除宠物GET /api/pets/:id/reminders - 获取指定宠物的待办提醒POST /api/vaccinations - 新增疫苗记录POST /api/dewormings - 新增驱虫记录POST /api/health-events - 新增健康事件设计接口时我跟 Claude Code 明确了几条规则每条路由都放在独立文件中按资源模块组织不把所有逻辑塞进一个 index.ts。每条路由要有基本的参数校验。例如新增宠物时name 不能为空新增疫苗时vaccinatedAt 必须是有效日期。删除宠物采用级联删除同步删除其关联的疫苗、驱虫、健康事件记录。最高频的 API 是 GET /api/pets/:id因为这个接口要同时返回宠物详情和所有关联记录如果 N1 查询没控制好前端加载会明显变慢。我在指令里明确要求 Claude Code 使用 Prisma 的 include 语法一次性查完关联数据。生成代码后我用 curl 手工测了几个接口又把测试命令交给 Claude Code让它基于 supertest 编写接口测试覆盖新增、查询、更新、删除四条路径。随后执行所有测试确认全部通过。3.4 后端实现的关键细节后端的核心逻辑其实不复杂但有几个细节决定了代码质量。第一个是错误处理。我要求 Claude Code 加一个统一异常处理的中间件所有路由内的 throw 都会被它捕获返回 JSON 格式的错误信息而不是默认的 HTML 报错页。这样前端的 axios 拦截器才能统一处理错误状态。第二个是日期处理。Prisma 存储日期时按 UTC 处理如果代码里直接 new Date() 拿本地时间存进去和数据库里的 UTC 时间对不上查询结果时会差 8 小时。我让 Claude Code 统一在服务端用 UTC 规范输出前端展示时再转成本地时区。第三个是数据校验。我让 Claude Code 在服务层写了一个轻量的 validate 函数没有引入第三方的 validation 库因为这个项目的字段校验逻辑不复杂手写更直接可控。如果后续字段多到一定程度再引入 zod 也来得及。这三个细节如果交给 AI 自由发挥它大概率不会全部覆盖到。所以在你让 AI 写接口时把这些工程要求直接写进指令里是最省事的方式。4. 前端实现从空白页面到完整交互4.1 页面结构与组件拆分前端页面按照用户操作流程拆分首页宠物列表页展示所有宠物卡片支持新增、进入详情、删除。宠物详情页展示宠物基本信息下面分 Tab 展示疫苗记录、驱虫记录、健康事件、提醒列表。新增宠物页表单页支持录入宠物核心信息。新增记录页在宠物详情页内嵌的模态框支持添加疫苗、驱虫、健康事件。为了让 Claude Code 生成的前端代码与我的设计意图一致我先用文字描述每个页面的视觉布局和交互行为。比如首页我描述为“顶部标题栏下面两列栅格排布宠物卡片卡片显示宠物头像占位、昵称、品种、体重右上角是编辑和删除按钮底部按钮跳转新增宠物页”。这种描述方式能让 AI 生成的基础 UI 结构贴合需求后续只需要微调样式。4.2 状态管理与数据请求的关键决定前后端数据交互最忌讳每个组件各自发请求、各自管理状态这样数据流会陷入混乱。我让 Claude Code 在 src/client/store 下统一管理所有 API 调用使用 React Context 和 useReducer 组合方式管理宠物列表、当前选中宠物、加载状态、错误状态。之所以不用 Redux是因为项目规模尚小引入 Redux 反而会增加样板代码量。useReducer 加上 Context 足够满足需求后续真要扩展再替换也不迟。Claude Code 在实现时还自动加了数据缓存切换页面时如果数据没有变化就不会重复请求接口。这个优化虽然小但很实用。4.3 前端接口对接与交互细节前端页面搭好后我开始对接接口。为了让 Claude Code 理解接口的响应结构我把后端返回的 JSON 示例贴在对话中明确告知有哪些字段、什么类型、可能有什么错误。这个信息非常关键前端代码的类型安全就靠它支撑。对接过程中遇到过两个典型问题。第一个是日期控件格式问题。新增疫苗表单里的日期控件浏览器输出的是带时区的 ISO 字符串而后端 Prisma 存储的是 UTC 时间导致显示出来总是差 8 小时。我让 Claude Code 在前端把日期转成 YYYY-MM-DD 格式后再提交后端存储时用 new Date(dateString) 解析显示时再用本地时区格式化问题解决。这个时区问题看起来小但几乎是每个全栈项目都会踩的坑。让模型处理时区逻辑一定要给出明确的格式规范而不是只说“处理好日期”。第二个是删除确认的交互细节。列表页的删除按钮如果直接触发删除误点率太高。我让 Claude Code 在删除前弹出一个轻量的确认模态框要求用户输入宠物昵称进行二次确认。这个交互看着简单但对“误删数据”这种不可逆操作来说是非常必要的保护。它把这个安全机制写成一个通用组件后续任何需要二次确认的操作都能复用。4.4 前端工程的几个注意事项前端这块有几个注意事项值得单独拎出来说。第一组件的划分粒度要适中。颗粒度太细会导致 props 传递繁琐太粗会导致代码难维护。我定的原则是页面级组件负责数据请求卡片级组件负责展示按钮级组件负责交互。Claude Code 按这个原则生成代码后可读性和可维护性都好了不少。第二样式方案上我没有额外引入 UI 组件库而是让 Claude Code 直接写简单的 CSS 文件。这样做的好处是项目依赖更少、构建更快生成页面干净没有不必要的 UI 库代码。如果你的项目需要复杂的表格、下拉、弹层那引入成熟组件库是合理的但这种体量的项目手写更可控。第三前端路由需要统一处理“未匹配”的情况。我让 Claude Code 加了一个 404 页面并在路由配置里兜底。这个小细节虽然简单但很多 AI 生成的前端项目里往往会漏掉你会看到一个空白的浏览页面体验很差。5. 测试驱动的 AI 辅助开发闭环5.1 后端接口测试用例设计与执行功能开发完成后我让 Claude Code 基于已实现的接口补充一套完整的接口测试。测试框架选用 vitest 和 supertest数据库使用独立的测试库避免污染开发数据。测试覆盖的用例包括创建宠物成功POST /api/pets 携带合法参数断言返回 200 和正确的宠物对象。创建宠物失败POST /api/pets 缺少 name断言返回 400 和错误提示。获取宠物列表先插入两条数据再 GET /api/pets断言返回数组长度和字段完整性。删除宠物级联清理创建带疫苗记录的宠物删除后检查疫苗记录表是否同步删除。获取提醒列表插入具有未来疫苗日期的记录断言提醒列表返回了正确的 pending 状态。执行测试后有几个用例失败了。我把失败日志丢回给 Claude Code让它分析原因并修复。它定位后返回原因是创建宠物时体重字段没有做类型检查字符串 “12.5kg” 被直接存入数据库修复方式是统一在服务层做数值类型校验并在 Prisma 模型中将 weight 设为 Float 类型。修复后再次执行测试全部通过。这个排查过程看起来简单但如果换成没有 AI 辅助的开发你得手动翻代码、查日志、加断点至少要折腾半天。而 Claude Code 能直接定位到具体文件和具体行效率提升非常明显。5.2 前端组件测试与交互验证前端测试相对后端略复杂因为涉及 DOM 操作和事件模拟。这里我选择了 React Testing Library 配合 Vitest。测试的重点放在核心交互路径上渲染宠物列表并显示名称点击“新增宠物”按钮后能够弹出表单提交表单后列表中出现新增的宠物点击“删除”后弹确认框确认后宠物从列表消失测试用例执行期间发现了一个交互问题删除按钮绑定的事件在快速双击时触发两次。Claude Code 在监听函数里加了防抖处理并在删除接口请求期间对按钮设置禁用态问题解决。这类细节往往只有在测试驱动下才会被及时暴露。还有一点值得分享前端组件测试不需要追求全覆盖但核心的业务路径必须覆盖到。宠物列表的渲染、新增表单的提交、删除确认的交互这三个是用户最高频的操作路径覆盖了就相当于把用户体验的主干道守住了。其他旁支路径比如空列表状态、网络错误提示可以交给代码审查环节去查漏补缺。5.3 通过 AI 进行代码审查测试通过不代表代码质量过关。我给 Claude Code 加了一个“代码审查员”角色让它对后端路由、Prisma 模型、前端组件文件逐一审查要求它找出潜在问题并给出修复建议。这轮审查发现的问题包括部分后端路由缺少统一异常处理中间件数据库查询出错会直接抛出 500 并且返回堆栈信息这对生产环境是安全隐患。前端详情页接口请求失败时没有错误态展示用户会看到空白页不知道是网络问题还是数据问题。Prisma 模型中的索引不够优化对 petId 外键频繁查询却缺少索引。这些问题都在这轮审查中被补齐修缮。AI 生成代码往往“表面功能正确但健壮性不足”而代码审查正是把这层隐患挖出来的最有效方式。6. 部署与交付从“能跑”到“能交付”6.1 本地生产模拟与接口调试在部署之前我搭了一个本地生产模拟环境确保构建流程没有遗漏。步骤如下执行 pnpm build确认 TypeScript 编译和前端资源打包都通过。使用 pm2 启动生产模式服务访问 3000 端口测试首页加载、API 请求、静态资源路径。检查 .env 文件中的 DATABASE_URL 和生产环境配置差异把开发环境的 SQLite 数据库文件路径切换成独立的 prod 目录确保开发数据和生产数据隔离。这轮模拟跑下来发现一个问题前端构建后的静态资源路径是绝对路径 /assets/xxx.js部署到子路径时全部 404。原因是 Vite 配置里没有设置 base 选项。我修改 vite.config.ts 中的 base 为相对路径 ./\ 重新构建后资源路径全部变为相对路径部署到任意子路径都不再报错。这个坑有些项目上线了才发现幸好本地模拟阶段就暴露了。6.2 README 与交付文档的生成策略当功能稳定、测试通过、部署验证成功后我让 Claude Code 生成 README 和交付文档。我在指令里明确要求README 要包含项目简介、技术栈、快速启动步骤、测试命令、项目结构说明交付文档要包含接口文档、数据库表结构说明、环境变量说明、部署注意事项。这里有个原则要守住AI 生成的文档可以作为第一个版本但你必须自己过一遍把“生成痕迹”扫掉。模型生成的 README 往往有个通病它会把没有实现的功能也写进特性列表里。我逐条比对了 README 的功能列表与实际页面确认没有过度承诺才让它定稿。6.3 验收清单与最终交付交付前我先自测了一遍所有用户路径逐项确认是否满足当初定下的验收标准。然后让 Claude Code 基于原始的验收标准生成验收报告模板我再照着实际测试结果逐项填写。这个过程相当于一次完整的回归测试确保没有遗漏功能点。验收清单当时分成三个层次数据层、接口层、展示层。数据层主要看 Prisma migrate 是否干净执行、种子数据能否正常插入接口层看每个接口是否都按照预期返回状态码和数据结构展示层则人工点一遍页面看交互流程是否顺畅、提示是否到位。这个三层验收品思路适用于几乎所有全栈项目照搬即可。7. AI 辅助开发避坑指南我踩过的那些坑7.1 模型“一本正经地胡说八道”最大的坑是模型会在代码里给出“看似合理但实际不存在”的库或用法。有一次我要实现 Excel 导出功能Claude Code 给出了一个不存在的导出库名称还附带了一堆看起来非常合理的配置代码。我执行后报错核对后发现这个库在 npm 上根本没有。从那以后我给自己定了一条规则凡是 AI 给出的不熟悉依赖一律先 npm view [包名] 确认存在性和版本再安装绝不盲目执行。这条规则听起来基础但真能拦住不少坑。7.2 上下文丢失导致的前后不一致另一个常见坑是上下文丢失。当对话轮次过多、代码量过大时Claude Code 可能会出现早期定义的变量、函数名与后期生成的不一致。比如项目开始规定 API 路径全部以 /api 开头生成到后面某个页面时它可能直接发了一个 /pets 请求路径前缀缺失。解决方法是把“全局约定”写进项目根目录的 CLAUDE.md 文件里每次对话开始都让 Claude Code 先读取这个文件。我在 CLAUDE.md 里写清了目录结构、API 前缀、命名规范、测试命令等全局约定这样无论上下文如何切换它都会回到既有约定上来。实际使用下来这个文件的约束力远比我在对话里反复强调更有效。建议你也创建一份这样的文件里面至少包括项目简介、目录结构、代码风格约定、常用命令、环境变量说明。这个文件将成为整个 AI 协作会话的“宪法”非常关键。7.3 版本过期与依赖冲突第三个坑与时间相关。模型的知识截止到训练数据而工具链迭代太快。比如某个 API 在当前版本已经弃用但模型给出的还是旧写法。应对方案很直接用 npm outdated 检查依赖更新情况用 npm audit 检查安全漏洞必要时通过升级依赖版本强制模型使用新写法。我在项目后期遇到过 Prisma 的 schema 格式在版本升级后发生变化导致 migrate 命令无法识别旧格式。典型症状是执行npx prisma migrate dev时报错提示某个字段缺少属性。处理方法是先升级 Prisma 相关包然后让 Claude Code 根据报错信息修复 model 定义再重新执行迁移。如果你正卡在类似问题上可以直接把报错完整日志贴给 Claude Code让它分析原因并给修复方案比手动翻文档快得多。7.4 测试驱动的必要性最后聊一下测试。没有测试约束的 AI 生成代码就像没有检查点的流水线你不知道哪一步会产出次品。我强烈建议在项目开始时就确立“每条核心路径必须有测试”的纪律。测试一方面能拦截 bug另一方面是给 Claude Code 的“验收反馈”。当它生成的代码通过测试时它会更有信心地继续做新任务当测试失败时它也能定位到具体问题并修复。这种“生成-测试-反馈-修复”的闭环是 AI 辅助开发最有价值的工作模式。如果你时间紧张哪怕只写核心接口的测试也比完全不写强得多。7.5 一次“AI 永远修不对同一个 bug”的排查还有一个印象很深的案例。某前端页面在提交表单时数据总是发送不出去。Claude Code 连续给出了三版修复方案但每次跑完测试对应的问题依旧存在。我停下来重新审视发现根因是前端的 axios 实例配置里多了一个自定义的 headers导致后端无法识别请求体格式。这个配置是在某个早期版本里由 Claude Code 加上去的但因为上下文丢失它后续分析问题时根本看不到自己当初加的那段代码。这个案例给我的启示是AI 反复修不对一个问题时不要陷入“就问题而问题”的对话循环。这时应该自己动手看一遍请求头、Response 头、实际发出的数据体拿现场数据去问它而不是只在抽象层面描述现象。上下文丢失是模型的机制性弱点你得学会用工程手段帮它补上。写在最后AI 不是魔法而是放大器这次用 Claude Code 搭建宠物生命周期管理应用整个过程给我最大的感受是AI 把开发效率提升了一个量级但前提是使用者的思路必须足够清晰。它能把好的输入放大成更好的输出也能把模糊的输入放大成灾难性的返工。如果把 AI 辅助开发比作驾驶那模型是引擎你的需求定义、工程判断、审查习惯是方向盘。引擎再强方向盘握不稳车还是会冲进沟里。反过来说只要方向明确、约束清楚、验收到位引擎带给你的提速效果是过去任何工具都比不了的。如果你准备用类似的方式接新项目我的建议是开工前先花一个晚上把需求列表、字段清单、目录骨架、验收标准写清楚。哪怕只是写在备忘录里。这笔时间的投入会在后续开发的前三天里十倍百倍地赚回来。希望这次全流程拆解能给你一些可参考的思路。AI 写代码的门槛真的很低但把项目做成永远靠的是人的判断力。