AI编码实战：用Claude Code从零搭建宠物生命周期管理系统

我最近把一个积压很久的想法翻了出来：给家里那只猫做一套完整的生命周期档案。起初以为只是记录疫苗和驱虫时间，越拆越发现“生命周期管理”背后的复杂度远超想象——从领养、幼年、成年、绝育、疾病、老年，到最后的临终关怀，每只宠物都对应一条完整的时间线。靠表格和相册根本接不住这条时间线，于是我用Claude Code从零搭建了一个宠物生命周期管理App，并尝试把需求分析、数据库设计、功能开发、部署上线全流程交给AI推进。

这篇文章主要写给两类人：一是想用AI编码工具落地实际项目的开发者，二是想给自家宠物做一套“成长档案系统”但又不知道从哪下手的产品爱好者。我会把真实的项目推进过程摊开来讲，包括数据模型怎么设计、提示词怎么给、Claude Code在哪些环节容易翻车、以及我怎么兜底。不吹一口气产出一个完整App的玄学，只讲能复现的操作路径。

1. 为什么选“宠物生命周期管理”作为第一个AI全流程项目

1.1 需求拆解：宠物“生命周期”到底管理什么

很多事一旦落到“全生命周期”维度，就会被拉得很长。宠物不是简单的一个档案，它是多重事件叠加的时间序列。我列了一个最小事件集合，发现已经覆盖了一个普通养宠家庭绝大部分真实场景：

• 领养/到家：记录来家里的日期、来源、初始体重，这是时间线的起点；
• 疫苗：猫三联、狂犬病疫苗，每种疫苗有首次接种和次年加强的时间要求；
• 驱虫：体内驱虫每月一次、体外驱虫每季度一次，不同品牌略有差别；
• 绝育：绝育手术时间、术后恢复观察记录；
• 体重与体格：每月称一次体重，持续观察胖瘦走势；
• 疾病与就医：就诊时间、症状、诊断结果、用药记录；
• 特殊生命周期事件：发情、怀孕、绝育、临终关怀、离世纪念。

这些事件不是孤立的。它们共同构成一条可回溯的时间线，也共同决定了“下一步该做什么”。所以我给这个项目定的核心功能很明确：一是信息台账，二是主动提醒，三是时间线回顾。这个项目没有花哨的社交功能，也没有复杂的多人协作，数据模型足够真实，技术难度又恰好在一个独立开发者能扛住的范围内，很适合作为AI全流程开发的试验场。

1.2 用AI编码代理的前提：先有架构意识，再谈效率

很多人对Claude Code这类工具最大的误解，是以为给它一句“帮我写个宠物管理App”就能得到一个能上线的产品。实测下来，AI编码代理更像一个执行力极强的工程师，而不是产品经理。它可以非常快速地生成路由、表单、组件、ORM模型，但如果需求本身模糊，它就会用一套自以为合理的默认设计填坑，最后你反而要花更多时间改代码。

所以我做的第一件事，不是让AI写代码，而是自己先把架构定下来。我会在项目根目录放一份简短的README，写清楚以下内容：

• 项目定位：宠物生命周期管理，核心是事件时间线，不是普通通讯录；
• 目标用户：单家庭多宠物，不需要复杂权限体系；
• MVP范围：宠物档案、疫苗/驱虫提醒、体重趋势、事件时间线；
• 技术栈：前后端统一语言，单服务部署，数据库用轻量方案；
• 明确的非目标：不做宠物社交、不做支付、不做多语言。

这份README最大的作用，是每次新开一个Claude Code会话时，我都可以直接告诉它“先读一下README再开始动手”。它能把项目背景延续下来，让我不用在每一轮对话里重复解释我到底想要什么。

2. 从零到一：项目骨架与数据模型的落地

2.1 技术栈选型的博弈：轻量优先还是生态优先

我在技术选型上有过一段反复。最初考虑过前后端分离，用某个前端框架加Node接口再加MySQL，后来我否掉了这个方案。原因是“全流程AI搭建”阶段，链路越短，越容易留痕排查。跨了前后端、跨了多个服务，任何一个依赖版本错位都会让AI生成的代码在联调时大面积报错。

最终我选了前后端同构的全栈方案，核心是TypeScript。这个选择有三个理由：

