用Claude Code从零搭建宠物生命周期管理App：AI全流程开发实战

最近用 Claude Code 从零搭了一个宠物生命周期管理 App，从项目初始化、数据表设计、后端接口到前端页面，几乎全程用自然语言驱动 AI 完成。整个项目做下来，我最深的感受不是"AI 能写代码"这件事本身，而是项目的推进方式彻底变了——以前是先写文档再写代码，现在是先和 AI 把思路聊清楚，然后让它把思路变成能跑的工程。

这篇文章会把完整过程还原出来：需求怎么拆、提示词怎么组织、每一步 AI 给出了什么输出、中间踩了哪些坑、最后怎么收尾。适合两类人看：一类是想试试 Claude Code 但不知道从哪下手的开发者，另一类是已经把 AI 当作日常编码工具、但总觉得产出不可控、想建立一套可靠工作流的朋友。我会把能直接抄作业的部分都写在明面上。

1. 项目定调：宠物生命周期管理 App 到底要做什么

1.1 需求源头与核心痛点

先说说这个项目是怎么来的。一个养了两只猫的朋友跟我抱怨，说疫苗本子上记的日期早就乱套了，驱虫药每次都是想起来了才买，体重秤上的数字变化他也没概念。他说"要是有一个东西能告诉我，我家猫现在处在哪个阶段、该打什么针、该不该控制食量就好了"。

这就是"宠物生命周期管理"的核心：围绕一只宠物的完整时间线，把档案、疫苗、驱虫、喂养、体重、健康记录这些零散信息串起来，在关键节点主动提醒主人。它跟普通的"宠物日记本"类 App 最大的区别是，它有一套基于时间的规则引擎——什么时候该接种疫苗、什么时候该驱虫、体重增长速度是否异常、宠物从幼年期进入成年期的时间点，这些不是用户手动记录的，而是系统根据出生日期和既往记录自动推算出来的。

这也是我觉得适合拿来验证 AI 全流程开发的原因：业务规则清晰，但又有足够的逻辑复杂度；数据结构不复杂，但表与表之间有明确的关系；界面不需要炫技，但得有完整的交互流。

1.2 功能清单与优先级划分

面对一个项目，第一步不是让 AI 写代码，而是先把需求边界划出来。我当时的做法是列一张优先级表，明确 MVP 里有什么、砍掉什么：

之所以这么划，是因为 P0 里的功能全部可以闭环验证：用户建档案 → 记录一次疫苗 → 系统算出下次时间 → 首页提醒里出现对应条目。这就是一个完整的最小闭环，AI 围绕这个闭环干活，目标感会很强。P2 的东西一旦混进来，AI 就会在无关模块上浪费大量 token 和上下文窗口。

1.3 技术选型：为什么是 Web App 而不是原生 App

标题里虽然叫"App"，但我从一开始就没打算做原生 iOS/Android。原因很实际：Claude Code 跑在终端里，它最擅长的是读写文本文件、执行命令、跑测试，这套工作流对 Web 项目最友好。React + TypeScript + Vite 做前端，Node.js + Express 做后端，SQLite 做数据库，全链路都是文本文件，AI 可以无缝介入每一层。

还有一个关键考量：SQLite。它不需要单独启动数据库服务，就是一个文件，开发环境和部署环境几乎零差异。对于这种体量的项目，PostgreSQL 属于杀鸡用牛刀，还会引入环境配置的复杂度，AI 生成的连接配置稍有环境差异就跑不起来。SQLite 配合数据访问层的小封装，后面真要换库也有回旋余地。

2. 用 Claude Code 启动项目的完整流程

2.1 工作环境与启动方式

实际操作层面，Claude Code 是在项目目录下通过命令行启动的。进入一个空目录，确认配置文件里的 API 凭证就绪，然后执行启动命令，一个交互式的会话就起来了。它会读取当前目录的文件结构，我需要的下一步就是把我脑子里的需求描述给它。

这里有个容易被忽略的点：项目目录最好是一开始就是空的，或者只有 Git 初始化记录。让 AI 在一个干净的环境里从零创建工程，远比让它去理解一个已有项目的五花八门的结构要可靠。我的做法是先git init打底，然后启动 Claude Code 直接开聊。

