最近这一年AI 编程工具的迭代速度快得离谱以前我们说全栈开发是前后端通吃现在“AI 全栈开发”更像是“人机协同下的全流程交付”。我自己的项目组从最初大家各自用 ChatGPT 和 Cursor 写点页面到现在把这套东西沉淀成一套可以复制的流程中间踩了不少坑也试过从 vibe coding 一路走到 harness × SDD 全栈开发实战终于摸出一套比较稳定、能上生产的 AI 辅助开发方式。这篇文章就把这些经验完整写出来。适合正在用 Cursor、Copilot、各类 Agent 工具做全栈项目又不想让代码库变成大型事故现场的开发者。我会尽量把“为什么这么做”讲清楚而不只是丢一堆工具清单。1. 为什么 AI 全栈开发需要一套最佳实践1.1 从 vibe coding 到 harness × SDD开发范式的转折先说说 vibe coding。这个词描述的状态很形象开发者不逐行手写代码而是用一句模糊的需求概念让 AI 模型不断生成代码通过关键词引导模型往某个方向走代码能不能跑起来靠跑一下就知道。我早期干过类似的事让 AI 生成一个 React 页面加上 Flask 后端再连一个 SQLite 数据库整个过程非常爽十分钟出一个原型。但爽过之后的代价是代码里充满了 AI 自己编造的接口、重复的逻辑、不存在的依赖最离谱的是有一个功能模块调用了第三方 SDK 里根本不存在的类。这就是 vibe coding 的边界。它适合做原型验证、写一次性脚本、快速试探某个技术方案的可行性但不适合直接作为唯一方法去交付一个全栈项目。一旦代码量上去AI 的“乐观幻觉”会被成倍放大。于是有了第二个思路harness × SDDSpec-Driven Development。说白了就是给 AI 套一个隐性约束框架先写规格再写代码用测试和验收条件来兜底让 AI 的生成行为从“自由发挥”变成“按规格实现”。这不是放弃 vibe coding而是把它收编成流程里的一个环节构思阶段可以 vibe落地阶段必须 harness。1.2 工具链选型背后的取舍自由度和约束的平衡最佳实践不是一个单一工具而是一整套工具链的配合。我的默认组合是这样的IDE 层用 Cursor 做交互式补全和单文件重构命令行层用一个支持多文件、多步骤任务的 Agent CLI 处理跨模块改造模型层通过 Litellm Proxy 统一接入多个模型包括云端模型和本地模型流程层用 SDD 规范加自动化测试来约束 AI 的输出。这套组合的核心逻辑不是“谁最强选谁”而是在自由度和约束之间找平衡。你可以把 AI 全栈开发想象成开车。vibe coding 像是没有导航的飙车爽但容易翻。全手动写代码像是推着车走安全但慢。最佳实践就是给车装上导航、车道保持和刹车辅助AI 负责踩油门和打方向盘规格、测试、代码审查机制负责确保你不冲出马路。工具链里的 Agent 是油门Litellm 是道路监控SDD 是交通规则。这样组合下来单个环节出问题都能被其他环节兜住。1.3 这套思路适合谁解决什么问题这套最佳实践尤其适合三类人第一类是 Solo 全栈开发者一个人要同时维护前端、后端、部署和数据库AI 能把重复劳动力释放出来但如果没有流程约束很容易在代码膨胀之后失去掌控第二类是小型团队里负责业务系统交付的工程师需求变化快没有太多时间写文档但又不想让 AI 生成的代码变成技术债第三类是正在做 AI 产品原型验证的人需要在几天内把 idea 变成可演示、可测试的 MVP同时保留后续继续迭代的余地。它解决的问题也很明确不是“写得快”而是“改得稳”。AI 生成代码的速度从来不是瓶颈瓶颈在于AI 不知道你在改什么、为什么改、改了之后哪里会坏。SDD harness 的方式把“上下文”显式化让 AI 每一次改动都基于一个可验证的规格而不是靠猜。实际跑下来代码返工率下降得比我预想还明显团队协作时扯皮的次数也少了。2. 核心细节拆解让 AI 真正融入全栈开发的四个关键环节2.1 上下文管理比提示词更影响结果如果你觉得 AI 生成代码不够准问题通常不是模型不够强而是上下文给得不够好。全栈开发的上下文其实分三层全局上下文项目结构、技术栈、页面路由、局部上下文当前文件、相关组件、API 定义、数据库 Schema、任务上下文需求描述、验收条件、约束。我见过很多同事把整个项目的代码一股脑丢给 AI以为上下文越多越好结果模型被无关文件干扰反而忽略关键约束。最佳实践是用 Agent 工具自带的代码检索能力比如 Cursor 的 Codebase 索引、CLI Agent 的 grep 和文件读取能力按需提取局部上下文而不是把所有内容塞进 prompt。同时我会把项目根目录放一个AGENTS.md或CLAUDE.md文件描述技术栈、目录结构、编码规范、测试命令让 AI 在开始任何任务前先读取它。这个文件的收益非常高相当于给 AI 配了一张项目地图不需要每次重复解释项目的背景。上下文管理的另一个细节是“会话长度的控制”。AI 模型的上下文窗口虽然越来越大但是长上下文之后模型往往会“注意力稀释”遗忘最早的指令。所以我在处理一个大型重构任务时会主动拆分成多个子任务每个子任务开新的会话只把必要的背景信息带过去而不是一个会话从头聊到尾。这个习惯让 AI 输出的稳定度提升了一个档次。2.2 规范优先用 Spec 约束 AI 的输出SDD 的核心不是写一堆文档而是写一份“可执行的需求规格”。什么叫可执行每条需求都能对应到验收条件每个接口都能对应到输入输出样例每个页面都能对应到用户故事。我用一个非常轻量的 spec 模板格式是 Markdown放在specs/目录下每个功能一个文件。模板包含以下部分功能描述用两到三句话说明这个功能解决什么问题。用户故事As a ... I want ... so that ...。技术约束使用哪些技术栈、不能引入哪些新依赖、是否兼容老接口。接口定义请求、响应、错误码、数据结构尽量给出 JSON 示例。验收条件用 Given/When/Then 写每一句都要能在测试里机械验证。边界情况空值、超时、权限不足、并发冲突等。有了 specAgent 的代码生成就从“猜需求”变成“翻译需求”。测试就是翻译的质量检查员。我通常要求 Agent 在写实现的同时写一组最小测试覆盖验收条件。如果没有测试直接不接收这个功能的实现。这样做的好处是AI 即使某次生成出有问题的代码也可以在测试阶段被拦下来不至于积累到上生产才爆雷。2.3 Agent 工作流从“补全代码”到“独立完成任务”现在的 AI Agent 已经能完成“补全代码”之外的完整任务修改多个文件、运行测试、根据报错自动修复、生成 commit 信息甚至提 PR。但 Agent 做多步任务时容易东一榔头西一棒槌我在实际操作中摸索出几个固定动作把它们串成工作流第一步是让 Agent 先读 spec 和相关代码产出实现方案不要立刻写代码。这一步很重要相当于让 AI 先“复述需求”确认它理解正确。第二步是让 Agent 列出将要修改的文件清单以及每个文件修改的原因。我审查这个清单能发现很多设计问题。第三步才是写代码写完代码必须跑测试测试失败就迭代修复最多迭代三次超过就停下来人工介入。第四步是代码审查我不会让 AI 审查自己的代码而是用另一个不同视角的指令比如让它从安全角度、性能角度分别审查再反馈给实现 Agent 修改。这套工作流跑顺之后我一个中型全栈功能的开发时间从“人工手写两天”压缩到“AI 协作一个下午”而且代码质量比之前还稳定。但前提是每一步都有清晰指令不能给 AI 太模糊的“帮我改个东西”。2.4 模型与网关Litellm Proxy 扮演的角色多模型混合使用是 AI 全栈开发里容易被忽略的一环。我们的应用里IDE 补全、代码审查、测试生成、文档总结这些任务对模型的偏好并不一样。有些便宜模型写代码也行但做深度代码审查时理解力不够有些模型写通用代码优秀但不擅长处理中文需求描述。所以我用 Litellm Proxy 统一封装这些模型对外暴露一个 OpenAI 兼容的 API 网关。实践上我的litellm_config.yaml大概是这样的model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-code litellm_params: model: anthropic/claude-sonnet-4 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-fast litellm_params: model: ollama/qwen2.5-coder:14b api_base: http://localhost:11434 api_key: dummy这样我所有 Agent 工具都指向同一个 Base URL比如http://localhost:8000但可以在不同任务里动态切换模型还能统一做日志、限流和 token 统计。尤其是团队协作时每个人不用配置各自的模型 key只需要连代理权限和费用也能统一管控。Litellm 在这里不是“模型选择器”而是 AI Infra 的基础设施让整个开发流程里的模型调用都变得可观测、可管理。3. 实操过程一个全栈功能从 0 到 1 跑通的全过程3.1 环境搭建本地模型网关 IDE 插件 Agent CLI我选择一个真实的例子来说明整套流程为一个内容管理后台加一个“文章标签批量替换”功能。这个功能听起来简单但它涉及前端页面、后端 API、数据库迁移和异步任务非常适合演示全栈 AI 开发。先搭环境。本机装了 Cursor命令行装了一个支持 Agent 模式的 CLI 工具模型统一走 Litellm Proxy。本地跑了一个 Ollama加载了qwen2.5-coder:14b作为快速草稿模型重量级的代码审查用云端 Claude日常生成用 GPT-4o。注意我不建议把本地 14B 模型用于所有任务它速度快但复杂逻辑和多文件重构能力不够。我在实践里把它定位为“初稿生成器”或者“代码格式化助手”正式逻辑还是交给强模型。3.2 需求拆解与 Spec 编写我没有直接让 AI 写代码而是先花 15 分钟写了一份 spec放在specs/tag-batch-replace.md。核心内容如下# 文章标签批量替换 ## 功能描述 - 运营人员可在后台选择一个或多个标签替换为目标标签。 - 替换过程涉及所有文章替换完成后需保留操作日志。 ## 技术约束 - 后端使用 FastAPI数据库使用 PostgreSQL。 - 前端使用 React Ant Design。 - 不允许新增重量级任务队列组件使用数据库行锁模拟异步任务。 ## 接口定义 POST /api/admin/tags/replace body: { source_ids: [1,2], target_id: 3 } response: { task_id: ... } GET /api/admin/tags/replace/tasks/{task_id} response: { status: pending|running|done, processed: 100, total: 1200 } ## 验收条件 - Given 有 1200 篇文章包含标签 1 和 2When 发起替换请求Then 每个标签字段都被替换为 3且只执行一次。 - Given 并发提交两个相同替换任务When 第二个任务到达Then 返回冲突错误。 - Given 任务执行中When 前端轮询任务状态Then 状态每 5 秒更新且最终为 done。 ## 边界情况 - 目标标签不存在时返回 404。 - 源标签列表为空时返回 422。 - 替换任务失败时已处理的数据可回滚。这份 spec 不复杂但它的存在让 AI 的每一步动作都有了锚点。3.3 代码实现与验证循环接下来我让 Agent CLI 读取这份 spec要求它先输出修改文件清单。它提出了后端加两个路由、一个服务类、一个数据库迁移文件前端加一个 Modal 组件和一个状态轮询 hook。我看了清单补了一条加一个幂等表防止重复替换。然后让 Agent 开工。Agent 写后端时用了 SQLAlchemy写完自动跑了pytest第一次挂了原因是标签关联表的主键冲突处理不对。Agent 读取报错后自动修正第二次通过。前端部分它生成 React 组件我用 Cursor 人工微调了界面布局没有大改。整个过程中我几乎没有手动写业务代码只做审查和决策。这里有一个关键心得不要让 Agent 一次性完成所有文件。我要求它分三步提交先数据库迁移再后端接口最后前端页面。每完成一步我都会运行一遍相关测试和类型检查。如果全堆在一起出了问题定位成本非常高。3.4 联调、测试与收尾最后我启动了本地前后端用 spec 里的接口定义做了手工冒烟测试创建 5 篇测试文章各打上标签 1 和 2发起替换请求确认文章标签最终都变成 3且日志表里有一条替换记录。同时运行了并发请求的测试后端成功返回冲突错误。收尾时我让 Agent 生成了 migration 的回滚脚本、简单的 README 片段和一个自动化测试文件然后提交 PR。这样整个功能下来开发文档和测试都是配套的不会出现“代码写完了但没人知道怎么部署”的状态。这个流程走完我一共花了一个半小时其中一半时间在做 review 和确认边界情况。如果完全用 vibe coding 乱写可能 30 分钟就出活但后续修 bug 的时间绝对超过一天。4. 常见问题与排查技巧实录4.1 上下文丢失或错乱最常遇到的问题是AI 写着写着就忘了最早的技术约束。比如我们要求所有数据库操作必须走事务但 Agent 在后半程生成的代码里直接裸写 SQL没有包裹事务。这不是模型不行是上下文窗口里的关键信息被大量中间输出挤掉了。我的解决方案有两个。一是把关键约束写进项目级指令文件让 Agent 每次开始任务前先读一遍二是把大任务拆小每次只给模型一小部分上下文避免一次塞太多。如果问题依旧直接开新会话把 spec 和“你犯过的错”一起塞给新的模型效果通常立竿见影。4.2 AI 反复修改导致代码退化还有一种很气人的情况AI 修了一个 bug引入了两个新 bug你让它再修它又把之前的正确逻辑改坏了。我在用 Agent 跑迭代修复时限制最多自动修复三轮三轮之后强制人工接管否则会陷入“修一个坏一个”的漩涡。同时要求 Agent 在每次修改前先写一个失败测试证明它理解了问题再去改代码。这个“测试先行”的做法能大幅减少退化。4.3 生成代码存在依赖地狱AI 全栈开发最痛的点之一是依赖管理。模型很喜欢凭空引入“感觉自己用过”的库有时候还会生成一些版本根本不存在的依赖。我的做法是在 spec 里明确写“不新增依赖除非先和开发者确认”另外每次 Agent 生成代码后都会跑一遍依赖检查和构建比如pip install -e .、npm run build一旦有依赖错误就让 Agent 回滚到上一步而不是让它自己乱装包。4.4 安全与合规红线这一点一定要单独说。AI 生成代码容易在安全细节翻车比如硬编码密钥、不小心把日志打到前端、没有做 SQL 注入防护、没有对用户输入做校验。我的习惯是让一个“安全审查 Agent”专门检查 diff重点看密钥、鉴权、输入输出校验。同时禁止 AI 处理任何真实生产密钥所有密钥只通过环境变量注入。团队里也可以定一个简单规则凡是涉及用户数据、付款、权限管理的代码AI 只允许生成 draft必须由人工 review 后再合入。4.5 一份问题速查表症状可能原因解决思路AI 生成代码和需求不符spec 不够细验收条件缺失先补 spec再让 Agent 基于验收条件重写修改一个文件破坏了另一个文件上下文缺少跨文件一致性信息让 Agent 先列出所有受影响文件再动手测试一直过不了AI 反复修不好模型能力不足或任务太复杂换更强模型或人工拆解任务构建报错找不到依赖AI 私自引入新依赖spec 禁止随意添加依赖失败时回滚审查代码发现硬编码密钥没有安全审查环节加一个专门做安全 review 的 Agent 指令5. 写在最后我踩过的坑和仍在坚持的习惯我现在已经很难回到“完全手写所有代码”的状态了但也不再迷信“让 AI 一口气生成全项目”的爽快感。踩过的坑里最深刻的一条是AI 工程的瓶颈不在于模型而在于我们有没有给它一个清晰可信的边界。边界越清楚AI 的产出越靠谱边界模糊再强的模型也会帮你写出一个漂亮的烂摊子。所以我的几个习惯一直没变每个功能先写 spec哪怕只有三行字每个 Agent 任务都要求先交方案再动手每次 AI 生成的代码必须过一遍测试和代码 review所有密钥和敏感操作永远不让 AI 自由接触。这些习惯看着琐碎但它们就是“AI 全栈开发最佳实践”的本质——不是去追最新最快的模型而是把可靠的流程固化下来。我也还在不断尝试把 AI 用到更多环节比如自动生成测试数据、自动补文档、自动分析用户反馈但无论怎么扩展那套“规格、约束、验证、人工审查”的骨架我都不会丢。如果你正准备把 AI 编程引入自己的项目我建议从最小的一个功能开始按这篇文章的流程走一遍你会发现它带给你的不只是速度还有那种“改得动、敢上线”的底气。
AI全栈开发实战：用Spec与Agent构建稳定高效的AI辅助编程流程
最近这一年AI 编程工具的迭代速度快得离谱以前我们说全栈开发是前后端通吃现在“AI 全栈开发”更像是“人机协同下的全流程交付”。我自己的项目组从最初大家各自用 ChatGPT 和 Cursor 写点页面到现在把这套东西沉淀成一套可以复制的流程中间踩了不少坑也试过从 vibe coding 一路走到 harness × SDD 全栈开发实战终于摸出一套比较稳定、能上生产的 AI 辅助开发方式。这篇文章就把这些经验完整写出来。适合正在用 Cursor、Copilot、各类 Agent 工具做全栈项目又不想让代码库变成大型事故现场的开发者。我会尽量把“为什么这么做”讲清楚而不只是丢一堆工具清单。1. 为什么 AI 全栈开发需要一套最佳实践1.1 从 vibe coding 到 harness × SDD开发范式的转折先说说 vibe coding。这个词描述的状态很形象开发者不逐行手写代码而是用一句模糊的需求概念让 AI 模型不断生成代码通过关键词引导模型往某个方向走代码能不能跑起来靠跑一下就知道。我早期干过类似的事让 AI 生成一个 React 页面加上 Flask 后端再连一个 SQLite 数据库整个过程非常爽十分钟出一个原型。但爽过之后的代价是代码里充满了 AI 自己编造的接口、重复的逻辑、不存在的依赖最离谱的是有一个功能模块调用了第三方 SDK 里根本不存在的类。这就是 vibe coding 的边界。它适合做原型验证、写一次性脚本、快速试探某个技术方案的可行性但不适合直接作为唯一方法去交付一个全栈项目。一旦代码量上去AI 的“乐观幻觉”会被成倍放大。于是有了第二个思路harness × SDDSpec-Driven Development。说白了就是给 AI 套一个隐性约束框架先写规格再写代码用测试和验收条件来兜底让 AI 的生成行为从“自由发挥”变成“按规格实现”。这不是放弃 vibe coding而是把它收编成流程里的一个环节构思阶段可以 vibe落地阶段必须 harness。1.2 工具链选型背后的取舍自由度和约束的平衡最佳实践不是一个单一工具而是一整套工具链的配合。我的默认组合是这样的IDE 层用 Cursor 做交互式补全和单文件重构命令行层用一个支持多文件、多步骤任务的 Agent CLI 处理跨模块改造模型层通过 Litellm Proxy 统一接入多个模型包括云端模型和本地模型流程层用 SDD 规范加自动化测试来约束 AI 的输出。这套组合的核心逻辑不是“谁最强选谁”而是在自由度和约束之间找平衡。你可以把 AI 全栈开发想象成开车。vibe coding 像是没有导航的飙车爽但容易翻。全手动写代码像是推着车走安全但慢。最佳实践就是给车装上导航、车道保持和刹车辅助AI 负责踩油门和打方向盘规格、测试、代码审查机制负责确保你不冲出马路。工具链里的 Agent 是油门Litellm 是道路监控SDD 是交通规则。这样组合下来单个环节出问题都能被其他环节兜住。1.3 这套思路适合谁解决什么问题这套最佳实践尤其适合三类人第一类是 Solo 全栈开发者一个人要同时维护前端、后端、部署和数据库AI 能把重复劳动力释放出来但如果没有流程约束很容易在代码膨胀之后失去掌控第二类是小型团队里负责业务系统交付的工程师需求变化快没有太多时间写文档但又不想让 AI 生成的代码变成技术债第三类是正在做 AI 产品原型验证的人需要在几天内把 idea 变成可演示、可测试的 MVP同时保留后续继续迭代的余地。它解决的问题也很明确不是“写得快”而是“改得稳”。AI 生成代码的速度从来不是瓶颈瓶颈在于AI 不知道你在改什么、为什么改、改了之后哪里会坏。SDD harness 的方式把“上下文”显式化让 AI 每一次改动都基于一个可验证的规格而不是靠猜。实际跑下来代码返工率下降得比我预想还明显团队协作时扯皮的次数也少了。2. 核心细节拆解让 AI 真正融入全栈开发的四个关键环节2.1 上下文管理比提示词更影响结果如果你觉得 AI 生成代码不够准问题通常不是模型不够强而是上下文给得不够好。全栈开发的上下文其实分三层全局上下文项目结构、技术栈、页面路由、局部上下文当前文件、相关组件、API 定义、数据库 Schema、任务上下文需求描述、验收条件、约束。我见过很多同事把整个项目的代码一股脑丢给 AI以为上下文越多越好结果模型被无关文件干扰反而忽略关键约束。最佳实践是用 Agent 工具自带的代码检索能力比如 Cursor 的 Codebase 索引、CLI Agent 的 grep 和文件读取能力按需提取局部上下文而不是把所有内容塞进 prompt。同时我会把项目根目录放一个AGENTS.md或CLAUDE.md文件描述技术栈、目录结构、编码规范、测试命令让 AI 在开始任何任务前先读取它。这个文件的收益非常高相当于给 AI 配了一张项目地图不需要每次重复解释项目的背景。上下文管理的另一个细节是“会话长度的控制”。AI 模型的上下文窗口虽然越来越大但是长上下文之后模型往往会“注意力稀释”遗忘最早的指令。所以我在处理一个大型重构任务时会主动拆分成多个子任务每个子任务开新的会话只把必要的背景信息带过去而不是一个会话从头聊到尾。这个习惯让 AI 输出的稳定度提升了一个档次。2.2 规范优先用 Spec 约束 AI 的输出SDD 的核心不是写一堆文档而是写一份“可执行的需求规格”。什么叫可执行每条需求都能对应到验收条件每个接口都能对应到输入输出样例每个页面都能对应到用户故事。我用一个非常轻量的 spec 模板格式是 Markdown放在specs/目录下每个功能一个文件。模板包含以下部分功能描述用两到三句话说明这个功能解决什么问题。用户故事As a ... I want ... so that ...。技术约束使用哪些技术栈、不能引入哪些新依赖、是否兼容老接口。接口定义请求、响应、错误码、数据结构尽量给出 JSON 示例。验收条件用 Given/When/Then 写每一句都要能在测试里机械验证。边界情况空值、超时、权限不足、并发冲突等。有了 specAgent 的代码生成就从“猜需求”变成“翻译需求”。测试就是翻译的质量检查员。我通常要求 Agent 在写实现的同时写一组最小测试覆盖验收条件。如果没有测试直接不接收这个功能的实现。这样做的好处是AI 即使某次生成出有问题的代码也可以在测试阶段被拦下来不至于积累到上生产才爆雷。2.3 Agent 工作流从“补全代码”到“独立完成任务”现在的 AI Agent 已经能完成“补全代码”之外的完整任务修改多个文件、运行测试、根据报错自动修复、生成 commit 信息甚至提 PR。但 Agent 做多步任务时容易东一榔头西一棒槌我在实际操作中摸索出几个固定动作把它们串成工作流第一步是让 Agent 先读 spec 和相关代码产出实现方案不要立刻写代码。这一步很重要相当于让 AI 先“复述需求”确认它理解正确。第二步是让 Agent 列出将要修改的文件清单以及每个文件修改的原因。我审查这个清单能发现很多设计问题。第三步才是写代码写完代码必须跑测试测试失败就迭代修复最多迭代三次超过就停下来人工介入。第四步是代码审查我不会让 AI 审查自己的代码而是用另一个不同视角的指令比如让它从安全角度、性能角度分别审查再反馈给实现 Agent 修改。这套工作流跑顺之后我一个中型全栈功能的开发时间从“人工手写两天”压缩到“AI 协作一个下午”而且代码质量比之前还稳定。但前提是每一步都有清晰指令不能给 AI 太模糊的“帮我改个东西”。2.4 模型与网关Litellm Proxy 扮演的角色多模型混合使用是 AI 全栈开发里容易被忽略的一环。我们的应用里IDE 补全、代码审查、测试生成、文档总结这些任务对模型的偏好并不一样。有些便宜模型写代码也行但做深度代码审查时理解力不够有些模型写通用代码优秀但不擅长处理中文需求描述。所以我用 Litellm Proxy 统一封装这些模型对外暴露一个 OpenAI 兼容的 API 网关。实践上我的litellm_config.yaml大概是这样的model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY - model_name: claude-code litellm_params: model: anthropic/claude-sonnet-4 api_key: os.environ/ANTHROPIC_API_KEY - model_name: local-fast litellm_params: model: ollama/qwen2.5-coder:14b api_base: http://localhost:11434 api_key: dummy这样我所有 Agent 工具都指向同一个 Base URL比如http://localhost:8000但可以在不同任务里动态切换模型还能统一做日志、限流和 token 统计。尤其是团队协作时每个人不用配置各自的模型 key只需要连代理权限和费用也能统一管控。Litellm 在这里不是“模型选择器”而是 AI Infra 的基础设施让整个开发流程里的模型调用都变得可观测、可管理。3. 实操过程一个全栈功能从 0 到 1 跑通的全过程3.1 环境搭建本地模型网关 IDE 插件 Agent CLI我选择一个真实的例子来说明整套流程为一个内容管理后台加一个“文章标签批量替换”功能。这个功能听起来简单但它涉及前端页面、后端 API、数据库迁移和异步任务非常适合演示全栈 AI 开发。先搭环境。本机装了 Cursor命令行装了一个支持 Agent 模式的 CLI 工具模型统一走 Litellm Proxy。本地跑了一个 Ollama加载了qwen2.5-coder:14b作为快速草稿模型重量级的代码审查用云端 Claude日常生成用 GPT-4o。注意我不建议把本地 14B 模型用于所有任务它速度快但复杂逻辑和多文件重构能力不够。我在实践里把它定位为“初稿生成器”或者“代码格式化助手”正式逻辑还是交给强模型。3.2 需求拆解与 Spec 编写我没有直接让 AI 写代码而是先花 15 分钟写了一份 spec放在specs/tag-batch-replace.md。核心内容如下# 文章标签批量替换 ## 功能描述 - 运营人员可在后台选择一个或多个标签替换为目标标签。 - 替换过程涉及所有文章替换完成后需保留操作日志。 ## 技术约束 - 后端使用 FastAPI数据库使用 PostgreSQL。 - 前端使用 React Ant Design。 - 不允许新增重量级任务队列组件使用数据库行锁模拟异步任务。 ## 接口定义 POST /api/admin/tags/replace body: { source_ids: [1,2], target_id: 3 } response: { task_id: ... } GET /api/admin/tags/replace/tasks/{task_id} response: { status: pending|running|done, processed: 100, total: 1200 } ## 验收条件 - Given 有 1200 篇文章包含标签 1 和 2When 发起替换请求Then 每个标签字段都被替换为 3且只执行一次。 - Given 并发提交两个相同替换任务When 第二个任务到达Then 返回冲突错误。 - Given 任务执行中When 前端轮询任务状态Then 状态每 5 秒更新且最终为 done。 ## 边界情况 - 目标标签不存在时返回 404。 - 源标签列表为空时返回 422。 - 替换任务失败时已处理的数据可回滚。这份 spec 不复杂但它的存在让 AI 的每一步动作都有了锚点。3.3 代码实现与验证循环接下来我让 Agent CLI 读取这份 spec要求它先输出修改文件清单。它提出了后端加两个路由、一个服务类、一个数据库迁移文件前端加一个 Modal 组件和一个状态轮询 hook。我看了清单补了一条加一个幂等表防止重复替换。然后让 Agent 开工。Agent 写后端时用了 SQLAlchemy写完自动跑了pytest第一次挂了原因是标签关联表的主键冲突处理不对。Agent 读取报错后自动修正第二次通过。前端部分它生成 React 组件我用 Cursor 人工微调了界面布局没有大改。整个过程中我几乎没有手动写业务代码只做审查和决策。这里有一个关键心得不要让 Agent 一次性完成所有文件。我要求它分三步提交先数据库迁移再后端接口最后前端页面。每完成一步我都会运行一遍相关测试和类型检查。如果全堆在一起出了问题定位成本非常高。3.4 联调、测试与收尾最后我启动了本地前后端用 spec 里的接口定义做了手工冒烟测试创建 5 篇测试文章各打上标签 1 和 2发起替换请求确认文章标签最终都变成 3且日志表里有一条替换记录。同时运行了并发请求的测试后端成功返回冲突错误。收尾时我让 Agent 生成了 migration 的回滚脚本、简单的 README 片段和一个自动化测试文件然后提交 PR。这样整个功能下来开发文档和测试都是配套的不会出现“代码写完了但没人知道怎么部署”的状态。这个流程走完我一共花了一个半小时其中一半时间在做 review 和确认边界情况。如果完全用 vibe coding 乱写可能 30 分钟就出活但后续修 bug 的时间绝对超过一天。4. 常见问题与排查技巧实录4.1 上下文丢失或错乱最常遇到的问题是AI 写着写着就忘了最早的技术约束。比如我们要求所有数据库操作必须走事务但 Agent 在后半程生成的代码里直接裸写 SQL没有包裹事务。这不是模型不行是上下文窗口里的关键信息被大量中间输出挤掉了。我的解决方案有两个。一是把关键约束写进项目级指令文件让 Agent 每次开始任务前先读一遍二是把大任务拆小每次只给模型一小部分上下文避免一次塞太多。如果问题依旧直接开新会话把 spec 和“你犯过的错”一起塞给新的模型效果通常立竿见影。4.2 AI 反复修改导致代码退化还有一种很气人的情况AI 修了一个 bug引入了两个新 bug你让它再修它又把之前的正确逻辑改坏了。我在用 Agent 跑迭代修复时限制最多自动修复三轮三轮之后强制人工接管否则会陷入“修一个坏一个”的漩涡。同时要求 Agent 在每次修改前先写一个失败测试证明它理解了问题再去改代码。这个“测试先行”的做法能大幅减少退化。4.3 生成代码存在依赖地狱AI 全栈开发最痛的点之一是依赖管理。模型很喜欢凭空引入“感觉自己用过”的库有时候还会生成一些版本根本不存在的依赖。我的做法是在 spec 里明确写“不新增依赖除非先和开发者确认”另外每次 Agent 生成代码后都会跑一遍依赖检查和构建比如pip install -e .、npm run build一旦有依赖错误就让 Agent 回滚到上一步而不是让它自己乱装包。4.4 安全与合规红线这一点一定要单独说。AI 生成代码容易在安全细节翻车比如硬编码密钥、不小心把日志打到前端、没有做 SQL 注入防护、没有对用户输入做校验。我的习惯是让一个“安全审查 Agent”专门检查 diff重点看密钥、鉴权、输入输出校验。同时禁止 AI 处理任何真实生产密钥所有密钥只通过环境变量注入。团队里也可以定一个简单规则凡是涉及用户数据、付款、权限管理的代码AI 只允许生成 draft必须由人工 review 后再合入。4.5 一份问题速查表症状可能原因解决思路AI 生成代码和需求不符spec 不够细验收条件缺失先补 spec再让 Agent 基于验收条件重写修改一个文件破坏了另一个文件上下文缺少跨文件一致性信息让 Agent 先列出所有受影响文件再动手测试一直过不了AI 反复修不好模型能力不足或任务太复杂换更强模型或人工拆解任务构建报错找不到依赖AI 私自引入新依赖spec 禁止随意添加依赖失败时回滚审查代码发现硬编码密钥没有安全审查环节加一个专门做安全 review 的 Agent 指令5. 写在最后我踩过的坑和仍在坚持的习惯我现在已经很难回到“完全手写所有代码”的状态了但也不再迷信“让 AI 一口气生成全项目”的爽快感。踩过的坑里最深刻的一条是AI 工程的瓶颈不在于模型而在于我们有没有给它一个清晰可信的边界。边界越清楚AI 的产出越靠谱边界模糊再强的模型也会帮你写出一个漂亮的烂摊子。所以我的几个习惯一直没变每个功能先写 spec哪怕只有三行字每个 Agent 任务都要求先交方案再动手每次 AI 生成的代码必须过一遍测试和代码 review所有密钥和敏感操作永远不让 AI 自由接触。这些习惯看着琐碎但它们就是“AI 全栈开发最佳实践”的本质——不是去追最新最快的模型而是把可靠的流程固化下来。我也还在不断尝试把 AI 用到更多环节比如自动生成测试数据、自动补文档、自动分析用户反馈但无论怎么扩展那套“规格、约束、验证、人工审查”的骨架我都不会丢。如果你正准备把 AI 编程引入自己的项目我建议从最小的一个功能开始按这篇文章的流程走一遍你会发现它带给你的不只是速度还有那种“改得动、敢上线”的底气。