1. 写这篇案例集之前环境与准备工作上一期讲完了基本操作和命令体系这期直接上实战。我用自己积累的几个真实项目场景做样本整理了四种不同类型的开发任务从需求拆解到最终提交每一步都配有实际执行过的指令和踩坑记录。如果你已经装好了工具、跑通过一两个简单例子又想知道在正经项目里怎么发挥它的价值这篇应该正合适。动手之前先把环境理清楚。我平时习惯用一个独立目录专门放这类 AI 辅助开发的实验项目避免和真实工作仓库混在一起。这次的案例集也遵循同样思路所有项目都放在~/lab/下面每个案例一个子目录互不干扰。这样做的好处很明显工具的上下文窗口是有限的目录越小它读代码的效率和准确率越高。1.1 工具定位它不是搜索引擎也不是自动程序员很多刚接触这类工具的人容易把它当成“你描述需求它直接交付成品”的神器。实际用下来它更像一个能力很强但需要你把关的结对编程搭档。它能快速读取整个代码仓库、能跨文件定位逻辑、能帮你生成带有上下文的改动但它不了解你团队内部的隐性约定也不负责帮你做产品决策。这期案例里我会尽量展示它“能做到什么”和“需要你把关什么”的边界。比如数据看板的案例里工具生成的图表组件可以直接用但业务指标的口径最终还是要人工校验过才敢上线。这个判断能力恰恰是工具无法替代的部分。1.2 推荐配置上下文长度与并发预算实战之前我把常用的启动参数固定下来了。如果你和我一样用默认的对话模式建议重点关注三个配置项它们直接影响生成质量上下文窗口尽量开大至少保证工具能同时看到主要入口文件、路由配置和两个核心模块。窗口太窄的话它会频繁“忘记”前面聊过的约束。模型选择代码生成类任务我优先用能力更强的模型文档类任务则用轻量模型速度和成本都更划算。自动执行权限新手阶段先关掉让它只输出命令预览你确认后再执行。等熟悉了它的行为模式再逐步放开。我在.config文件里保存了一套固定参数每次进入项目目录自动加载省去重复敲命令的麻烦。后面每个案例里涉及的关键指令我都按当时的实际输入原样贴出来方便你对照。1.3 案例总览与适用场景先给四个案例做个速览方便你按需跳读案例项目类型核心技能点适合读者案例一数据可视化看板需求拆解、迭代修正、依赖管理从零起步的新手案例二旧项目加登录鉴权理解旧代码、补丁式修改、测试验证有过一定开发经验的人案例三自动生成API文档代码阅读、信息提取、文档交叉核对需要维护项目文档的人案例四重构与单测补全重构建议筛选、批量生成单测、覆盖率分析想提升代码质量的中级开发者这四个案例难度递进但每个都是独立的不需要按顺序读。2. 案例一从零生成一个数据可视化看板第一个案例来自我给某团队做的内部数据展示页。需求很简单从一个 JSON 文件读取数据在前端渲染出折线图和柱状图外加一个简单的筛选下拉框。这类任务非常适合验证工具的基础能力因为它不涉及复杂的业务耦合但又需要完整的工程思维——建项目、装依赖、写代码、跑起来全链路走通。2.1 把模糊需求拆成可执行的指令直接跟工具说“帮我做个可视化看板”它大概率会给你一个完整但和你预期不一致的东西。我踩过这个坑之后学乖了先自己在纸上把需求拆解成四个维度——数据源、展示形式、交互行为、技术栈约束。这次我写下的初始指令是这样的请在 ~/lab/dashboard 目录下创建一个前端项目技术栈使用 Vite React。 数据源是项目根目录下的 data.json格式为 [{date: 2025-01-01, value: 42, category: A}]。 页面顶部放一个下拉框按 category 筛选数据下方用图表库渲染折线图和柱状图分别展示 value 按 date 的趋势和按 category 的汇总。 不需要额外的 UI 框架样式简洁即可。这个指令里每句话都是一个明确约束工具不需要猜。尤其是数据格式我直接把 JSON 的 schema 写进去了它生成的解析逻辑基本不会跑偏。2.2 首轮生成结构与依赖一眼看清工具收到指令后先自己扫描了目录发现是空目录就自动初始化了项目结构。几秒钟后输出了一组要执行的动作清单包括创建 Vite 项目、安装react-router-dom它自作主张加的猜想我会用到路由和图表库、然后生成组件代码。看到这个动作列表的时候我一般会检查两件事依赖是否合理、文件结构是否清晰。我让它生成了这些文件dashboard/ ├── index.html ├── package.json ├── vite.config.js └── src/ ├── main.jsx ├── App.jsx ├── components/ │ ├── FilterBar.jsx │ ├── TrendChart.jsx │ └── CategoryChart.jsx └── utils/ └── loadData.js实际执行后项目能直接npm run dev跑起来。这一步对新手来说最有价值它帮你完成了大量样板工作但每一行代码都展现在你面前你可以随时检查和修改。2.3 迭代修正从能跑到跑得好第一版跑起来之后问题开始暴露。图表里的日期轴格式显示为时间戳而不是2025-01-01这样的格式下拉框筛选后图表没有联动更新。这些都是很典型的细节问题。我不重新描述整个需求而是直接基于当前代码提修改要求趋势图的 X 轴日期格式换成 YYYY-MM-DD数据里的 date 字段本来就是字符串不要转换成时间戳。 下拉框切换 category 时write 两个图表组件要响应新的筛选数据。目前状态只存了 FilterBar 内部需要提升到 App 层级并通过 props 传递。这段指令精准定位了两个问题格式化处理和状态管理。工具基于第一次生成的代码上下文直接做了局部修改没有动其他无关部分。修改后我重新启动项目验证两张图表都正常显示了筛选联动也生效了。这个案例想说明的是工具最强的不是“一次性生成完美代码”而是和你在同一个代码库上连续对话、逐步逼近目标的能力。你不需要反复粘贴代码它能记住自己写过什么。3. 案例二给老项目加登录鉴权第二个案例来自一个真实的老项目一个没有用户体系的内部工具。需求是要加上基于 JWT 的登录鉴权同时不影响现有的所有接口。比起从零新建这种改造任务更考验工具对现有代码的理解能力。3.1 先让工具读懂旧代码而不是急着改代码我接手过不少维护成本很高的老项目上来就让它直接改代码经常出现“改了一个函数打破了三处调用”的灾难。正确做法是先让工具建立对项目的整体认知。我用的指令是请先不要做任何修改。阅读这个项目的代码结构重点说明路由定义在哪里、接口入口是什么、有没有现成的中间件机制、数据库连接和用户表的情况。 用列表形式输出你的理解指出哪些地方可能影响鉴权方案的选型。工具花了几秒钟扫描文件给出了一个结构梳理项目是 Express 框架入口文件在app.js所有接口挂在/api下路由集中在routes/目录数据库用的是 SQLite暂时没有用户表。这个梳理质量相当高它甚至标注了哪个中间件文件是全局启用的——这正好是插入鉴权逻辑的关键位置。3.2 生成补丁式修改先规划后动手确认它读懂了项目我提出具体需求项目增加 JWT 登录鉴权新增 users 表默认插入一个管理员账号新增 /api/login 接口验证用户名密码后返回 token新增全局中间件对 /api 下的所有路由生效但 /api/login 本身不需要 token。现有接口不应有明显调用变化。这次我特意强调“生成修改计划不要立刻执行”。工具给出的方案很清晰先创建一个auth/目录存放中间件、路由和数据库初始化脚本再修改app.js注册中间件最后添加数据库迁移脚本。每个文件改动都列出来并提供一个小型 diff 预览。我确认计划后它按顺序执行了所有操作。生成的代码里校验逻辑完整密码哈希用的是bcrypttoken 过期时间设为 24 小时。这些安全细节通常是新手容易遗漏的它做得不错。3.3 鉴权链路的验证清单代码改完之后直接上线显然不现实。我自己整理了一套快速验证清单一边手动测试一边对照未带 token 请求/api/xxx返回 401 和明确错误信息。用正确账号密码请求/api/login拿到 token错误密码返回 401。带着有效 token 访问原有接口行为和改造前一致带过期 token 返回 401。数据库首次启动时自动创建用户表重复启动不会重复覆盖已有数据。实测下来前三条都顺利通过了唯独第四项出了问题工具生成的初始化脚本在每次启动时都尝试插入管理员账号但没判断是否已存在导致重复插入报错。我反馈给工具后它迅速把插入语句改成了INSERT OR IGNORE问题解决。这个案例的教训是改造旧项目时最关键的步骤不是“写新代码”而是“让工具充分理解旧代码”。跳过高危的“它不认识这个项目”阶段后续生成的代码贴合度会高很多。4. 案例三用代码反推API文档与示例第三个案例处理了一个很多团队都头疼的需求项目写了大半年接口文档一直靠口口相传。我用工具把代码里的接口信息提取出来直接生成了 Markdown 格式的 API 文档顺带写了调用示例。4.1 提取接口信息的关键指令先明确一点工具阅读代码的能力很强但它不会替你判断业务意图。你越清楚需要提取哪些字段生成结果越精准。我的指令是这样写的阅读 routes/ 目录下所有路由文件提取每个接口的HTTP 方法、路径、请求参数包括 query 和 body、响应字段结构、可能的错误码。输出为 Markdown 格式按模块分类每个接口附带一个 curl 调用示例。不要在文档中写入任何推测性的业务描述。这里有个细节值得提最后一句“不要在文档中写入任何推测性的业务描述”很关键。如果没有这句工具会尝试用文件名和参数名去推断业务含义生成的结果往往“看着挺对”实际错误百出。约束它只做信息提取之后文档反而干净可靠。4.2 生成文档后的交叉核对工具生成的文档结构很规整每个接口列了请求方式、路径、参数表、响应示例。但它漏了一个细节——部分接口的query参数带有默认值比如分页接口的pageSize默认 20而它写成了必填参数。我通过和项目里的接口测试文件比对发现问题后直接用这个指令修正分页类接口的 page、pageSize 参数是可选的带有默认值默认值各为 1 和 20。修正文档中这些参数的说明。另外检查是否还有其他类似的可选默认参数被标为必填。修正后的文档基本可以直接交付。这类任务里工具节省的时间最多——人工通读全部路由文件并整理格式可能需要半天它只花了十几分钟就完成了初稿我只需要做交叉验证。5. 案例四重构建议与单元测试补全第四个案例面向的是有一定代码基础的人。项目里有一个历史遗留的工具函数文件函数逻辑复杂、分支多、没有测试。我尝试用工具完成两件事给出重构建议并补全单元测试。5.1 让工具先提改造方案而不是直接动手我把函数文件提交给工具指令是阅读 utils/legacy.js。请先给出重构建议哪些函数可以拆分、哪些变量命名有问题、哪些逻辑可以简化。不要直接修改代码先输出一份评审意见。工具逐行分析了代码后给出了清晰的问题列表某个 200 行的函数实际上混合了三个不同职责两个魔法数字缺少命名常量一个switch分支结构可以改成配置映射。这些建议很常规很可靠。之后我让它按建议拆分为三个独立函数并保持对外接口不变。全程工具自动调用测试来验证行为未变它自己新建了测试文件先跑旧函数的结果做对照。5.2 批量生成单元测试与覆盖率瓶颈重构完成后要补测试。工具先看了现有代码结构自行设计了测试目录然后逐个文件生成用例。生成的测试覆盖了主要分支、正常值和边界值运行全部通过。但覆盖率报告出来后发现还有两行关键分支没覆盖到是错误处理逻辑中的异常路径。工具主动在这些分支上补齐了新的断言用例。这类主动发现测试盲区的行为在实际项目中价值很大。我只需要确认边界条件确实符合业务预期其余校验逻辑交给了断言本身。5.3 人工 review 的立场工具可以批量生成测试但生成不意味着可信。我坚持逐条查看每个用例而不是只跑绿了就算结束。过程中发现有几条断言写得太宽松没有真正校验返回值的关键字段。我给工具反馈“断言只测了返回值是否存在没有测字段值。请为这些用例补充具体期望值”它立刻修正了断言逻辑。在这个案例里工具的效率解放了我的时间让我把精力全部集中在“测试是否测对了东西”上而不是苦于“写测试用例”本身。6. 实战排障记录与心得速查这期案例集做下来我实际遇到过不少问题在这里整理成一个速查表便于你对号入座。我把最常见的问题按现象、原因、解决方法列在下面。现象常见原因有效解法工具频繁“忘记”之前的修改要求上下文窗口溢出或开了新会话单次会话内连续对话不轻易开新会话关键约束重复粘贴一次生成的组件引用了不存在的依赖项目已有依赖列表和新装依赖冲突让工具先输出package.json的依赖清单确认后再开始生成代码修改代码后原有功能报错工具对旧代码理解不充分让工具先输出项目结构理解再生成修改计划不做无计划的直接改动文档中的参数被标为必填实际可填可不填工具只看了参数名和位置没上下文人工对照接口定义文件交叉核对发现后要求修正测试断言太宽跑绿但校验不足生成测试默认以“不报错”为目标而不是“行为正确”为每个用例检查断言是否有具体期望值不满足就要求增强断言自动生成的初始化脚本重复覆盖数据缺少对数据是否已存在的判断修改 SQL 插入逻辑为幂等写法启动前做数据检查6.1 上下文管理最少但够用的信息原则实际使用中最常踩的坑就是上下文管理。一方面想让工具掌握足够信息另一方面它又会因为信息过多而“注意力涣散”。我的经验是每次明确告诉它本次会话的任务边界不让它做无关探索一旦任务切换主动精简上下文把必要的约束重新口头交代一次。比如案例二里我进入鉴权会话时主动描述了“项目是 Express SQLite已有 handlers 目录结构”而不是让工具重新读一遍全部代码。这种“摘要式交接”能让后续对话更高效。6.2 安全边界敏感信息不进对话无论是哪个案例我都严格避免在对话内容里出现数据库密码、内部 token 或关键业务密钥。工具读取代码时可能会接触到这些信息我可以做到的是不让它们被显式写进提问指令里。如果工具生成的文档里包含了敏感占位符我也统一用your-token之类的方式替代。另外涉及真实项目的修改时我总会在动手前确认一遍工具的权限设置是否能自动执行命令、是否能写到系统目录之外。原则上我只在隔离的项目目录里开启自动执行防止它碰不该碰的地方。6.3 个人使用的几个习惯最后分享几个我自己的使用习惯不一定适合所有人但至少对我挺管用每个案例的任务都从一个“调研指令”开始先让工具描述现状再提修改需求。哪怕我完全了解项目也会这么做因为它能确认自己读到的东西和我理解的一致。对话里尽量用“不要修改先给我方案”这类否定式约束开头能显著减少工具直接乱改代码的概率。任何工具生成的改动我都会先看 diff 再确认。这个动作不能省有一次它悄悄把一个方法的输出格式改了差一点造成下游解析失败。我做项目从来不喜欢把工具的结果当作最终答案。它更像是我的第一读者——能秒速读完整个代码库、能按需求生成初稿、能重复执行枯燥的测试补全。而代码能不能合并、文档能不能发布、重构方向正不正确这些决定始终在我手里。希望这期案例集能帮你少走一些弯路把这类工具真正变成自己的生产力杠杆。