2.2 第一轮对话：先要方案，不要代码

很多人的第一反应是直接说"帮我做个宠物 App"，这样得到的必然是一堆泛泛而谈的代码框架。我的经验是：第一轮对话只谈方案，不谈实现。我会把需求背景、功能边界、技术约束一次性丢给它，然后明确要求它输出一份结构化的开发计划。

当时的核心提示词大概是这样的：

我要做一个宠物生命周期管理 Web 应用。核心功能包括：宠物档案管理、疫苗/驱虫记录与到期提醒、喂养记录、体重记录与趋势展示、生命周期阶段自动计算。技术栈限定为前端 React + TypeScript + Vite，后端 Node.js + Express + TypeScript，数据库用 SQLite。 请先不要写任何代码。先帮我做三件事：1. 拆解数据模型，列出所有表和关键字段；2. 梳理 API 路由清单；3. 给出一个分阶段的开发顺序，从最小的可运行闭环开始。 请用 Markdown 输出，控制在 800 字以内，重点突出表设计、路由地址和阶段划分。

这份输出被我当作整个项目的"施工图"。AI 给出来的方案其实和你自己会想的差别不大，但它能在几秒钟内把所有表、字段、路由一次性铺开，省掉了大量手打草稿的时间。更重要的是，之后每一次让它写具体代码，我都能引用这份方案，"按照你上一个回答里的表结构去创建迁移文件"，上下文就串起来了。

2.3 脚手架搭建与目录结构落地

方案确认之后，我让它开始搭建工程骨架。这一步的关键词是"最小化"：package.json、tsconfig、vite 配置、express 入口、SQLite 连接模块，够跑起来就行，不要一次性引入一堆不知道用不用得上的依赖。

AI 生成的后端目录结构大概是这样的：

server/ ├── src/ │ ├── index.ts # Express 入口 │ ├── db.ts # SQLite 连接与初始化 │ ├── routes/ │ │ ├── pets.ts │ │ ├── vaccines.ts │ │ ├── feeds.ts │ │ └── weights.ts │ └── services/ │ ├── schedule.ts # 提醒规则计算 │ └── lifecycle.ts # 生命周期阶段计算 └── data/ # SQLite 数据库文件目录

前端部分让 AI 用 Vite 的模板初始化，然后加上 React Router 和必要的目录结构。这里有一个很实用的约束：我会明确告诉它"所有新增代码必须遵循 TypeScript 严格模式，禁止使用 any 类型"。这条约束看起来简单，实际上能避免掉 AI 在类型上偷懒导致的连环报错。

3. 核心功能实现：从数据模型到业务逻辑

3.1 数据模型设计：让 AI 把外键关系讲清楚

数据模型是整个项目的底座，这里不能含糊。我让 AI 把每个表的关键字段、类型、约束都列出来，特别强调要说明外键关系。

最终确定的表结构核心部分是：

CREATE TABLE pets ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, species TEXT NOT NULL CHECK (species IN ('dog', 'cat', 'other')), breed TEXT, birth_date TEXT NOT NULL, is_neutered INTEGER DEFAULT 0, avatar_url TEXT, created_at TEXT DEFAULT (datetime('now')) ); CREATE TABLE vaccines ( id INTEGER PRIMARY KEY AUTOINCREMENT, pet_id INTEGER NOT NULL REFERENCES pets(id) ON DELETE CASCADE, vaccine_name TEXT NOT NULL, administered_at TEXT NOT NULL, next_due_at TEXT, note TEXT ); CREATE TABLE feeds ( id INTEGER PRIMARY KEY AUTOINCREMENT, pet_id INTEGER NOT NULL REFERENCES pets(id) ON DELETE CASCADE, fed_at TEXT NOT NULL, food_type TEXT, amount_grams REAL, note TEXT ); CREATE TABLE weight_records ( id INTEGER PRIMARY KEY AUTOINCREMENT, pet_id INTEGER NOT NULL REFERENCES pets(id) ON DELETE CASCADE, recorded_at TEXT NOT NULL, weight_kg REAL NOT NULL );