• Claude Code对TypeScript极其熟悉，类型标注能减少很多“生成代码运行时才发现字段拼错”的问题；
• 同一个服务里既写服务端逻辑又写页面组件，不需要跨进程调试；
• 借助一个主流的ORM框架，可以把数据表结构写在单一Schema文件里，AI只需要读这一个文件就能理解全部数据关系。

数据库方面我用了轻量级的嵌入式数据库来做本地开发，部署时再切换到常规关系型数据库。这种“先用轻量、后上重度”的思路适合AI全流程构建：前期跑得动，后期IO和并发上来了再平滑升级。

2.2 数据模型：宠物档案、疫苗驱虫、健康记录、生命周期里程碑

数据模型是整个项目的灵魂。Claude Code能写一万行UI代码，但建模这步如果错了，后面每加一个功能都要做破坏性变更。我的Schema文件开头是这么设计的：

model User { id String @id @default(cuid()) email String @unique name String? pets Pet[] createdAt DateTime @default(now()) } model Pet { id String @id @default(cuid()) ownerId String owner User @relation(fields: [ownerId], references: [id]) name String species String // CAT / DOG / OTHER breed String? gender String // MALE / FEMALE birthDate DateTime? adoptedDate DateTime? sterilized Boolean @default(false) avatarUrl String? status String @default("ACTIVE") // ACTIVE / PASSED_AWAY events LifecycleEvent[] vaccines VaccineRecord[] dewormings DewormingRecord[] weights WeightRecord[] createdAt DateTime @default(now()) } model LifecycleEvent { id String @id @default(cuid()) petId String pet Pet @relation(fields: [petId], references: [id]) eventType String // ADOPTION / VACCINE / DEWORM / NEUTER / SICK / ESTRUS / PREGNANCY / SENIOR / MEMORIAL title String eventDate DateTime notes String? attachments String[] createdAt DateTime @default(now()) } model VaccineRecord { id String @id @default(cuid()) petId String pet Pet @relation(fields: [petId], references: [id]) name String vaccinatedAt DateTime nextDueDate DateTime? notes String? } model DewormingRecord { id String @id @default(cuid()) petId String pet Pet @relation(fields: [petId], references: [id]) drugName String dewormedAt DateTime nextDueDate DateTime? } model WeightRecord { id String @id @default(cuid()) petId String pet Pet @relation(fields: [petId], references: [id]) date DateTime @default(now()) weight Float }

这里最关键的一个设计决策是：我没有在Pet表里放一个固定的“生命周期阶段”字段，而是把阶段作为一组可推导的计算结果。为什么这么做？因为宠物的阶段是会动态变化的。如果数据库里存了“幼年”两个字，等到它该变成“成年”时，我就得写定时任务去更新字段；而如果只存出生日期和预期寿命，那么“当前处于哪个阶段”随时可以用公式算出来，永远不需要数据迁移。

2.3 生命周期阶段的计算逻辑：不靠魔法，靠年龄比例

生命周期管理的核心其实是“判断阶段 + 阶段建议”。我设定的判断逻辑很简单，用年龄与预期寿命的比例来划分：

• 幼年期：实际年龄小于预期寿命的10%；
• 成长期：实际年龄处于预期寿命的10%-30%；
• 成年期：实际年龄处于预期寿命的30%-70%；
• 初老期：实际年龄处于预期寿命的70%-90%；
• 老年期：实际年龄大于预期寿命的90%。

不同物种和体型的预期寿命不一样。猫的预期寿命我按15年算，狗则需要根据体型差异化处理：小型犬约15年，中型犬约13年，大型犬约10年。这些预期寿命值我写在了一个独立配置模块中，AI生成代码时会直接读取配置，而不是散落在各种组件里。

举个例子：一只大型犬，两岁半，预期寿命10年，年龄占比25%，它还在成长期；而同样两岁半的猫，预期寿命15年，年龄占比不到17%，也还算少年阶段。这种阶段计算会让后面“该打什么疫苗、该做什么体检”的建议逻辑变得非常清晰。

3. 核心功能如何借助Claude Code逐步实现

3.1 宠物档案模块：表单校验、图片上传与文件存储

这是最基础的模块，Claude Code实现得非常快。但我被坑过一次：我让它生成宠物资料的编辑表单，它直接给出了一个不带任何校验的版本，头像上传甚至直接把图片转成了Base64字符串塞进数据库。这在数据量小的时候能用，但录满几年照片之后数据库会迅速膨胀。

我在根README里补充了一条技术约束：“所有用户上传文件必须落盘到服务器文件目录，数据库中只存文件路径。”然后给Claude Code的提示词就非常明确：

实现宠物档案编辑页，包含昵称、物种、品种、性别、出生日期、绝育状态和头像。头像使用multipart/form-data上传，保存到服务器上的uploads/pet-avatars目录，数据库Pet.avatarUrl字段存储相对路径。表单需要结合zod做校验，名称至少1个字符，出生日期不能晚于今天。

这轮生成的效果好很多。AI自动产出了上传接口、静态目录挂载和表单组件。我还让它顺手生成了一个“头像裁剪”的纯前端预览逻辑，不传原图、只传裁剪后的Blob，这一块超出了我原来的预期，但确实是从数据库字段设计倒推出来的合理扩展。

3.2 生命周期时间线：把零散事件串成一条故事线

时间线功能是这个App区别于普通宠物档案的关键。我希望主页进入某只宠物后，能把疫苗、驱虫、体重、就医这些零散记录按时间倒序排列成一条故事线。

我给Claude Code的描述是这样的：

宠物详情页需要展示一条可筛选的时间线。从LifecycleEvent、VaccineRecord、DewormingRecord、WeightRecord四张表中拉取该宠物全部记录，按事件发生时间倒序渲染成纵向时间轴。时间轴左侧是日期，右侧是标题和备注。顶部提供按事件类型筛选的下拉框。

实现方式不复杂：服务端一次性查出来，前端按日期合并排序。这里我特意强调“一次性查出来”，是因为AI生成代码时很容易偷懒写多个串联await，在小数据量时感受不到问题，但时间线会变成瀑布式请求，后面优化成本很高。有了这个约束，Claude Code生成的查询用了Promise并行，并组装成了一个统一的TimelineItem数组。

3.3 疫苗与驱虫提醒：不靠定时轰炸，靠“到期窗口”

提醒是这个App真正能改善生活的功能，但它的实现思路需要仔细设计。如果每次到期就给人发一条提醒，用户很快会麻木；真正有用的是“宽限期窗口”。我的规则是：

• 已过期：nextDueDate小于今天，状态显示红色“已逾期XX天”；
• 即将到期：nextDueDate距离今天小于等于7天，状态显示黄色“还剩X天”；
• 正常：其他情况显示绿色“未到期”。

这个逻辑不依赖后台定时任务，而是每次页面打开时实时计算。对单家庭应用来说完全够用，也不用额外维护一堆调度进程。但在宏观层面，仍然需要一个每日巡检任务——万一用户一周没打开App，该系统就应该发送汇总提醒。

这个每日汇总任务我用Claude Code生成了一段脚本，挂在服务器周期任务里。它会扫描近14天所有疫苗和驱虫记录，找出“提醒但未处理”的项，组装成一条文本发到手机通知。提醒不是冷冰冰的“你的猫该驱虫了”，而是带上具体时间和上次用药名称，例如：“上次体内驱虫是3月1日，距今天已超过35天，建议尽快完成一次驱虫。”实测下来，带上下文的提醒比通用push的点击率高一截。

3.4 健康记录与体重趋势：可视化不多，但要有价值

体重趋势是宠物健康管理里最不该被忽视的数据。它不像疫苗那样有明确的日期节点，而是需要持续记录才能看出问题。我在体重记录页面设计了一个简易图表，横轴是日期，纵轴是公斤数，能叠加显示一条基于最近30次记录的平均趋势线。

Claude Code生成了图表组件和解析数据的接口。这里我给它补了一个核心约束：折线图中低于2kg的异常值要有提示标记，并且不允许直接删除历史记录，只能通过“新增一条修正记录”的方式来纠错。这是从真实兽医建议里听来的逻辑：体重数据讲究连续性，删点会让趋势失真得太厉害。AI对这种规则理解得很快，它自动在图表下方加了一条说明文案“体重趋势仅供参考，请勿替代专业兽医诊断”。这条文案加得挺聪明，后来我觉得所有涉及健康建议的页面都应该有类似表述，就统一在提示词里加了这句话。

4. 全流程中AI最容易“翻车”的环节与人工兜底

Claude Code在编程任务上表现出色，但离“免维护”还很远。我整理了这次项目中三类最容易出问题的场景，每类都踩过坑。

4.1 依赖版本冲突：AI不会主动去看锁文件

Claude Code生成的代码经常引用一些很新的API，但项目的依赖锁定在旧版本。比如它生成了一段使用某个工具库新写法的代码，实际安装的包还是老版本，就会直接抛“xxx is not a function”。这类报错比较迷惑人，因为报错位置往往不在依赖声明里，而在运行时调用处。

我总结的排查链路是这样的：

1. 先看报错堆栈指向的包的版本，与package.json里的声明是否一致；
2. 如果版本不符，优先让Claude Code“依据现有版本改写代码”，而不是直接升级依赖；
3. 升级依赖时要检查锁文件的变更范围，避免一个包升级引发一整个依赖树变化。

后面我把“项目依赖版本清单”写进了根目录上下文，让Claude Code在生成代码前先读一遍依赖清单。这个动作一度让我觉得像在带一个刚入职的同事：它效率很高，但需要明确告知项目里有哪些包、什么版本、哪些API可用。

4.2 权限与状态管理：上下文不清楚就会被AI“带偏”

Claude Code默认生成的页面是没有“用户身份”概念的。第一次生成宠物详情页时，它直接从一个全局参数取值，整个页面没有任何权限判断，任意登录用户都能看到任意宠物的档案。这让我倒吸一口凉气。

后续我把权限规则明确写进了项目规范：

• 所有宠物列表必须按当前登录用户过滤；
• 宠物详情接口必须校验Pet.ownerId与当前用户一致；
• 高敏操作用服务端校验，不在前端隐藏按钮，接口层同样校验。

这类约束不适合每轮对话都重复，于是我把它们放在全局的规则文件里，并告诉Claude Code“每次代码生成前都阅读这个规则”。效果是显著的：后面生成的新页面基本都能自动带上公共的鉴权判断，不用我每次追问。AI不是不会写安全代码，而是它不知道这套系统的安全边界是什么，这是产品约束问题，不是模型能力问题。

4.3 代码审查：AI生成的代码必须过两层检查

我自己有一个比较严的兜底流程：AI生成的每一份核心代码，必须先过静态检查，再补一个最小单元测试。静态检查能揪出未使用变量、类型错误、明显的逻辑漏洞；最小单元测试则保证核心函数在可控条件下行为正确。

比如阶段计算函数，我让Claude Code自己写单测，它写了三个用例：幼年、成年、老年。我补了两个边界用例：正好处于阶段切换临界点的日期，以及超过预期寿命很多年的老年宠物。这两个边界用例果然暴露了问题，它在临界点的取整逻辑上是“左闭右开”，导致刚好满多少岁那天会被多算一个阶段。修正方案是明确的：阶段切换时间必须包含当天，于是把边界判断从大于等于改成严格判断并追加一条测试。

所以我建议所有用AI做开发的团队都养成一个习惯：AI产出代码后，人至少要负责“看核心逻辑 + 补边界用例”。不要指望AI把测试和边界都想全了，它只能基于你的提示词和固有经验给出大概率正确的版本。

5. 部署上线与后续迭代：AI写代码之外的工程化细节

5.1 环境变量、容器化与低成本部署

代码写完后，部署又是一个独立战场。Claude Code帮我生成了一个多阶段构建的Dockerfile：第一阶段装依赖、跑构建；第二阶段用精简基础镜像只拷贝构建产物和运行所需的文件。这个思路比我手写的一个大而全镜像方案更好，镜像体积小了不少。

但部署脚本里有几个环境变量是AI替我做不了决定的：

• 数据库连接字符串；
• 上传目录的绝对路径和权限；
• 会话加密密钥；
• 外部通知服务的回调地址。

这些我都在环境变量注解文档里列清，Claude Code生成配置文件时会自动引用。我不建议把任何敏感值直接写进代码或镜像里，因为容器镜像一旦被推送，里面的环境变量会被持久化，这等于把钥匙挂在门上。

部署到云主机后，我用了很传统的做法：反向代理处理域名和HTTPS，进程守护工具管理Node服务。整个部署链路没有引入过于复杂的容器编排系统，一台低配置主机就够跑。这个选择对小型项目非常友好，出问题时排查路径也短。

5.2 自动化测试与CI：别把“能跑”当成“能交付”

项目功能迭代到第四周时，我开始感受到手动的回归测试成本。改一个时间线排序逻辑，可能影响疫苗列表、提醒页和主页三个入口。我在CI流水线里加了三件事：

• 代码静态检查：确保类型和语法没有明显问题；
• 核心函数单元测试：阶段计算、日期窗口、权限校验；
• 一次完整的Prisma迁移检查：保证Schema变更能顺利应用。

这个CI流程我保留得比较简洁，没有做端到端UI测试。原因很现实：个人项目的UI变化太快，写一套完整端到端测试维护成本太高，性价比不高。先保住核心逻辑，界面问题靠手动冒烟覆盖。

5.3 从MVP到成品的迭代节奏

我的迭代节奏刻意保持了两周一个版本。第一版只做宠物档案和基础时间线；第二版加入疫苗驱虫提醒；第三版才上体重趋势图表和生命周期阶段展示。每轮迭代我都有一个专门的“功能提示词文档”，把要做的功能、涉及的数据表、页面入口、验收标准写清楚，然后交给Claude Code分模块实现。

这个节奏的好处是，每一轮改动都能被完整地构建和部署，所有问题都能被隔离在当轮功能里。如果一次性把App的所有功能需求都交给AI，它往往会在复杂交互里迷失，生成的代码互相穿插，最后变成一堆补丁叠加。

6. 复盘：我用Claude Code做全流程项目的几个核心心得

6.1 提示词规范：任务越小，输出越稳

我发现把一个大功能拆成十几个小任务，比一次性给出完整需求在质量上高出非常多。例如“实现宠物档案模块”和“实现宠物档案编辑保存功能，包含表单校验、服务端接口、文件上传落盘”是两种体验。后者更稳定，因为AI不会自己脑补额外功能，也不会把文件上传、标签系统、历史修订一起塞进来。

我的提示词模板大概长这样：

功能目标：…
涉及数据表：…
当前文件结构：…
技术约束：…
验收标准：…
请只实现本次范围，不要重构无关代码。

这套模板把AI的行为边界划得很清楚。

6.2 上下文管理的三个技巧

长期使用Claude Code之后，我养成了三个习惯，这里直接分享出来：

第一，在项目根目录维护一份规范文档，让AI每次开工前先读。这份文档相当于团队里的项目Wiki，能解决大量重复解释成本。

第二，避免在一个会话里同时讨论多个互不相关的功能。切换任务时新建会话，并把上一轮的关键输出粘贴给新会话作为上下文。这样能让模型的注意力始终聚焦在当轮目标上。

第三，对AI的输出坚决执行“提交前审查”。每完成一个模块，我看一遍它改动过的关键文件，不只看有没有报错，更看有没有未定义边界、更新了不该改的配置。这种审查在前期多花10分钟，能省掉后面三个晚上的排错。

6.3 适合AI全流程构建的项目特征

经历了这个项目后，我对“什么项目适合用Claude Code全流程搭建”有了更清醒的判断。它不一定适合所有场景，但确实适合以下几个特征的项目：

单一服务、技术栈统一、数据模型不复杂的应用，AI几乎可以单枪匹马完成；而涉及复杂实时通信、海量数据分片、多团队协作的系统，AI目前只能承担辅助编码角色。

宠物生命周期管理App恰好落在这个理想区间里。它足够真实，能覆盖表单、文件上传、关系数据库、提醒、图表、权限这些常规功能；它又足够克制，不会把项目膨胀到需要分布式架构才能支撑。做完这个项目，我最大的体会是：AI编码工具把“从0到1”的成本压到了极低，但项目的上限依然取决于人的架构判断和工程素养。工具能帮你把脑子里的想法变成代码，前提是你得先想明白自己在做什么。

最后分享一个我实际用下来的小技巧：如果你打算做一个类似的记录类项目，不妨先不碰代码，拿一天时间把自己最想解决的五个真实痛点写下来，然后让Claude Code从数据模型开始拆。数据模型对了，后面所有页面都会越写越顺；数据模型错了，AI生成再多界面都只是在一堆沙子上盖楼。项目跑通之后再看，宠物生命周期管理这件事，也许真的可以成为我们陪伴宠物过程中，一份最踏实的数字化回忆。