做过个人项目的人大概都有同感最烦人的不是写不出代码而是从零起步那一刻——建目录、搭脚手架、设计表结构、写接口、画页面、调样式一连串琐碎活儿还没碰到核心功能热情先耗掉一半。加上家里两只猫的疫苗本早就找不到了去年什么时候驱的虫、下个月该打哪针全靠手机备忘录里的零散记录硬猜。我一直想做个顺手的小工具把这事管起来但一想到全栈那摊子事就一直拖着。后来我把整个流程都交给Claude Code跑了一遍发现体验和以前完全不一样。它不是一个只会吐代码片段的聊天框而是一个能直接读写我项目文件、执行命令、跑测试、把整个工程从零撑起来的编程代理。这篇文章就记录我用它从空目录开始完整搭建一个宠物生命周期管理App我叫它PetLife的全过程从需求梳理、技术选型、数据库设计到核心功能开发、界面打磨、测试部署每个环节怎么跟AI配合、哪些地方AI会翻车、我做了哪些人工把关都会讲到。如果你也想用类似的AI编程工具做独立项目这篇应该能帮你少踩不少坑。1. 为什么是Claude Code一个能直接改代码的终端“编程搭子”1.1 和普通AI助手的核心区别先说结论Claude Code最大的价值不是“对话”而是“执行”。普通AI助手是你在聊天窗口里复制粘贴代码它给你一段代码你再手动贴回文件里来回切换成本很高。Claude Code不一样它直接住在你的终端里跟你的项目共享同一个文件系统。我给它的指令可以是“帮我在models目录下建一个petModel.js字段包括名字、品种、生日、绝育状态同时把CRUD接口写出来”它会真的动手去创建目录、写文件、把接口代码塞进去。我只需要在后面审查结果不满意就直接说“这个字段命名用snake_case统一改掉”它也会自己批量替换。这样的工作方式本质上是把一个“能执行任务的实习生”配给了你。实测下来我最深的感受是它尤其适合从零搭建新项目。空目录意味着没有历史包袱AI不需要理解一堆遗留代码它生成的工程结构可以非常干净。网上很多人反馈AI写代码“坑”大多数是在已有大型代码库里让AI改东西上下文太乱AI容易改一处崩三处。而新项目是AI最舒服的战场。1.2 环境准备和启动流程启用的流程很简单前提是机器上装好Node.js和Git。我在终端执行全局安装命令装好后进入想开发的项目目录敲一个claude命令就行。npm install -g anthropic-ai/claude-code cd petlife claude首次启动它会做一次登录授权之后就会进入一个交互式会话界面。这个会话跟聊天软件不一样你可以看到它每一步在干什么——读取了哪些文件、执行了什么命令、输出是什么。如果它卡住了我可以在对话框里直接让它“换个思路试试”。我建议开始的目录保持干净到极致连README都不用建所有内容都让AI生成。这样后面跟踪每一处代码变更时思路很清晰哪些是AI写的、哪些是我改的一眼就能看出来。2. 把需求讲给AI之前先把宠物生命周期App的MVP边界划清楚2.1 先让AI当一次产品经理很多人在使用AI编程时最容易犯的错是拿着一句话需求就让AI开写。比如你告诉它“做一个宠物管理App”它能给你生成一个包含电商、社交、AI问诊的庞然大物。问题不在AI而在需求本身不够清晰。我第一步没有让Claude Code写任何代码而是让它直接切换到“产品经理”角色通过连续问答帮我把需求理清楚。我给出的第一句是你现在是产品经理我要做一个宠物生命周期管理App核心用户是养猫养狗的人。请先问我10个最关键的澄清问题再输出一份MVP功能清单。它问的问题确实问到点子上了是单用户还是多用户数据要不要云同步提醒方式是站内消息还是推送需不需要图片上传我把回答逐一定下来第一版单用户本地优先不需要登录系统提醒用站内通知即可头像暂时用emoji替代不给图片上传。最终它输出的功能清单很干净我在此基础上又压缩了一轮定下了五个核心模块模块功能描述优先级宠物档案新建、编辑、删除宠物记录品种、生日、绝育状态、头像P0疫苗记录记录接种日期计算下次接种时间支持周期性提醒P0驱虫管理按体内/体外区分按周期生成下次驱虫日期P0体重记录记录体重变化直观展示成长曲线P1健康日志补充备注类信息如生病、换粮、就诊记录P1需求越具体后面AI写代码的目标就越明确。这一步省下来的时间比写代码本身还多。2.2 技术选型全栈方案和数据库取舍功能定下来之后第二个问题是技术选型。我对技术栈有自己的倾向但我还是让Claude Code给出了一套方案和理由然后逐条跟我确认。基于单用户、本地优先、后续可能部署到NAS或小型服务器的场景推荐一套全栈技术方案要求上手简单、依赖少、数据库文件可随时备份。它给的方案是前端React Vite后端Node.js Express数据库SQLite。理由很实在这三样都是各自领域最主流的选择生态成熟、社区案例多SQLite是单文件数据库备份就是复制一个文件对本地优先的应用来说比MySQL、PostgreSQL轻太多了。我认同这个方案没有任何犹豫。React Router管理前端页面后端用更现代的Hono替代Express也可以但考虑到Claude Code训练语料里Express的样本量大得多生成代码的稳定性更高。当时这个选择后来被证明是明智的——它写Express接口几乎不太需要我返工。2.3 确定MVP边界哪些功能第一版坚决不做AI默认会往产品里塞各种“锦上添花”的功能。第一轮它生成的清单里甚至有“AI宠物问诊”“社区分享”“多宠对比排名”。这些功能不是没价值但明显和“先把生命周期管理做好”这个核心定位冲突。我要求把第一版功能收敛到严格的最小集合制定了明确的“不做什么”清单不做账号系统本应用只服务本地单用户不做云同步部署时用Docker卷挂载数据库文件即可不做AI问答功能避免无限扩大依赖不做图片存储头像用内置emoji加底色代替不做日历视图第一版先保列表和提醒这个约束听起来很反直觉但对用AI开发至关重要。AI工程师至少现在的版本在功能膨胀面前几乎不会主动刹车它会很兴奋地给你堆功能。所有边界约束必须由作为负责人的人来定这是一条铁律。3. 从空目录开始初始化工程骨架与数据库表结构设计3.1 第一条指令让Claude Code从空目录开始动手需求定了接下来是动工。我当时的项目目录是彻底空的我给了Claude Code一条总指令让它完成初始化在空目录中初始化一个全栈项目 petlife - 前端React Vite React Router - 后端Node.js Express - 数据库SQLite使用 better-sqlite3 - 根目录下建立 client 和 server 两个子目录 - 先不要写具体业务代码只搭好工程结构、安装依赖、让前后端能分别启动它收到之后没有立刻开写先让我确认几个配置细节包管理器用npm还是pnpm、前后端开发端口怎么区分、需不需要一键启动脚本。确认完之后它就开工了。我目睹它创建了目录结构、初始化package.json、安装依赖并逐条执行命令。整个过程跑了大概十多分钟中间有一次npm安装失败它自动识别为网络问题重试了一次就过了。完成后项目结构长这样petlife/ ├── client/ # React 前端 │ ├── src/ │ │ ├── api/ # 封装后端请求 │ │ ├── components/ # 通用组件 │ │ ├── pages/ # 页面组件 │ │ └── App.jsx │ ├── package.json │ └── vite.config.js ├── server/ │ ├── src/ │ │ ├── routes/ # 接口路由 │ │ ├── db/ # 数据库连接与初始化 │ │ └── index.js │ ├── package.json │ └── .env ├── docker-compose.yml # 后续部署用 └── package.json # 根目录一键脚本我验证了一下前后端服务都能正常起来前端开发服务器和Express接口服务都返回了预期响应。这一步顺利得有些意外但我知道真正的挑战在后面——业务逻辑和数据处理。3.2 数据结构设计单表事件 vs 分表存储让AI给我讲道理表结构设计是这个项目里最不能全权交给AI的部分因为数据库结构一旦定错了后面所有代码都要跟着返工。我先让Claude Code基于需求清单独立设计一套数据库表结构并且要求它必须为每个设计决策说明理由。它第一版设计比较常规pets表、vaccines表、dewormings表、weight_records表每类健康记录单独一张表。看起来没毛病但我追问了一个问题“疫苗和驱虫本质上都是周期性的健康事件逻辑几乎一致有必要拆成两张表吗”它思考后主动提了重构方案将两者合并成一张health_events表通过event_type字段区分是疫苗还是驱虫然后通过cycle_days字段控制提醒周期。字段类型说明idINTEGER主键自增pet_idINTEGER关联宠物IDevent_typeTEXTvaccine / deworming / checkupevent_nameTEXT如“猫三联加强针”“体内驱虫”happened_atTEXT实际发生日期next_due_atTEXT下次提醒日期cycle_daysINTEGER周期天数无周期则为nullnotesTEXT备注备注信息这个设计一举两得一方面疫苗和驱虫的增删改查代码可以共用一套开发量直接减半另一方面提醒逻辑只需要统一查next_due_at字段即可定期扫描。权衡之下单表事件模型比双表方案干净得多。最终的表结构一共四张表pets、health_events、weight_records、health_notes。设计定稿后我让AI把SQLite的建表语句和种子测试数据一并生成初始化数据是两只虚拟猫咪让后面开发时始终有真实数据可以调试。这一步很重要空数据调试界面永远发现不了问题。3.3 建立CLAUDE.md把项目规范固定下来工程搭到这一步我意识到一个关键问题Claude Code的上下文窗口会逐渐缩小每次会话里聊偏了之后早期定下的技术选型和命名规范很容易被“遗忘”。如果不做点什么过不了多久它就可能给接口起一个风格完全不同的名字或者在前端卡出一个不一致的命名风格。解决办法是让它在项目根目录创建一个CLAUDE.md文件这个文件相当于给Claude Code的项目备忘录每次新的会话启动时它都会自动读取。我在里面写清楚了几个关键约定后端API统一前缀/api返回格式统一为{ code, data, message }前端请求封装统一放client/src/api目录每个资源一个文件数据库表名用复数snake_case字段用snake_case前端变量用camelCase时间统一用YYYY-MM-DD字符串存储不用时间戳文件中还记录了当前进度和已完成的模块。这样每次新开一个会话我不用重复交代项目背景和约定Claude Code自动就明白了。这是后面多轮开发不让项目跑偏的关键。如果你准备用类似的AI工具做完整项目强烈建议从一开始就建一个类似的“约定文件”宁可多花十分钟也要避免后面反复修正的麻烦。4. 核心功能逐个击破档案管理、疫苗提醒、成长曲线的AI实现过程4.1 宠物档案的CRUD后端优先再补前端所有的管理类应用入口一定是“档案”。我让Claude Code优先写宠物档案这个模块并且明确要求它“先完成后端接口再写前端页面”这样一旦后续有问题排查链路很清晰后端有问题前端一定正常不了前端有问题也只在前端范围内找。我的指令现在实现宠物档案模块。后端需要支持查询宠物列表、查询单只宠物、新增宠物、编辑宠物、删除宠物。字段包括名字、品种、物种猫/狗、性别、生日、绝育状态、头像emoji、备注。前端做对应的列表页和编辑页。验收标准页面能完成一次完整的“新建-查看-编辑-删除”流程。它非常老实地按顺序执行后端接口一口气写了五个前端页面也跟上了。我用种子数据验证了一遍列表能展示、编辑能保存、删除会二次确认整个流程畅通。我特别满意的一点是它把头像处理成了一个有趣的折衷方案前端用一个emoji选择器存到数据库里是字符展示时放进一个彩色圆形背景里。没有文件上传、没有静态资源目录却实现了类似头像的效果。这种在约束条件下的巧妙设计比按部就班实现图片上传更符合我们MVP的定位。4.2 疫苗与驱虫提醒最容易翻车的日期计算逻辑如果说哪个模块最容易让AI翻车一定是日期计算。疫苗和驱虫的核心逻辑很简单每次记录一条健康事件写上实际执行日期和周期天数系统计算出next_due_at。但AI在实现日期计算时有一个常见倾向就是喜欢用“当前时间 周期”来计算下次日期这在逻辑上是严重错误的。举个例子猫三联加强针的执行日期是2025年3月1日周期是365天那么下次接种应该是2026年3月1日。如果程序用“今天 365天”计算那么你明天打开应用下次接种日期就变成了2026年3月2日。这个bug在测试时很难发现因为隔天打开的话误差只有一天不敏感的人根本注意不到。我在指令里明确写下了计算规则下次提醒日期的计算逻辑必须基于happened_at加上cycle_days绝不允许基于Date.now()计算。Claude Code这次没踩坑但我的经验是对于这种逻辑必须把规则主动告诉它而不是默认它一定正确。为了让日期的加减计算本身更可靠我让它引入dayjs库来处理所有日期运算——JavaScript原生的Date对象在处理跨月、跨年时容易翻车第三方库会省心很多。提醒列表的实现也很有意思。我让它按“状态”把事件分为三类已过期next_due_at小于今天、即将到期30天内、正常。后端用一条SQL语句搞定分组查询前端用三个Tab来展示非常清晰。这个设计成为整个应用的视觉重心打开首页第一眼就知道哪只猫该打针了。4.3 成长曲线与体重记录选对图表库省一半力气体重记录本质上是一组“日期—数值”的序列数据最适合用折线图展示。我让Claude Code在图表库上做推荐它在Chart.js和Recharts之间推荐了后者理由是Recharts采用声明式组件设计跟React的写法更一致数据格式适配也最容易。后来的开发体验证明这个选择是正确的传一个数组进去就自动渲染出坐标轴和线条。实现过程出乎意料地快。只要给它说“在宠物详情页做一个折线图展示体重记录x轴日期y轴体重空数据时提示用户去添加记录”它就完整实现了组件。我额外让它加了趋势线逻辑最近一次体重相对上一次是上升、下降还是持平用一个小标签展示在图表右上角。这个细节很能提升产品感对观察宠物健康状态有明显作用。那一版的图表实现本身没有出问题但我在验证时发现一个数据倒序问题新增记录后最新数据在图表上出现在左边而不是右边。我让AI调整了数据排序逻辑一句指令就解决了。这类体验问题在AI生成的代码里很普遍因为AI默认按创建顺序排序不会主动去想人类习惯的“时间从左到右流动”的直觉。所以在验收任何数据展示类功能时都要特意检查一下排序方向。5. AI生成的界面能看但不好用交互与视觉的迭代打磨5.1 让AI照着参考风格改样式的迭代方式Claude Code第一次交出的前端界面只能说“能用”谈不上好看默认的浏览器字体、白色背景、生硬的表格布局所有页面就像是从管理后台模板里批量复制的。很多人到这里会很失望觉得AI做不了好看的界面但我发现只要给对方法AI在UI设计上的上限远比想象中高。我采用的方式是“给风格锚点而不是抽象形容词”。如果我只是说“界面要好看”它无从下手。当我给出具体的视觉描述时它就有了明确方向。我的指令是重构前端UI风格整体采用卡片式布局主色调用暖橙色(#F59E0B)背景用浅灰白色卡片白色带圆角和轻微阴影。列表项要有图标、标题、副标题三层结构。移动端优先宽度不超过480px时单列布局。它一次就完成了一次相当成功的视觉升级从“应付作业”变成了“有点精致的小应用”。这个过程让我意识到AI在视觉设计上的能力并不是弱而是需要人给它可落地的定义——颜色、间距、层次结构、是否圆角。就像给设计师写一份有参考图的设计稿而不是只丢一句“做个高级感”。5.2 空状态、加载态、错误提示体验细节要主动提需求迭代完视觉之后我发现一个更隐蔽的短板Claude Code默认生成的代码几乎没有处理“边界状态”。比如一只新宠物没有任何健康记录时详情页就是一片空白网络请求失败时会静默用户根本不知道发生了什么删除操作没有撤销或提示点错了就是一个不可逆的动作。这些状态单独看都不起眼但它们决定了一个产品“像正经产品”还是“像Demo”。我专门开了个会话来处理这些问题检查全站所有页面为以下场景补充界面 1. 空状态没有数据时显示友好的引导文案和行动按钮 2. 加载状态请求期间显示居中加载动画 3. 错误状态请求失败时显示错误信息并提供重试按钮 4. 危险操作删除类操作统一使用二次确认弹窗它很精准地列出了一个待办清单然后逐页处理完。做完之后Product的感觉立刻不一样了。这个经验我是认真的AI作为默认配置时会把所有注意力放在“正常流程”上那些用户在真实使用中一定会遇到的不正常情况就要靠你在需求里主动提出来。你不说它默认不去做。6. 从“本地能跑”到“真正能用”测试、联调与部署6.1 让AI自己写单测边界条件一个都别放过提醒逻辑是整个应用里最不能出错的部分一个日期偏差就可能导致用户错过疫苗时间。所以我让Claude Code优先对这个模块做单元测试。它选择的测试框架是Vitest跟Vite天然兼容不需要额外配置。我给的指令里有明确的测试用例清单为server端的提醒日期计算函数写单元测试覆盖以下场景 1. 正常计算happened_at 2025-03-01cycle_days 365结果为2026-03-01 2. 跨年场景2025-12-15 30天 2026-01-14 3. 周期性更新连续两次执行驱虫下次日期始终基于上一次执行日期 4. 空值场景cycle_days为null时next_due_at不生成提醒它按照清单写出来的测试跑完之后全部通过。有一个用例我还真没想到当happened_at是2024-02-29闰年时加上365天会得出什么结果它自动补了这个测试断言等于2025-02-28因为2025年不是闰年、没有2月29日。这种细节能想到并且用测试兜住说明它在边界条件的推演上至少达到合格水平。6.2 联调踩过的坑CORS、路由刷新404前后端联调是另一个容易出现问题的环节。一开始我在前端页面请求后端接口时控制台报出CORS错误因为前后端跑在不同端口上。Claude Code在后端加了一个cors中间件就解决了。但在实际部署之后遇到的另一个坑它没能提前预判前端使用React Router的BrowserRouter模式时直接访问某个深层路由地址Nginx会返回404。比如用户访问https://petlife.example.com/pets/1Nginx会去寻找名叫1的静态文件找不到就报404。我让Claude Code在本地复现这个问题它仔细检查后发现生产环境的前端路由应该使用HashRouter或者服务器配置降级到index.html。对一个本地小型应用来说HashRouter更省事——没有服务器配置的心智负担刷新永不404。6.3 用Docker Compose一键部署开发完之后的部署环节我继续让Claude Code完成同时提前给它指定方案为项目编写Docker部署方案 - 前端用Nginx容器托管构建产物 - 后端用Node容器跑Express - SQLite数据库文件放到一个volume中持久化 - 用docker-compose.yml一键编排 - 前端通过环境变量配置后端API地址它分别生成了前端Dockerfile、后端Dockerfile、nginx配置和docker-compose.yml。我在一台测试服务器上执行docker compose up -d --build一条命令就把整个应用拉起来了。数据库文件通过volume挂载到宿主机目录里我只需要定期备份这个目录里的单个.db文件即可。对个人项目来说这个部署复杂度不能再低了。7. 用Claude Code做完整个项目之后我总结的实战经验7.1 上下文管理是最大的隐形坑使用Claude Code最大的风险不是它能力不足而是上下文失忆。它会忘记自己二十分钟前写的函数叫什么名字也会忘记你最开始定下的命名规则。如果没有CLAUDE.md这个“项目外部记忆”每开一次新会话项目就等于失忆一次。项目后期我养成了一个习惯每完成一个模块就让Claude Code在CLAUDE.md里更新“项目当前进度”部分把新模块的路径、核心函数名、注意事项都写上去。下一轮工作时它会自动读取这份记忆跨会话的连续性就保住了。7.2 AI会“过度设计”简单的事容易被复杂化Claude Code有一个非常典型的倾向遇到一个问题时优先引入新依赖或新抽象而不是用最朴素的方式解决。比如让它实现“宠物列表筛选”它可能会引入一个状态管理库还写了个自定义Hook。看起来代码很“工程”实际上完全是不必要的复杂度。我的规则是每段功能代码生成之后我都会扫一眼依赖和复杂度。如果判断“加一个依赖的维护成本已经超过了它带来的好处”直接让AI重写明确要求“不要引入新库用最简单的循环实现”。AI的能力边界不是“能不能写出复杂代码”而是“能不能判断复杂是否有必要”。做选择和做取舍这件事目前AI还需要人的判断力来把关。7.3 给AI下指令的正确姿势验收标准比形容词有用如果你只能从这篇文章里带走一条经验那就是指令质量决定输出质量。给它说“页面做得好看一点”它只能瞎猜但你说“列表用卡片样式主色白色底、灰色边框、圆角12px主按钮用橙色”它就能一口气交付。我把常用指令模板总结成了三句话功能指令必须包含触发条件、业务规则、预期结果修改指令必须指出具体文件或页面并写明验收标准代码生成之后必须先问“你确定吗”然后看关键部分的实现不要盲信也许将来AI自己能写全栈项目不需要人做太多判断但眼下这个阶段人依然是项目的架构师AI是把架构图纸落地成代码的工程师。这两者配合好了一个周末搭出一个能用的全栈应用完全不是什么神奇的离奇事。希望这篇实战记录能让你对自己动手做第一个AI辅助项目多一份信心。