这里有个值得展开的细节：疫苗表里的next_due_at字段，是冗余存储还是每次实时计算？我让 AI 权衡后选择了"写入时计算、存储冗余"的方案。原因是提醒查询要频繁按日期排序和筛选，如果每次都在查询时根据接种日期和疫苗周期去推算，逻辑会散落在各处，也难做索引。写入时算好下次时间，查询就退化成简单的日期比较。代价是数据更新时要重算，但在这种低频写入场景里完全可接受。

3.2 提醒规则引擎：疫苗到期怎么算才靠谱

这个模块是项目的核心，也是最能体现"业务逻辑必须自己心里有数"的地方。常见的疫苗和驱虫周期不一样：狂犬疫苗通常一年一次，犬瘟细小这类核心疫苗初免后也需要定期加强，而驱虫药有的一个月一次，有的三个月一次。

我不指望 AI 自己懂兽医知识，所以我把规则直接交给它：

请实现一个计算下次到期日的函数，输入参数为：疫苗/驱虫名称、上次接种日期、周期类型（monthly / quarterly / yearly）。返回值为下次到期日。另外实现一个 judgeDueStatus 函数，输入下次到期日，按以下规则返回状态：已过期（due date < today）、即将到期（due date - today <= 7 天）、正常。请导出这两个函数，并写成纯函数，便于单测。

强调"纯函数"是有原因的。Claude Code 这类工具写业务逻辑时，很容易顺手就把日期操作和数据库查询混在一起，结果就是函数没法单独测试、也没法复用到提醒列表的渲染上。把它们拆成纯函数后，逻辑和 IO 分离，后续让 AI 补测试用例就非常顺。

“即将到期”的提前量我定成了 7 天，这个值后来证明比较合理。太短了主人来不及准备，太长了提醒会失去紧迫感。如果你要做的是更细分的场景，可以把提前量做成每只宠物可配置的字段，但 MVP 阶段不宜过度设计。

3.3 生命周期阶段计算：年龄和阶段的联动

生命周期阶段的算法看起来简单，其实有几个边界情况要注意。我当时的规则是：猫和狗在 1 岁以内算幼年，1 到 7 岁算成年，7 岁以上算老年。但大型犬的成年期和老年期节点通常会早于小型犬，这属于领域知识，AI 不知道，需要我来定。

处理方式是让 AI 把"生理年龄"做成一个独立服务，内置一张物种阈值表。我不让它写死死代码，而是用配置对象表达：

const STAGE_THRESHOLDS = { dog: { large: { juvenileMonths: 18, seniorYears: 5 }, small: { juvenileMonths: 12, seniorYears: 7 }, }, cat: { juvenileMonths: 12, seniorYears: 7, }, };

满足isLargeBreed的条件时，就按大型犬的阈值计算；否则走默认值。这种配置驱动的写法，后续要调整阈值，只需要改配置，不需要动逻辑代码。AI 对这种写法天然友好，因为它的改动成本变低了，出错面也更小。

3.4 API 路由与错误处理

API 层我让 AI 按照 REST 风格实现，路由清单在方案阶段就已经确定了，所以实现阶段就是按清单逐条落地。这里要特别控制的是错误处理的风格统一性。如果放任 AI 自由发挥，每个接口的报错结构可能都不一样，前端处理起来很痛苦。

我提出了一个硬性约束：所有接口统一返回{ code, data, message }结构，成功时code=0，业务异常时code为非 0 的业务码，参数错误统一返回 400。然后让它先写一个全局错误处理中间件，再写业务路由。这样前端封装请求层时只需要处理一种响应结构，省掉大量分支判断。

4. 前端页面与交互的 AI 实现

4.1 页面骨架：单页应用 + 底部 Tab 导航

前端页面结构我定得很简单：一个 App 外壳 + 三个 Tab，首页是提醒和概览，宠物页是列表和详情，记录页是汇总和新增入口。这种结构对移动端形态的 Web App 很自然，也方便 Claude Code 按模块生成代码。

