说实话我一开始不太相信AI能独立从零搭出一个完整的新项目。Claude Code这种AI编程工具我平时基本只拿它改个小函数、补几个测试用例直到朋友问我能不能帮忙做一个记录家里宠物疫苗、体重和成长阶段的小工具——我心一横决定不仅要做还要用最“激进”的方式从项目初始化到需求拆解、数据建模、功能开发、测试部署全程让Claude Code参与。于是就有了这个宠物生命周期管理App。整体做下来我的结论有点反转它确实能扛一大半编码工作但在关键业务逻辑上你稍微松手它就可能给你埋雷。这篇文章我不打算写普适性的AI使用指南而是完整还原这个项目从0到1的推进过程包括每一步的选择、踩过的坑以及哪些环节适合放手让AI做、哪些必须自己把关。尤其适合想尝试用AI做完整项目但还不太敢动手的开发者。1. 先想清楚再动手宠物生命周期管理App到底要管什么1.1 这个项目的第一版需求是怎么来的需求最初其实就一句话“帮家里两只猫一只狗记录打疫苗、驱虫、体重变化和看病历史。”如果用传统方式我会先画原型图、写PRD、再排期。但这次我想看看Claude Code在需求阶段能帮上多少忙所以反向操作先自己用通俗语言描述场景再让它抛出一份“宠物生命周期管理App功能建议清单”。我给的原始描述大概是这样“宠物的生命周期分幼年、成年、老年不同阶段需要不同的疫苗和检查频率。用户要能添加多只宠物记录每只宠物的基本信息、体重变化、疫苗记录、驱虫记录、就诊记录系统要能根据生日算出当前处于哪个阶段并且提前提醒该打什么疫苗。”Claude Code很快列出了一张功能表宠物档案管理、生命周期阶段划分、疫苗和驱虫提醒、健康记录台账、体重趋势图、宠物知识库、多宠物家庭支持、家庭成员共享。说实话这份清单比我脑子里想的完整得多它甚至把“不同物种的生命周期折算”和“慢性病用药提醒”这种细节都列了出来这正是当初让我决定把项目做实的原因它一开始就把“生命周期”当作核心领域来理解而不是简单做个记事本。1.2 “生命周期”不等于“生老病死时间轴”这个环节是需求阶段最有价值的部分。我发现Claude Code对“生命周期管理”的理解一开始偏向时间轴想做一个类似“病历时间线”的东西把所有事件串起来。这当然也对但真正的业务痛点不是记录而是“主动管理”。宠物主人真正想要的是你知道我家猫现在处于哪个阶段吗它这个阶段该做什么下次疫苗什么时候打体重是不是超标了这些信息需要系统主动算出来、主动提醒而不是让用户自己翻记录。我把这个想法反馈给它后它把需求清单调整成了三个核心闭环档案→阶段判定→提醒健康记录→统计→异常提示。整个应用的骨架一下子清晰了。这段经历也让我确认了一件事AI可以帮你把需求从“模糊”变成“完整清单”但方向的确认权必须在你手里。“生命周期管理”这个词的语义人和AI的理解是有偏差的你得把它掰正。如果你自己心里没有一张地图AI只会帮你更快到达一个错误的地方。1.3 砍功能MVP只留四件事需求清单出来之后最大的工作量其实是砍掉三分之二。Claude Code和大多数初次做产品的人一样喜欢把功能加到最大化。我和它讨论后把首版范围圈定为四个核心宠物档案、生命周期阶段自动判定、疫苗/驱虫提醒、健康记录和体重趋势。共享功能、知识库、慢性病用药提醒都挪到第二期。砍功能这件事AI本身也能给出建议——我让它从“最小可用产品”角度重新排序它会告诉你哪些功能互相依赖、哪些可以先不做。但最终拍板还是要靠人。MVP阶段的技术复杂度也因此降了不少不需要账号体系和多用户共享就绕开了权限设计这一大块复杂度。这个决策在后面推进速度上起到了决定性作用因为越少的功能边界意味着AI越不容易在模块之间产生“幻觉耦合”。2. 从对话到方案技术选型与工程目录怎么定2.1 技术选型让AI给对比人来做决定技术选型是这次实践里我最看重的一环。以前遇到新项目我通常会自己列几个技术方案对比这次我让Claude Code基于“小型Web应用、快速开发、方便部署、适合AI代码生成”四个条件给出一份推荐。它的第一推荐是前端React Vite Tailwind后端FastAPI数据库SQLite开发/PostgreSQL生产ORM用SQLAlchemy提醒服务用APScheduler部署用Docker。理由也说得通这套技术栈生态成熟、代码生成语料丰富、依赖少、本地跑起来快。我也和它讨论过要不要上移动端结论是首版先用Web响应式页面——宠物主人大概率在手机上看但Web端可以用PWA方式近似实现省掉双端开发和审核成本。这里我做了一个小表格对比了几种方案方便大家复现时参考方案优点缺点结论React Web PWA开发快、AI生成成熟、实现提醒方便离线能力弱一些首版选择Flutter单端真原生体验开发周期长、AI生成质量参差二期考虑纯后端API App壳复用Web代码需要额外的打包和签名流程暂不考虑让AI给技术建议有个技巧不要直接问“选什么框架好”而是把它扔到一个具体约束里来问比如“我有一个单人开发的小项目希望三周内上线后续要加移动端请从开发效率和维护成本给出推荐”。约束越具体它给出的答案越靠谱。因为它本质上是一个概率模型你给它的前提越多它生成的内容就越收敛而不是给你一堆泛泛的框架列表。2.2 从0初始化项目一次生成目录技术栈定了之后我做了两件事第一在本地建好空目录把项目描述整理成一段话第二让Claude Code直接生成整个初始工程。给它的输入大概是这样的“初始化一个宠物生命周期管理App项目。后端用FastAPISQLAlchemySQLite前端用ReactViteTailwind包含如下接口宠物档案CRUD、获取宠物当前生命周期阶段、疫苗记录增删改查、提醒列表。请生成完整的目录结构和基础代码。”几秒钟之后它输出了类似下面的目录pet-life-app/ ├── frontend/ │ ├── src/ │ │ ├── components/ │ │ ├── pages/ │ │ ├── api/ │ │ └── App.jsx │ └── package.json ├── backend/ │ ├── app/ │ │ ├── models/ │ │ ├── schemas/ │ │ ├── routers/ │ │ ├── services/ │ │ └── main.py │ ├── tests/ │ ├── requirements.txt │ └── Dockerfile └── README.md这一步的体验是非常流畅的但它有一个陷阱它生成的是“看起来正确”的项目骨架不保证能直接跑起来。比如它生成的requirements.txt里少了几个关键版本号前端Vite配置也有过时写法。我自己的策略是让它生成之后立刻在本地跑一遍前后端把能报的错全报一遍再把这些错误原样贴回给Claude Code。这样迭代两三轮项目基本就能从“纸面工程”变成“可运行工程”。这一阶段不用操心代码细节核心目标是让整个架子转起来。3. 数据先行宠物表、阶段计算规则和一个时区坑3.1 四张核心表的建模过程业务上“宠物档案→健康记录→提醒”这三个核心闭环落到数据库里就是四张表宠物表、疫苗记录表、健康记录表、提醒表。我让Claude Code先建模型它直接生成了SQLAlchemy模型。宠物表的要点是除了name、species、breed、birthday、gender这些基本信息还应该有weight_current方便在列表上直接显示最新体重中性化状态neutered我干脆合并成布尔字段而picture_url放的是头像地址。这里我要特别强调一个我从实际开发里总结的经验像“当前体重”这种字段一开始不要单独建一张表去维护直接在宠物表上冗余一个字段配合健康记录表里的历史体重曲线两种需求都能覆盖。如果一开始就纠结“范式完美”很容易被AI带进过度设计的坑里。AI天然会倾向于“完整”的表结构但MVP要的是“够用”两者经常冲突。健康记录表的核心字段是pet_id、record_typevaccine/体重/就诊/用药、record_at、content、value。为什么要用record_type而不是建一堆子表因为对于MVP来说它们的查询模式高度一致——都是“按宠物和时间倒序查列表”拆表只会让代码变复杂收益却很小。提醒表的设计则和定时任务强绑定id、pet_id、remind_at、remind_type、title、statuspending/done/cancelled、last_sent_at。提醒不是“改一下数据就自动生成”的而是由一个后台任务扫描某个“下次应做时间”字段比对当前时间后插入提醒记录这个逻辑在第4章会展开。3.2 生命周期阶段的计算并没有那么简单生命周期阶段是这个App的灵魂。Claude Code第一版给的计算逻辑是简单按年龄月份划分def get_life_stage(species: str, age_months: int) - str: if species dog: if age_months 12: return puppy if age_months 48: return adult return senior # cat handled similarly表面上看没问题但实际一推敲就发现三个漏洞。猫和狗的阶段阈值完全可以用同一套吗不能。狗的体型差异很大大型犬6岁就可能进入老年期而小型犬到10岁还活蹦乱跳猫相对均匀但纯种猫和混血猫的平均寿命差距也存在。按“出生到现在的月份数”计算完全忽略了不同阶段的相对长度。比如狗的前12个月被笼统当作puppy但实际上3个月大的幼犬和11个月大的幼犬护理需求完全不同。我和Claude Code讨论后把判定规则改成了两层结构第一层按物种和体型先确定“成熟速度档位”第二层把年龄按月数换算成“相对生命阶段比例”。简化后的规则如下STAGE_THRESHOLDS { cat: {kitten: 12, adult: 72, senior: 144}, dog_small: {puppy: 12, adult: 72, senior: 132}, dog_large: {puppy: 12, adult: 60, senior: 108}, } def get_life_stage(species: str, breed_size: str, birthday, today) - str: age_months (today.year - birthday.year) * 12 (today.month - birthday.month) thresholds STAGE_THRESHOLDS[species if species cat else fdog_{breed_size}] if age_months 0: return unknown if age_months thresholds[kitten]: return puppy if species dog else kitten if age_months thresholds[adult]: return adult return senior这个版本依然有简化的成分没有细致到每个品种的体重修正但这已经够MVP用了。关键点是像“生命周期”这种领域概念AI不会自动知道你的业务目标是“根据阶段给养护建议”所以必须把业务语义喂给它。它的职责是快速把规则写成代码你负责给它规则。3.3 birth字段的语义日期和时间是两回事这个模块让我踩了一个印象深刻的次坑。最初Claude Code用生日字段直接通过“当前日期减生日”来计算年龄生成逻辑用的是标准库的date对象。这套逻辑本地开发跑得挺好但一旦部署到服务器时区如果没设置晚上8点以后出生日期当天年龄显示居然会差一天。原因是服务器用的是UTC时间而用户录入的是本地时间。修复方案不是自己改一行代码而是把这个现象告诉Claude Code后它会建议把birthday统一成“日期字符串”存储不参与时间转换同时在计算年龄时用本地时区的today()而不是date.today()。这条经验值得记下来AI默认用UTC时间来处理所有datetime相关逻辑你的业务时间如果不是UTC一定要在模型设计阶段就表明字段语义否则它生成的代码里就会埋着“跨天”的雷。后面第五章翻车现场我也会再提它的完整排查链路。4. 核心功能逐个实现档案、阶段卡片与疫苗提醒4.1 宠物档案CRUD先让列表页跑通宠物档案是整个应用的地基。实现方式是标准的CRUD后端FastAPI路由、SQLAlchemy模型、Pydantic校验前端一个列表页、一个表单页。这里分享一个协作技巧不要一次让AI生成“完整功能”而是按“接口→页面→联调”的顺序推进。我先让它只生成“宠物列表接口详情接口”前端页面先用假数据渲染等后端接口通了再把假数据换成真实API调用。这样做的好处是每一步出错时你能立刻定位是后端问题还是前端问题而不会出现那种“前后端代码看起来都对但页面就是白屏”的经典灾难。在实现过程中Claude Code给我补了一个我当时没注意的细节birthday字段的输入控件用的是日期选择器但后端校验里没有限制“生日不能晚于今天”。一只宠物如果录了未来的生日生命周期阶段计算会直接返回负数月份界面上一团糟。这个校验是它帮我加上的——这也是这类工具的价值它不是替你思考而是能帮你挡住你暂时没想到的边界。4.2 阶段卡片一处后端计算处处复用阶段卡片是宠物详情页最亮眼的部分。前端拿到后端返回的阶段判定后渲染一张卡片展示“幼年期/成年期/老年期”和一句对应阶段的养护建议比如“猫咪1-6岁是成年期注意控制体重建议每年体检一次”。这里我把阶段判定写成了后端services里的一个独立函数没有直接放在路由里。原因是这个函数会被很多地方调用宠物列表要显示、宠物详情要显示、提醒服务判断阶段变化时也要调用。独立成一个纯函数还有一个好处方便做单元测试后面第6章会讲到。Claude Code在生成这一步时非常顺手因为它已经在前面的模型和规则里给出了足够上下文所以生成出来的service几乎是直接可用的。4.3 疫苗提醒是怎么真正跑起来的提醒系统是这个项目最“重”的部分也是最有技术含量的。最初我们讨论过两种方案。方案A是每次用户打开App时扫描所有宠物把“逾期未做的疫苗”计算出来并展示。方案B是后台常驻定时任务按计划生成提醒记录存到提醒表里用户看到的是已生成的提醒列表。Claude Code推荐的是方案B理由是提醒数据一旦入库就可以支持“标记完成”“忽略”“统计提醒率”等后续功能。我也同意这点但它也带来了复杂度什么时候扫描扫描多久一次重复提醒怎么避免我们决定先按方案B实现。核心实现思路是宠物表里加一个vaccine_next_due_date字段下次疫苗应做日期一个定时任务每天早上8点扫描所有宠物如果vaccine_next_due_date today 7天就在提醒表插入一条pending状态的提醒记录用户完成疫苗后更新疫苗记录同时把vaccine_next_due_date推到下一次日期。这样可以做到提醒不重不漏。Claude Code用APScheduler实现了这个定时调度本地跑通后部署到服务器上由系统进程拉起。这个设计的缺点也很明显提醒的精度依赖定时任务的粒度每天一次如果用户当天录入疫苗记录希望“三天后提醒”这种短周期提醒可能第二天才扫描到。好在MVP阶段可以接受。如果后续要更精确可以改成录入时立即生成提醒记录定时任务只负责兜底扫描。5. 翻车现场AI生成代码最容易出问题的三件事5.1 案例一服务器时区让年龄差了一天这个问题在第三章提过这里完整还原一次排查链路。现象是某天晚上用户新增了一只生日当天的宠物详情页显示的生命周期阶段却是“成年期”明显不对。第一反应是看后端日志发现返回的年龄月份数是几百个月显然生日解析出了问题。我把日志中的birthday值从头到尾看一遍发现请求体里传的是ISO格式的UTC时间字符串比如“2024-07-15T00:00:00Z”后端SQLAlchemy把它转成了datetime对象与本地当前时间相减时没做时区归一化导致日期跨天。定位到这个原因后我没有自己写修复代码而是把这段日志和SQLAlchemy模型定义贴给Claude Code让它解释为什么会出现这个问题并提出修复方案。它给出的建议是birthday字段在模型层就用Date类型而不是DateTime前端传日期字符串后端解析后直接存Date对象所有计算基于本地时区。修复后这个bug在测试环境再没出现。这类时区问题对AI生成的代码来说特别隐蔽因为AI是根据你给的需求生成代码它默认你处于单一时区。项目里所有跟日期相关的字段都要在描述需求时额外标注“按用户本地时区计算”。5.2 案例二录错日期的提醒风暴第二个问题更隐蔽。测试阶段我手动录入了一条疫苗记录把“下次疫苗日期”误填成了一年前。当天晚上的定时任务扫描时发现“已逾期”于是生成了一条提醒第二天同一个任务又扫到“仍逾期”又生成一条三天后我打开提醒列表看到同一条提醒出现了七次而且越积越多。原始设计里定时任务没有做“去重”判断——它假设所有提醒生成一次就够了却忘了如果用户一直不处理每天扫描都会判定为“需要提醒”。修复思路是给提醒表加一个唯一约束在pet_id remind_type remind_at上建唯一索引插入时捕获冲突或者更简单在扫描时先查询提醒表里是否已经有同类型的pending记录如果有就跳过。我把这个思路告诉Claude Code后它在扫描函数里加了一个exists查询几十行代码就解决了。这个问题其实不完全是AI的错而是需求定义阶段漏掉了“防重复提醒”的业务规则。但这也正是AI编程的现实你给了它“扫描并生成提醒”这个指令它就老老实实扫描并生成不会主动问“如果已经生成过了怎么办”。所以写给AI的需求说明里一定要带上异常分支的描述哪怕只是简单一句“已有待处理提醒时不要重复创建”。5.3 案例三宠物列表页的N1查询第三件事发生在数据量上去之后。我为了演示给朋友看导入了大约150只宠物的测试数据结果宠物列表接口从最初的几十毫秒变成了快两秒。一开始我怀疑是网络问题后来看后端日志发现SQL查询数量惊人地多列表接口先查宠物然后对每只宠物又查一次健康记录和阶段计算总共执行了300多条SQL。这个问题在ORM里非常经典叫N1查询。Claude Code生成的代码里宠物列表查询没有做关联预加载也没有批量查询最新体重。我把这个问题描述给它它给出了修复方案用subquery一次性查出每只宠物的最新健康记录然后在内存中关联或者直接用SQLAlchemy的selectinload。最后我们采用了“子查询字典关联”的方式把300多条SQL降到了2条接口耗时降到120毫秒。这个案例让我意识到AI生成的代码在小数据量下看起来完美但性能问题往往要在规模和边界触发后才暴露。所以越是“AI生成”的代码越需要在真实数据量下做一轮压测这个习惯比用任何工具都重要。5.4 这些翻车背后有个共同规律把三个案例放一起看规律其实很清楚AI的强项是“把明确的需求翻译成代码”真正出问题的地方都在“业务语义的隐含分支”——时区语义、重复判定、数据量级。这些东西不是AI能自己推出来的它们藏在你的人类经验里。所以AI编程的正确姿势不是“输出一个prompt然后等结果”而是“把业务约束逐条说全然后审阅AI生成的每一处边界逻辑”。这个体会贯穿了整个项目。我甚至觉得给AI的需求描述如果写得好比给同事写的需求文档还要好——因为AI不会“自动脑补”你漏掉的部分它可能直接做成最坏的那种实现。6. 边界收尾测试、部署和上线前检查6.1 用测试把计算公式锁死阶段计算函数是整个App里最值得写测试的代码因为它的输入输出非常纯粹。我给Claude Code描述了一组边界测试场景出生当天、刚满1岁、刚满6岁、临界的最后一天、未来生日异常输入、不同物种比较。它给生成了一组Pytest用例def test_cat_age_at_12_months(): assert get_life_stage(cat, medium, date(2023, 5, 1), date(2024, 5, 1)) adult def test_future_birthday_returns_unknown(): assert get_life_stage(cat, medium, date(2025, 1, 1), date(2024, 5, 1)) unknown这些测试帮了大忙因为我后来在调阶段阈值时改过几次逻辑每次改动后跑一遍测试能立刻确认哪些场景被影响了。对于AI生成的业务逻辑我强烈建议把“输入输出边界”写进测试里这比review代码更能发现深层问题。因为代码review容易顺着AI的思路走但测试用例是你自己定义的业务预期能独立验证结果对不对。6.2 部署Docker化一气呵成部署阶段Claude Code又发挥了它的高光时刻。我让它根据项目结构生成Dockerfile和docker-compose.yml它自动把前端构建产物交给后端静态托管数据库用volume挂载定时任务用同容器内的进程管理拉起。第一次构建虽然有几个版本号问题但修起来很快。上线前检查清单是我自己整理的数据库备份机制环境变量里数据库路径、时区是否正确定时任务是否随服务启动前端构建资源是否有缓存策略本地时区与业务时区是否一致是否限制了生日输入的上限不允许超过当前日期50年。这些检查和AI本身关系不大但如果你做AI编程项目我建议把它做成模板。因为工具会替你省掉写代码的时间却不会替你做运维判断——那些坑往往更贵。吃过亏的人都知道一个定时任务没起来可能要空跑一周你才会发现。7. 把AI当同事而不是工具这个项目教会我的几件事7.1 AI最适合的是从“模糊”到“清晰”这一段这个项目做下来让我对AI编程能力边界有了更清晰的认知。Claude Code最擅长的是把我描述的模糊需求翻译成结构清晰的工程目录、接口、模型、页面组件。尤其在做需求梳理和技术选型对比时它像一个知识面很广的同事能快速给你一份可参考的清单。而在“从清晰到正确”这段路上比如精确到业务的隐含规则、异常分支、性能边界输出质量就变得不稳定需要你持续盯。用一句话概括就是AI拉高的是下限但上限依然由你的判断力决定。7.2 真正有价值的不是让AI写代码而是你会不会审代码我越来越觉得AI编程时代的开发者核心竞争力变成了“审阅者”而不是“编写者”。你需要有能力判断它生成的表结构是否有坑、计算逻辑是否漏了边界、提醒任务会不会重复执行。这也是为什么我建议新手不要一上来就依赖AI完成所有代码先手写几个小项目打好底子你才有能力看出AI在哪里偷懒。就拿这个项目来说如果不是我之前踩过N1的坑我根本不会意识到宠物列表接口的300多条SQL有问题如果不是清楚“日期不等于时间”也不会一眼看穿时区bug。AI不会替你积累这些经验它只会把你的经验放大——无论是好是坏。7.3 一个可以复制的工作流最后分享一个我这次验证过的协作流程按这个步骤走翻车率会低很多先把需求场景写成人话让AI生成完整功能清单人工砍掉非MVP功能砍完再让AI按“最小可用”重新列优先级初始化和数据建模阶段让AI直接产出但人必须审模型字段语义功能开发按照“接口→页面→联调”分步推进不要一次生成全部每完成一个功能模块立刻补上边界测试数据量接近真实规模后做一轮性能观察重点关注N1这类查询问题。我自己在实际跑完这个流程后最感慨的还是那句话工具永远只是放大器。如果你自己心里没有一张清晰的地图AI只会让你更快地走向错误的方向但反过来当你把需求边界想清楚时AI又能让一个人的产出速度快得接近一个五人小团队——这就是这个宠物生命周期管理App项目给我的最大收获。最后再分享一个小技巧遇到AI生成的代码有诡异bug不要凭感觉乱改把它执行的日志、输入数据、预期结果一起贴回去让它解释为什么会出现这个现象。很多时候它能自己定位问题并提出修复方案这和让同事帮你调试是同一个原理——信息给得越全定位越快。
