★ FEATURED ARTICLE Claude Code这玩意儿出来之后我一直有种感觉以前写项目是一个人憋半天现在是你出嘴AI跑腿。但跑腿归跑腿能不能一次跑对路很大程度上取决于你怎么带它。正好前段时间我想验证一下Claude Code到底能不能扛起一个完整项目就挑了一个不大不小、覆盖面足够广的练手项目——宠物生命周期管理App。为什么选它因为这个需求包含增删改查、时间计算、数据持久化、多页面导航、状态管理、表单校验几乎覆盖了日常业务开发的全部典型场景。如果你能用AI把这种完整项目从零搭出来那搬到别的业务上基本就是换皮的事。这篇文章不聊虚的就把我实际操作Claude Code从初始化到功能完成、再到修bug的完整过程记录下来包括我用过的提示词、踩过的坑以及怎么让AI按你的思路而不是它自己的思路走。适合想用AI做全栈开发、又不想被AI带偏节奏的开发者参考。1. 项目整体设计与思路拆解1.1 为什么宠物生命周期管理是个标准试验田我最初考虑过拿待办清单或者博客系统来试Claude Code后来放弃了原因很简单这两种项目太单薄CRUD写完了就没有纵深了。而宠物生命周期管理App天然具备三层复杂度非常接近真实业务。第一层是基础数据管理。宠物档案要存名字、品种、性别、出生日期、体重、绝育状态还要支持增删改查和头像上传这是最典型的表单列表详情页组合。第二层是关联数据和时间计算。疫苗记录、驱虫记录、体检记录都挂在宠物档案下面每一条健康记录又可能关联下一次提醒日期。这里牵扯到日期差值计算、逾期判断、提前N天提醒是纯前端项目里最能体现逻辑复杂度的部分。第三层是场景化交互。喂食记录要按时间线展示提醒中心要区分今天到期、三天内、已逾期首页还要做概览卡片。这些交互细节加起来足够逼着AI做多次迭代。这个项目最好的地方在于它不需要后端不需要鉴权不需要支付所有复杂度集中在业务逻辑和前端体验上。这样一来Claude Code的能力边界就能被准确测出来——代码生成是否准确、逻辑推导是否可靠、能否处理跨文件修改。1.2 技术选型别给AI增加理解成本技术栈的选择直接影响AI生成代码的准确率。我的原则是选AI训练语料最丰富、生态最稳定的方案不要追新。我最终定的组合是React 18 Vite 5 Tailwind CSS 3.4 localStorage存储 dayjs日期库。选这套有几个具体原因。React 18的Hooks语法在AI的训练数据里占比极高它生成的组件代码出错率明显低于Class组件或老式生命周期写法。Vite作为构建工具启动快、配置少Claude Code在处理vite.config.js这类文件时基本不会出错。Tailwind 3.4而非4.x是因为3.x的类名体系稳定AI不会生成4.x才有的新语法。存储直接用localStorage省掉后端和数据库的搭建成本让整个项目能在一台机器上跑通也方便后续扩展成对接真实后端。这里有个关键判断你用AI搭建项目本质是在和它进行一次大规模结对编程任何一方不熟悉的工具链都会拖慢节奏。我见过有人让AI生成一个基于某个冷门框架的完整项目结果光是框架的API用法就来回纠错五六轮。所以哪怕你有自己的偏好第一版技术栈最好还是贴近主流。2. 环境准备与Claude Code接入2.1 接入前要准备什么用Claude Code之前我先确保本地的Node.js是18以上版本因为Vite 5要求Node 18低于这个版本会直接报错。这一步看似基础但如果让AI帮你排查装环境的问题它往往先怀疑配置文件的错误最后才发现是Node版本太低凭空多消耗几轮对话。我当时的操作是在终端里直接输入node -v确认版本然后全局安装Claude Code的CLI工具。安装完成后在项目目录里执行启动命令它会自动读取当前目录上下文把项目文件的结构扫描进会话里这样后续的提问它才知道你当前有哪些文件。有一个细节值得提Claude Code启动时会问你是否要将当前目录纳入权限范围我建议直接允许读写这个项目不涉及敏感数据限制太多反而会让AI在每次改文件时都停下来问权限打断节奏。2.2 第一轮对话项目初始化启动会话后我输入的第一条指令是这样的在当前目录初始化一个前端项目技术栈是React 18 Vite 5 Tailwind CSS 3.4。 项目是一个宠物生命周期管理App功能包括宠物档案管理、健康记录(疫苗/驱虫/体检)、喂养计划、提醒中心。 第一步只做三件事 1. 创建package.json并安装依赖 2. 配置Vite和Tailwind 3. 搭好src目录结构包括页面目录pages、组件目录components、工具目录utils、数据目录store 先不要写业务代码我确认初始化没问题后再继续。这段提示词有几个精心设计的地方。明确第一步只做三件事是把大任务切成小步块避免AI一次性生成数百行代码后出现无法定位的编译错误。限定先不要写业务代码是为了让我能在干净的骨架上逐步验证每一项功能这比我让AI一口气做完所有事情再回头调试要稳妥得多。Claude Code的输出方式和普通聊天式AI不同它直接在终端里生成文件、安装依赖、执行命令并且会把执行结果回显在对话里。我看到它安装完依赖、创建了目录结构之后就手动执行npm run dev验证了一下页面能正常渲染Vite默认模板这时候才告诉它可以继续写业务逻辑。2.3 用好子命令和上下文管理实操中我发现Claude Code有一个非常实用的特性它可以对已有文件做局部修改而不必让整个文件重新生成。第一次用的时候我还担心它每次都重写文件后来发现它会用类似补丁的方式精准替换代码块这样我有大量手动改动的内容不会被覆盖。这个特性的使用技巧是当我针对某个组件的特定函数提修改需求时明确告诉它要改哪个文件的哪个函数。比如我会说修改store/petStore.js里的updatePet函数让它在体重变化超过1kg时自动记录一条健康变化记录它就能精准定位并只改那一处逻辑而不是把整个store文件推倒重来。3. 核心功能拆解与数据模型设计3.1 三大功能模块的边界划分搭好骨架之后我没有让Claude Code一次性实现所有功能而是按模块逐个击破。每个模块的开发都是同一个节奏先定义数据结构再让AI生成对应页面最后验证交互逻辑。第一个模块是宠物档案。我需要它支持添加宠物、编辑信息、删除宠物、上传头像(用Base64存入localStorage)、按品种过滤列表。这个模块是基础后面所有功能都挂在当前选中的宠物这个上下文下面。第二个模块是健康记录。每条记录需要包含记录类型(疫苗/驱虫/体检)、名称、日期、下一针日期、备注。列表按时间倒序排列同时要根据下一针日期自动计算状态标签已完成、即将到期、已逾期。第三个模块是喂养计划与提醒中心。喂养计划存的是每天的固定喂食时间点和食量提醒中心则综合了疫苗到期提醒、驱虫到期提醒和每日喂食提醒三部分。模块边界清晰之后AI在生成代码时就不会出现功能交叉混乱的问题。我最开始的时候让AI把档案、健康和喂养一起做结果它在一个组件里混入了三个模块的状态逻辑后续维护极其痛苦。后来改成模块化开发之后每个模块的文件职责单一AI生成的代码质量也明显提升。3.2 数据结构让AI代劳前自己先想清楚虽然动手写代码的是AI但数据模型必须自己先设计好这是整个项目最不该省的心力。我告诉Claude Code我要的数据结构长什么样它负责按照这个结构生成代码而不是让它自己发挥设计数据结构。我定义的宠物档案结构是这样的// store/petStore.js 中的核心数据结构 const pet { id: pet_1720000001, name: Lucky, species: dog, // dog | cat | other breed: 柯基, gender: male, birthDate: 2023-04-12, weight: 9.5, // 单位kg isNeutered: true, avatarBase64: , // base64图片数据存localStorage healthRecords: [ { id: hr_001, type: vaccination, name: 狂犬疫苗, date: 2025-06-01, nextDate: 2026-06-01, notes: } ], feedingPlan: [ { id: fp_001, time: 08:00, amount: 80, foodType: 成犬狗粮 }, { id: fp_002, time: 19:00, amount: 80, foodType: 成犬狗粮 } ] }为什么这么设计有几个点是我刻意明确的healthRecords和feedingPlan作为嵌套数组挂在宠物对象下面而不是单独建一张记录表是因为这个App的数据量级很小嵌套结构在localStorage里读写一次性完成不需要做跨实体的数据关联。时间字段统一用YYYY-MM-DD字符串这种格式可以直接做字典序比较不需要转成时间戳再去计算大小。数据结构定好之后我把它发给Claude Code让它基于这个结构去实现localStorage的读写封装和页面渲染。实测下来只要数据结构是明确的AI生成的代码几乎不需要大改。4. 全流程实操从提示词到完整App4.1 提示词的结构化写法在实操过程中我总结了一套对Claude Code特别有效的提示词模板可以拆成四个组成部分上下文、需求、约束、验收方式。上下文告诉AI现在项目处于什么状态、代码在哪些文件里。比如目前pages/PetProfile.jsx里已有宠物详情展示数据来自store/petStore.js的getPetById。没有这个AI可能自己在某个不相干的文件里新建一套逻辑。需求部分要像写用户故事一样具体说清楚在什么交互动作下什么元素应该发生什么变化。比如点击接种记录条目右侧的删除按钮时弹窗确认后删除该条记录同时更新列表中的状态标签。需求越接近代码逻辑AI生成的结果越准确。约束部分是关键很多人在这一步偷懒。我需要显式声明不要引入新的依赖、文件只修改components/HealthRecordList.jsx、沿用现有的Tailwind样式风格。这些约束能有效限制AI的自由发挥。验收方式也不能省。我会要求AI生成后告诉我修改了哪些文件以及用什么命令可以验证功能这样我可以快速手动测试来确认生成结果是否符合预期。4.2 分步实现档案模块到提醒引擎我实际执行的第一个完整功能是宠物档案模块。当时给Claude Code的指令是基于已定义的pet数据结构实现宠物档案模块。 需要三个页面组件 - pages/PetList.jsx宠物卡片列表支持按品种搜索点击卡片进入详情 - pages/PetDetail.jsx宠物详情页展示基本信息、健康记录、喂养计划三个Tab - pages/PetEdit.jsx新增/编辑共用表单字段校验规则名字必填、生日不能晚于今天、体重范围0.5-80kg localStorage的key使用pets_data_v1读取时做JSON解析异常兜底。大约几秒钟后Claude Code就生成了这三个组件并自动更新了路由配置。我跑起来看了看列表渲染、搜索过滤、表单校验都正常唯一的问题是编辑表单里头像上传那块代码它用了FileReader却没处理图片过大的情况。我让它加了一个压缩逻辑限制上传图片在200KB以内超了就提示用户换图。健康记录模块是第二个做的这个模块最核心的是状态标签的计算逻辑。我让AI实现一个工具函数getRecordStatus输入当前日期和记录的nextDate返回状态。我给了它明确的规则nextDate为null或过去日期且当天没有记录时返回completed差值在7天内返回due_soon差值超过7天返回overdue否则返回scheduled。有了这套明确规则AI写出来的函数我根本不需要做边界测试就能放心用。提醒引擎是我觉得最体现AI价值的部分。它需要综合所有宠物的所有健康记录计算出未来14天内的到期提醒同时按天分组。这本质上是一个多源数据聚合加时间窗口计算的逻辑手写大概需要上百行代码。Claude Code生成后我验证了几个关键场景同一只宠物有两条不同日期的疫苗记录、跨月日期计算、已经逾期很久的记录是否归入逾期分组。全部通过了。4.3 界面打磨与交互细节功能跑通之后界面还处于能看但不好看的状态。我让Claude Code在这个阶段做视觉优化但这个阶段的交互方式要变化不能再像功能开发那样下长指令。我采取的方法是给出具体的视觉参考描述让AI逐项调整。比如首页宠物卡片改成横向排列卡片左上角放宠物头像圆形裁切右下角用圆角标签显示最近一次健康记录的到期状态。整体配色使用暖色调宠物相关用橙色系提醒用红色系。AI收到这种描述之后会精确调整Tailwind类名而不是重新设计页面结构。这个阶段我还要注意一件事每次只提一个页面的视觉优化请求验证完成后再进行下一个。如果同时提三个页面AI改了A页面的同时也改了B页面的共用样式组件容易产生连锁视觉问题。全部迭代完之后我又做了一轮交互细节补全空状态提示文案(没有宠物时显示引导添加)、删除确认弹窗、表单输入错误提示、列表加载过渡动画。这些细节单独看都不起眼但凑在一起决定了这个App是demo还是产品。5. 常见问题与排查技巧实录5.1 最典型的五类AI生成错误实践中我整理了Claude Code在这个项目中踩过的五类高频错误后面再做类似项目时直接命中率就高了很多。第一类是引入不存在的模块或API。有一次它生成的健康记录组件引用了react-router-dom的useNavigate但项目里用的是tanstack/react-router页面一跑就白屏。这种错误的排查方法很简单看终端报错信息AI通常只花了30秒就自己定位并修正了但如果你不把报错信息贴给它它就会凭空猜。第二类是旧版React写法残留。AI偶尔会生成componentWillMount、React.createClass这类早已废弃的代码特别是从存储里读旧项目代码做参考时。发现这个问题后我在约束里加了一条只使用React 18的Hooks函数式组件写法之后这类问题基本绝迹。第三类是样式类名错误。Tailwind 3.4的类名体系挺庞大AI偶尔会把flex-shrink-0写成shrink-0、把max-w-screen-xl写成max-w-全屏这种低级错误。我的处理办法是告诉它检查所有Tailwind类名是否为有效类无效类会导致样式丢失让它自己做一轮自纠。第四类是localStorage数据格式错误。AI生成的存储读取函数有时候不处理JSON.parse异常一旦历史数据损坏或格式不一致整个页面直接崩溃。我后来让AI在读写函数里统一加了try-catch和默认值兜底这个改动非常值得。第五类是日期计算的时区问题。用new Date(2025-01-01)在不同时区解析会差出8个小时导致天数计算错误。我让AI统一用dayjs的dayjs(2025-01-01)并指定dayjs()格式解析所有日期比较都用startOf(day)对齐这个问题就彻底解决了。5.2 如何让AI自己修bug而不把代码改坏我一开始遇到bug就让Claude Code直接修但它有时候会为了修一个小问题重写整个组件导致其他功能跟着被改坏。后来我摸索出一个好用的流程。第一步是把报错信息完全复制给AI包括终端里的错误堆栈和浏览器控制台的报错。注意不要只贴一句页面挂了信息越完整AI定位越准。第二步是明确告诉它只修复导致这个错误的最小改动不要重构其他代码。这句话能有效阻止AI的大规模重写冲动。第三步是修复完立即在本地运行和手动验证。AI说修复完成不等于真的修复完成我见过它改完编译错误但引入新逻辑bug的情况手动验证是唯一可靠的方式。另外我还有一个预防性做法在项目根目录下放了一个AGENTS.md文件里面写清楚了项目技术栈、文件职责、代码风格规范和禁止事项。Claude Code在每次会话时都会读取这个文件相当于给它一本项目操作手册。实际效果非常明显它生成的代码从一开始就符合项目约定大大减少了二次修改。5.3 版本控制与AI生成代码的碰撞这个项目虽然是我自己练手用但我也把Git仓库管理起来了。原因是AI批量生成代码时一旦你发现改坏了想回退没有版本控制会很痛苦。我的习惯是每个功能模块完成并验证通过后就git commit一次提交信息用模块名加简单描述。这样如果后续某次AI修改引入了问题可以直接回退到上一个commit。另外我还会在每次让AI做大改动之前手动git stash或commit一次当前状态。有一次Claude Code修改路由配置时误删了两个页面的导入语句我直接git checkout还原了文件整个过程一分钟不到完全不受影响。6. 这套流程的可复制性与后续扩展项目跑通之后我回头审视了整个流程最大的收获不是AI帮我写了个App而是我知道怎么指挥AI写一个App了。6.1 核心方法论归纳整个流程可以压缩成五步。第一步定数据模型把实体的字段、类型、约束先写在纸上。第二步定模块边界明确每个模块的输入输出和页面职责。第三步写结构化提示词把上下文、需求、约束、验收四要素补齐。第四步分模块实现每完成一个模块跑一次验证并提交git。第五步统一做UI打磨和交互细节补全。这套方法论换到其他项目依然成立。比如做一个库存管理App数据模型换成商品和入库记录模块边界换成商品管理和出入库管理其余流程完全一致。本质上Claude Code是一个高效的执行者你负责定义做什么和验收标准它负责把逻辑变成代码。真正决定项目质量的是你的设计能力和判断力而不是AI的代码生成速度。我现在写代码的习惯已经在改变了遇到机械性强的逻辑(表格渲染、表单校验、状态管理样板代码)我会用Claude Code加速遇到需要决策和权衡的架构问题我依然自己花时间想清楚再让它落地。这种协作方式让我同时拥有了速度和判断力。如果让我给一个具体的建议那就是从今天开始用一个小而完整的项目把手这个流程练一遍。别拿生产级系统去试就选一个你自己想做的工具类App。做完之后你会对自己的效率提升有非常直观的感受。
阅读完成 · 觉得有帮助？