让 AI 实现页面骨架时，我给的描述是"移动端优先、最大宽度 480px 居中、底部固定导航"。这个约束很重要，因为 AI 默认生成的页面往往是一个横向铺满的桌面布局，等做完再改适配，返工成本很高。把布局约束写在最前面，一次到位。

4.2 组件生成：从界面描述到可用代码

Claude Code 生成前端组件的能力很强，前提是你得把界面描述得足够具体。我当时的做法是"界面描述 + 数据示例 + 交互要求"三段式。比如宠物详情的疫苗列表，我会这样描述：

请实现疫苗记录列表组件。它接收一个疫苗记录数组，每条记录包含疫苗名称、接种日期、下次到期日。列表项左侧显示疫苗名称，右侧显示到期状态标签：已过期显示红色"已过期"，7 天内到期显示橙色"即将到期"，否则显示绿色"正常"。下方提供一个"添加记录"按钮，点击后弹出表单。请给出 React + TypeScript 实现，样式用内联简单的 class 即可。

这里的关键是"给出数据示例"。AI 对字段的理解取决于你的描述，如果只是说"疫苗记录数组"，它可能猜字段名。把一条真实的示例数据给它，组件代码里的字段引用就不会跑偏。我做这个小项目时，凡是涉及表格、列表、表单的组件，都坚持先给一条mock数据再让其实现，字段一致性错误几乎绝迹。

4.3 状态管理与数据请求封装

一个小型项目没有必要上重型状态管理库，React 自带的 hooks 足够。我让 AI 封装了一个useApihook，统一处理请求、加载态、错误态和刷新：

function useApi<T>(endpoint: string, options?: RequestInit) { const [data, setData] = useState<T | null>(null); const [loading, setLoading] = useState(true); const [error, setError] = useState<ApiError | null>(null); // 内部统一走 fetch 封装，解析 { code, data, message } 结构 // 暴露 refresh 方法，供提交后重新拉取数据 }

有了这个 hook，所有页面组件的逻辑都会收敛成"调用 hook + 渲染 data + 处理 loading/error"。这套模式一旦定下来，后续让 AI 新增页面时就等于给了它一个现成的模板，生成代码的稳定性和一致性会非常明显地提升。我在中期发现问题最多的就是请求层重复代码，收敛到一个 hook 之后，问题直接消失。

5. 联调、测试与细节打磨

5.1 前后端联调中的典型断裂点

前后端分离项目第一次联调，常见的坑就那么几个：CORS 没配、字段名前后端不一致、时间字符串格式解析失败。Claude Code 生成的代码也逃不过这些，所以我的策略是提前堵漏。

第一步，让后端在入口处显式配置 CORS，允许开发服务器地址跨域访问。第二步，统一时间格式约定：接口传输用 ISO 8601 字符串，前端展示时再格式化成"2025-06-01"这种人类可读格式。这一步不提前约定的话，前端拿到的可能是2025-06-01T08:00:00.000Z，也可能带时区偏差，展示时日期直接差一天。

5.2 让 AI 补测试用例：从最核心的函数开始

写完功能之后，我让 AI 给几个纯函数补了单测，优先覆盖的是疫苗到期状态判断和生命周期阶段计算。这两个函数是业务正确性的核心，出错的代价最高。

单测的价值在这个项目里体现得很直接：我让 AI 把"已过期""即将到期（7 天内）""正常"三条路径的用例都列出来，再把边界情况如"恰好 7 天"和"恰好 0 天"也覆盖进去。AI 生成的测试用例加上去之后，我后续让 AI 修改提醒提前量时，跑一遍测试就能确认改动没破坏边界行为。没有这层测试，改一个阈值就可能静默引入 bug。

5.3 体验细节：空状态、加载态、错误态一个都不能少

AI 生成前端界面时有个通病：默认只做"有数据"的那条路径。你把列表接口返回空数组，页面就白屏；请求失败，页面也没有任何提示。这个坑我在第一个版本里踩得非常痛。

解决办法是在每一次让 AI 实现页面组件时，把三个状态显式写进需求里。我的固定句式是："请确保组件包含 loading 骨架屏、空状态提示文案、错误状态和重试按钮三个分支。"这句话加进去之后，AI 生成的组件质量明显上了一个台阶。如果你在写提示词时漏了这一点，最后你会发现所有页面都漂亮，但一遇到空数据库就全裸奔。

6. 全流程实践里的经验与避坑

6.1 提示词组织的三层结构

整个项目做下来，我总结出的提示词模板是固定的三层：上下文、任务、约束。上下文告诉 AI 它需要知道什么，任务告诉它要做什么，约束告诉它怎么做以及绝对不能做什么。

【上下文】 我们正在开发宠物生命周期管理 App，技术栈是 React + Express + SQLite。项目遵循已有约定：date 回复用 `{ code, data, message }` 结构；时间字段统一用 ISO 8601 字符串。 【任务】 请实现宠物列表页，展示每只宠物的名字、物种、年龄和最近一次疫苗到期状态。 【约束】 1. 数据从 GET /api/pets 接口获取，请调用已有 useApi hook； 2. 不要引入新的 UI 组件库； 3. 需要包含加载、空状态、错误重试三个分支。

这套三层结构最容易被忽视的是"约束"里的负面清单。"不要引入新的 UI 组件库"这句话帮我避免了很多次 AI 自作主张装依赖的情况。Claude Code 的上下文是有限的，尽量每句话都有信息量，别让它猜。

6.2 上下文管理的核心：项目记忆文件

Claude Code 支持项目级的记忆文件，通常放在项目根目录，里面记录项目的关键约定，每次新会话它都会自动读取。这个文件值得花时间维护，我在里面写的是：技术栈、目录结构、API 响应规范、时间格式、代码规范、以及"禁止事项"清单。

实际使用的体会是：有了它之后，每次开新会话处理功能开发时，不需要重新解释一遍项目背景，AI 的任务完成度直接从"可能跑偏"变成"基本靠谱"。尤其是隔几天再继续开发时，这个文件就是项目的"记忆锚点"，价值非常大。

6.3 失控与返工的止损策略

Claude Code 干活不是每次都顺着你的想法走。我在项目中期遇到过两次它连续修改多个文件后把功能改坏的情况，一次是它为了"优化"某个组件结构，把状态管理的逻辑抽到一个新文件里，结果其他页面引用找不到导出；另一次是它自动升级了依赖版本，导致启动时报错。

应对策略有两个。第一个是频繁提交 Git。我给自己定了一条规则：每个功能模块完成后，立刻提交一次，并且提交信息写清楚这个模块完成了什么。这样 AI 一旦把代码改坏，git checkout可以直接回到可用节点。第二个是判断什么时候该止损。如果同一段逻辑让 AI 改了三轮还没对，大概率不是它能力问题，而是我的上下文描述有偏差，或者需求本身在演进，这时候我会停掉当前会话、重新整理上下文，而不是继续在已经发散的会话里纠缠。

7. 常见问题与排查速查

做了一个完整的项目，遇到的问题肯定不少。我把高频问题整理成了一张速查表：

这张表里的每一条都是实际发生过的，排查过程其实没有特别玄的地方，核心就是"让 AI 把完整报错信息贴出来，再定位到最小复现范围"。我反复强调一点：给 AI 的错误信息一定要完整，只丢一句"它报错了"是得不到有效修复的。

最后再分享一个个人体会。用 Claude Code 从零搭完这个项目之后，我最大的变化是不再把 AI 当成一个"自动补全机器人"，而是当成一个可以随时对话的结对开发者。但这个定位有个前提——你才是那个真正懂业务、懂边界、懂取舍的人。AI 能帮你把 SQL 建好、把组件写完、把测试补上，但它不会替你判断"提醒提前 7 天够不够""大型犬老年期该从 5 岁算还是 6 岁算"。这些决策得你自己做，然后把结论准确地告诉它。

如果你正准备拿 Claude Code 上手一个新项目，我建议你从今天这条流程里至少带走三件事：第一，先让 AI 出方案再写代码，别急着让它动手；第二，把项目约定写进记忆文件，让每次会话都有共同语境；第三，每个模块完成后立刻提交 Git，给自己留好退路。做到这三条，AI 全流程开发这件事，就真的从"炫技"变成了"生产力"。