AI Agent 全栈开发实战：从需求拆解到容器部署的完整复盘

AI Agent 构建全栈应用在 2026 年早就不算什么新鲜词了。但你别急着划走我最近刚拿一个练手项目把整套流程完整跑了一遍从需求拆解、技术选型、生成代码、本地联调到容器部署基本上全程把 AI Agent 当主力人只负责把方向和边界。做完之后最大的感受是很多人对这个东西的理解还停留在“自动补全代码”的层面实际上 2026 年的 Agent 早就能读项目、改文件、执行命令、跑测试、看报错再自己修循环。这篇文章我不讲虚的就把这次全链路实操的踩坑过程、提示词思路、技术选型逻辑和最后的审计要点全部复盘一遍。适合两类人一是第一次听说 AI Agent 开发、想找一份能跟着走一遍的攻略的人二是已经用过一些 AI 编程工具但总觉得生成出来东西“能跑又不太稳”、想知道怎么守住质量关的人。1. 先想明白2026 年的 AI Agent 到底能干多少活1.1 从“能补几行代码”到“能跑完整流程”如果你用过早期那批 AI 编程辅助工具印象大概是“在一个文件里帮你补全函数”“根据注释生成一段代码”。这种模式本质上还是人在规划、AI 在打字只不过打字速度快了一些。2026 年的 Agent 早就不是这个逻辑了它更像一个“能自己看项目、自己动手改、自己验证结果”的实习生。这次做项目我让它干过几件很能说明问题的事它读取了项目里十几份文件自己梳理出模块依赖关系一次性生成了二十多个新文件横跨前端、后端和配置文件它能在终端里跑测试命令把失败的堆栈信息读回来再定位到具体文件改代码改完之后它甚至会主动再跑一遍测试确认。整个循环里我不是每行都盯着更多时候是给它一个验收标准然后等结果。这种变化的核心在于Agent 不再是一个“单点的文本生成器”而是一个“带工具的任务执行体”。它能读写文件、能调用终端、能理解报错、能根据反馈迭代。所以同样是一句话需求旧的补全工具只能给你一段代码片段而现在的 Agent 可以给你一个能启动的项目甚至能自己把 bug 修完。当然能跑完流程不代表它能理解业务这是两码事。它可以非常熟练地把技术任务拆解成文件操作和命令执行但一旦碰到“用户到底想要什么”“这个设计合不合理”“这个数据会不会有隐私风险”这类问题它就老实了。这一点我们后面展开说。1.2 哪些环节必须留在人手里很多人搞反了一件事以为 AI Agent 越强大人越可以躺平。实际恰恰相反Agent 越强人的“判断力”越值钱。因为机器擅长的是在明确约束下做执行而模糊地带全部要靠人来补。这次实操我给自己列过一张分工表大概长这样环节交给 Agent 的放心程度说明项目脚手架高初始化目录、安装依赖、生成基础配置这类重复劳动它又快又稳CRUD 代码高单表增删改查、表单校验、基础 API写出来基本不用大改数据库迁移脚本中简单的能搞定涉及复杂索引和执行计划要人工复核前端布局与交互中能用但审美要人把关它默认产出的界面往往丑得真实测试用例中能写但容易只测 happy path边界情况要人补安全与权限策略低绝对不能全托管涉及鉴权、密钥、敏感数据必须人来审核心业务逻辑低业务规则不清晰时它只会猜猜错了就是灾难我的体会是凡是“有清晰输入输出、有标准答案”的活Agent 能扛凡是“需要价值判断、取舍权衡、安全责任”的活最后签字的必须是人。2026 年搞全栈开发本质上是你当技术负责人AI Agent 当你的主力工程师你可以甩活给它但不能甩锅给它。2. 项目拆解与技术栈选型2.1 示例项目“拾字”要解决什么问题我这次做的示例项目叫“拾字”一个个人阅读管理应用。为啥选这个因为它的功能边界足够清晰又能覆盖全栈开发里的典型环节——用户注册登录、图书录入、状态管理、评分和备注、简单的数据看板。没有复杂到需要分布式架构也没有简单到一眼看完。功能清单控制在这么几条图书库录入书名、作者、封面 URL、分类标签阅读状态想读、在读、读完三种状态流转阅读记录读完可以打分、写简短感想看板页统计在读数量、读完数量、平均评分按标签分组登录最简单的账号密码登录JWT 签发会话为什么刻意把 MVP 缩到这么小因为 AI Agent 快速出活的前提是需求边界清晰。我之前试过上来就跟 Agent 说“帮我做一个阅读管理平台”结果它一口气给我设计出社区、推荐算法、好友关注、每日打卡七八个模块代码量直接爆炸根本没维护下去。后来我把范围砍到上面六条整个项目的骨架一下子就清楚了。2.2 技术栈选型背后的三个考量这次选型我定的是前端 React TypeScript后端 FastAPI数据库 PostgreSQL本地和部署都用 Docker Compose 编排。你可能觉得这个组合没什么惊喜但它正好踩中了我反复权衡的三个点。第一是“AI 的熟悉度”。不要小看这一点代码智能体训练语料里最常见的就是这些主流技术栈。同样的需求你让它写一个冷门框架它很容易一本正经地编出错 API写 React 和 FastAPI它基本是在自己熟悉的场地里干活准确率完全不一样。第二是“调试的友好度”。TypeScript 在编译期就能揪出一堆低级错误FastAPI 自带交互式接口文档联调时候少很多痛苦。第三是“部署的标准化”。Docker Compose 把前端、后端、数据库三个服务的依赖关系钉得死死的换台机器一条命令就能起省掉“在我电脑上明明好的”这种经典扯皮。数据库选 PostgreSQL 而不是更轻的 SQLite是因为它更接近真实生产环境。索引、事务、并发控制这些行为差异很大如果开发时用 SQLite、上生产用 PostgreSQLAgent 写出来的 SQL 可能在这边没问题、那边就翻车。一次到位反而省事。2.3 AI Agent 工具怎么挑看图不看广告工具选型这部分我不打算报菜名一样把各家名字列一遍。我只说我在 2026 年挑选编程 Agent 时实际看中的五个指标。上下文长度至少能一次性吞下一个中小型项目的核心文件。上下文不够Agent 就会“失忆”前面刚交代的约束后面就忘了。工具调用能力能不能自己执行命令、读文件、搜索结果而不只是输出文本。没有工具能力的 Agent 再聪明也等于只有一个大脑没有手。多文件编辑能力改一个需求经常涉及前端组件、后端接口、数据库字段一个文件一个文件让它改会累死人必须能跨文件协同改。错误自修复循环测试报错后能不能自己读日志、改代码、再跑一次测试。这个能力直接决定你是在旁边指方向还是当 DEBUG 工具人。自定义指令能不能把你们团队的项目规范、代码风格、禁止事项写到配置文件里让每个新会话自动加载。我那段时间同时试过好几款最后留下了最符合上面五条的一款。不是说它每个功能都最强而是它的“工具调用稳定性”和“自定义指令机制”最让我放心可以反复用不抽风。另外提醒一句别只看演示视频里的完美案例一定拿自己的真实项目测尤其是让它处理一个你没告诉它规则的历史项目看它会不会乱猜。3. 实操全流程从一句话需求到能跑的 Demo3.1 第一步把需求压缩成可执行的 Prompt很多人用 Agent 写全栈应用第一句话就是“帮我做个阅读管理网站”然后就没有然后了。Agent 不是神仙它只能在你给的信息基础上做推断给它模糊输入它就用最省事的方案糊弄你。我这次在第一轮对话里就把需求“钉死”了提示词大概长这样项目名称拾字个人阅读管理应用 项目目标帮助个人用户管理想读、在读、已读的书籍并提供基础统计。 技术栈前端 React TypeScript后端 FastAPIPython数据库 PostgreSQL。 必须包含的功能 1. 用户注册与登录登录后发放 JWT token 2. 图书信息 CRUD字段包括书名、作者、封面URL、分类标签 3. 阅读状态流转想读 - 在读 - 读完 4. 读完可填写评分1-5和读书笔记 5. 看板统计各状态数量、平均分、标签分布。 明确不要做的功能不做社交分享、不做好友关系、不做扫码功能。 验收标准本地 docker compose up 后能一键启动前端页面可以完成全部操作。注意最后两条画风跟前面的功能清单不一样但特别重要。“明确不要做的功能”是在给 Agent 划边界不然它特别容易自己加戏搞得项目失控。“验收标准”是在定义终点Agent 会照着这个目标去判断自己是不是做完了。这一套组合拳打下来后面生成的东西就稳了很多。3.2 第二步生成骨架、数据库与后端 APIPrompt 发出去之后Agent 大概花了几分钟就把项目骨架立起来了。目录结构自动分成了前端、后端、数据库初始化脚本后端里已经建好了用户、图书、笔记这几张表对应的模型。数据库设计这一块值得拿出来单独说说。我让它建表的时候明确要求了外键关系和索引它给出的建表语句大致是这样CREATE TABLE users ( id SERIAL PRIMARY KEY, username VARCHAR(50) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, created_at TIMESTAMPTZ DEFAULT now() ); CREATE TABLE books ( id SERIAL PRIMARY KEY, user_id INTEGER NOT NULL REFERENCES users(id) ON DELETE CASCADE, title VARCHAR(200) NOT NULL, author VARCHAR(100), cover_url TEXT, status VARCHAR(20) NOT NULL DEFAULT wishlist CHECK (status IN (wishlist, reading, finished)), rating INTEGER CHECK (rating BETWEEN 1 AND 5), note TEXT, created_at TIMESTAMPTZ DEFAULT now() ); CREATE INDEX idx_books_user_status ON books(user_id, status);这里有几个细节我是重点审查过的。第一个是status字段用了 CHECK 约束从数据库层就防住非法状态值不能只靠前端管。第二个是外键加了ON DELETE CASCADE用户注销账号时书单自动清理不会留孤儿数据。第三个是索引idx_books_user_status因为看板统计最常见的查询就是“某用户某状态下的书”这个索引能直接把查询成本打下来。这些如果不提醒 Agent它大概率会生成一张没有约束的“万能表”后期查得慢、改得愁。后端 API 部分FastAPI 自动生成的交互式文档给我省了大力气。Agent 写完每一个接口我直接打开/docs页面手动点一遍看参数有没有校验、返回格式是否一致。遇到问题也不自己动手改把接口返回的错误信息原样贴给 Agent它自己会去修。这个“把验证结果反馈给 Agent 让它继续干活”的循环是整个流程里效率最高的环节。3.3 第三步前端页面与业务逻辑后端稳定之后我让 Agent 接着写前端。因为技术栈里有 React 和 TypeScript它自然拆成了组件化的结构列表页、详情页、表单组件、状态标签组件、统计卡片组件各管一摊。前端这块最容易出现的问题是“组件拆得过度或者拆得不够”。过度的时候明明就三行代码也抽成一个文件最后文件数量爆炸拆得不够的时候几千行逻辑全塞在一个组件里后面根本没法改。我当时的处理方法是给 Agent 追加了一条指令每个组件文件不超过 200 行公共逻辑进 hooks接口请求统一放一个 API 模块。Agent 收到这个约束之后生成的代码就规矩多了。状态管理我用了比较轻的方案没有上重型状态库而是靠 React 的请求缓存和局部状态顶住。因为项目功能不复杂硬上大工具等于给 Agent 增加无谓的复杂度它反而容易搞乱。2026 年写前端的一个趋势是“能简单就不复杂”Code 生成的代码更是如此能少绕弯子就少绕弯子。页面联调的时候我吃了点小亏前端调后端接口时跨域问题没配置好。Agent 一开始在本地起了两个服务端口不同浏览器直接拦截请求。我发现之后让它加了一层代理配置把前端的/api请求转发到后端地址问题立刻消失。这种问题纯靠读代码很难看出来必须实际点开页面走一遍流程才暴露所以我的建议是无论 Agent 生成得多顺利前端页面至少自己点过一遍一个功能一个功能过。3.4 第四步本地联调与测试全栈应用最怕什么前后端各跑各的时候都是好的一连起来就翻车。这次联调让我对“让 Agent 自己跑测试”有了新的认识。我给 Agent 下的指令是后端每个核心接口至少要有一个测试用例覆盖正常路径和异常路径。它随后用测试框架生成了几十个测试用例包括“未登录访问受保护接口返回 401”“登录成功返回 token”“评分超出范围被拒绝”等等。这些用例帮我揪出了几个逻辑漏洞比如修改图书信息时没有校验这这本书是不是当前登录用户的等于一个用户可以改别人的书单数据。这个漏洞如果靠人肉点击去测要花不少时间才能发现让 Agent 写测试用例等于让它自己给自己找茬效率完全不一样。本地联调的命令也很简单后端直接前台启动前端启动开发服务器两边日志同时开着。哪个接口请求失败日志里直接能看到堆栈和状态码我只需要把报错信息复制回对话让 Agent 修。这套工作流跑顺之后整个调试过程基本是“发现错误 - 反馈给 Agent - 自动化修复 - 再跑测试”的闭环。3.5 第五步容器化与部署配置开发环境跑通之后最后一步是我一拳一拳逼着 Agent 把部署配置补齐的。2026 年做全栈应用默认部署单元就是容器。我要求 Agent 生成前端、后端、数据库三个服务的编排配置并且满足一个硬性验收标准任何一台装有 Docker 的机器上执行一条命令之后整个系统能起来。它生成的配置核心长这样version: 3.8 services: db: image: postgres:16 environment: POSTGRES_USER: shizi POSTGRES_PASSWORD: ${DB_PASSWORD} POSTGRES_DB: shizi volumes: - pgdata:/var/lib/postgresql/data healthcheck: test: [CMD-SHELL, pg_isready -U shizi] interval: 5s timeout: 3s retries: 5 backend: build: ./backend environment: DATABASE_URL: postgresql://shizi:${DB_PASSWORD}db:5432/shizi JWT_SECRET: ${JWT_SECRET} ports: - 8000:8000 depends_on: db: condition: service_healthy frontend: build: ./frontend ports: - 80:80 depends_on: - backend这里有三个点是我亲手改过的也是值得你们特别注意的。第一数据库连接地址用的是服务名db而不是localhost因为容器网络里每个服务有自己的 DNS 名。第二depends_on配了健康检查条件确保数据库初始化完成之后再启动后端不然后端一启动就连不上库然后崩掉。第三POSTGRES_PASSWORD和JWT_SECRET用的是${VAR}占位符从环境变量注入绝对不能写死进配置文件更不能提交到代码仓库。这些“安全习惯” Agent 不一定每次都自觉遵守你得在验收标准里明确要求并且自己检查一遍。4. 贵在细节Agent 全栈开发里容易被忽略的关键点4.1 提示词工程升级到“上下文治理”前面提到第一轮提示词但全栈开发不是一轮对话能搞定的过程中 Agent 会越写越长超过上下文窗口之后就出现“前面讲了后面忘”的失忆症状。我这次的经验是不要把希望寄托在“对话无限长”上而是要给 Agent 一个可随时翻看的“项目约定文档”。做法很简单。在项目根目录放一个AGENTS.md或者PROJECT_SPEC.md里面写清楚项目定位、技术栈、目录结构、命名规范、通用约束、需要避免的事。每次开新会话或者 Agent 开始跑偏的时候就把这个文件的内容重新喂一遍。这比你在对话里反反复复强调管用得多因为它相当于给 Agent 一个永不丢失的长期记忆。我这次写的约定文档大致包含前端组件放在src/components、API 请求统一走src/api、后端路由按资源分模块、所有时间字段用 UTC 存储、数据库表名一律用复数、错误信息必须返回结构化 JSON 而不是纯文本。这些规则看起来琐碎但全栈项目最怕的就是代码风格分裂、目录混乱有了约定文档Agent 生成的代码就像同一个人的手笔。4.2 AI 生成代码的审查清单AI 生成的代码可以快但不能盲信。我给自己定了一条硬规矩凡是 Agent 生成的代码合入之前必须过一遍审查清单一个点都不能跳。第一个点是权限校验。凡是涉及“当前用户”的操作有没有在接口级别校验身份和归属这个点最容易漏因为 Agent 写 CRUD 的时候默认“能查到就能改”不会主动想权限边界。第二个点是输入校验。所有用户传递的参数有没有做类型检查和长度限制SQL 有没有走参数绑定而不是拼字符串第三个点是密钥管理。代码里有没有硬编码密钥.env 文件有没有被 Git 忽略第四个点是依赖锁定。项目里有没有锁文件保证每次安装的版本一致第五个点是错误处理。接口报错时会不会把底层异常信息直接抛给前端暴露数据库结构或者内部实现这些审查条目用脑子硬记容易漏建议做成一个 checklist 文件每次代码审查时打开照着过。我这次从 Agent 生成的第一版代码里就抓到了权限校验缺失的问题靠人工点击测试根本不容易发现。这不是 Agent 能力不行而是它默认的“代码正确”只到“语法对、逻辑通”的层面“业务安全”必须人来做判断。4.3 让 AI 自己给自己找茬最后一条细节是关于测试策略的。很多人的习惯是功能写完再补测试但我建议你把顺序反过来先让 Agent 写测试再让 Agent 写实现。这听起来有点违反直觉但在 Agent 开发流程里特别有效因为测试用例本质上是把需求翻译成“可验证的验收标准”有了验收标准Agent 写实现的时候反而更不容易跑偏。 我这次虽然没有走完整的 TDD但在几个核心接口上采用了类似的思路把预期的输入、输出、异常场景写成参数化的测试用例然后让 Agent 按测试用例去实现接口。结果就是那些“未登录访问返回 401”“越权修改返回 403”之类的边界行为在第一次生成时就已经被固定下来了后期回归测试也顺手覆盖到了。不要小看这一条AI 生成的代码最大的隐患不是“不会写”而是“写得太表面”——正常路径永远通异常路径永远炸。靠测试用例把边界钉死等于在 Agent 的想象力之外加了一堵护栏。5. 常见问题与排查技巧实录5.1 一分钟速查表这次实操虽然没有出现完全失控的状况但中途也确实遇到过几次卡壳。我把这些问题整理成一张速查表你们遇到类似情况可以直接对症下药。现象根因解法Agent 生成到一半开始跑偏、忽略前面的要求上下文超限或信息丢失重新读取项目约定文档把需求拆成小任务一次只做一件事生成的代码用了不存在的 API对特定库版本的记忆错误在提示词里明确“使用 xxx 主版本配置以官方文档为准”生成后核对官方文档反复报错但修不好陷入局部错误循环让它先写最小复现或者人肉定位到具体报错行再交给它精准修改数据库字段改了但前端编译报错前后端字段没有同步让 Agent 同时梳理前端类型定义和后端模型统一输出版本再一次性同步修改生成的界面丑得没法看默认样式就是朴素风给它参考布局描述或截图要求使用具体组件库主题并做一轮视觉微调Agent 突然提出要加“更完善”的功能误把范围扩大当加分项坚定回到功能清单明确“不在清单内的一律不做”5.2 三个典型坑的复盘第一个坑是“越写越乱的失控感”。当时做到中段我连续让 Agent 加了几个字段又调整了两处页面结构它开始改一处坏两处而且改 A 的时候不小心把 B 的老逻辑换掉了。后来我意识到问题在于我没有及时做版本管理。每个功能点完成之后应该立刻提交一次 Git让 Agent 在一个干净的基线上继续工作。它如果改坏了我可以随时回滚再给它看 diff 让它恢复。没有版本管理的 Agent 开发就像在沙子上盖楼越到后面越慌。第二个坑是“版本不匹配导致的慢性折磨”。Agent 默认使用它训练时接触过的某个版本但本地实际装的是另一个版本两边 API 对不上。这种问题特别隐蔽代码看起来没错一跑就报错。后来我在约定文档里明确写了“所有依赖的精确版本以 lock 文件为准不要擅自升级”情况才好转。锁文件的地位在 Agent 开发里被放大了十倍它就是你和 Agent 之间的“共同事实”。第三个坑是“报错信息贴给它之后它越改越离谱”。有一段时间遇到一个路由初始化的问题我一遍遍复制报错给它它一遍遍输出看起来很有道理其实完全没用的修改。后来我停下来手工打开了那个报错文件看到了一个函数参数顺序的问题直接让 Agent 按“把第 X 行的参数顺序改成 Y”这种精准指令去改一次就好了。这个经验是反馈给 Agent 的信息粒度越细它的修复准确率越高。你不能只给症状最好给它能定位到具体行号的线索。5.3 安全与合规自检这个环节很容易被“哇代码跑起来了”这种兴奋感掩盖但它恰恰是最不能省的。全栈应用涉及用户数据哪怕只是个人练手项目你也在收集用户的账号和阅读记录。我把这次的安全自检流程分享给你们照抄。第一密钥安全。项目里所有的 JWT 密钥、数据库密码必须走环境变量或密钥管理服务Git 提交历史里绝对不能出现明文密钥。第二权限控制。每个需要身份的接口都必须在后端校验“当前请求的用户“和”被操作的数据归属”是不是同一人不能只靠前端隐藏按钮来防。第三输入输出安全。所有用户提交的内容都要按不同类型做校验或转义防止注入和脚本攻击。第四依赖安全。定期扫描依赖有高危漏洞的版本不要因为“Agent 生成的代码能跑”就放着不升级。合规这个事儿要主动不能等出了问题再补救。AI Agent 不会替你背锅生产环境出了问题第一责任人永远是你自己。6. 关于 AI Agent 构建全栈应用我想再多说几句6.1 一次全流程下来我的真实体感这次从需求到部署完整跑下来最大的体感可以用一句话总结AI Agent 把“写代码”的体力活压缩了七八成但把“做对事情”的判断活拉满了。以前写一个全栈 Demo最花时间的是搭骨架、调接口、改样式这些手上功夫这些现在 Agent 基本都能扛。但需求怎么拆、边界怎么划、安全规则怎么定、代码质量怎么审这一整套“人的决策链”反而是整个项目真正的核心工作量。如果你以为买了一个牛逼的 Agent 工具就等于拥有了一个免费全栈团队那大概率会失望。它更像一个天赋极高但经验尚浅的协作工程师你交代得越清楚它发挥越好你放任不管它就按自己的最低标准交差。所以“2026 版 AI Agent 构建全栈应用”这个说法我觉得更准确的理解是你在用一种新的协作方式来管理软件开发负责方向的还是你本人。6.2 下一步可以怎么扩展这次做的“拾字”只是最小可用的状态如果继续往下拓展我后面想尝试的方向有三个。第一个是多 Agent 协作。让一个 Agent 专职写后端、另一个专职写前端中间通过接口文档和约定文档对齐这样并行效率更高但对编排能力的要求也上了一个台阶。第二个是把 AI 引入持续集成流程。不只是跑测试而是让 Agent 在代码提交后自动审查 diff、补测试、甚至生成变更说明把质量把关往前移。第三个是让 Agent 更深度地参与产品决策。比如把用户反馈和埋点数据喂给它让它帮助分析功能优先级和异常归因。这些都还在尝试阶段但方向已经比较明确。6.3 我的一点保留意见最后说点不太顺耳的。AI Agent 构建全栈应用的门槛确实在快速降低但不要因此就觉得人人都能造出好产品。工具可以帮你把代码写出来写不出“你为什么做这个产品”的判断也替不了你对用户的理解。好用的技术栈可能会变Agent 的版本会一轮轮更新但“清晰的目标、合理的边界、严格的验收”永远是软件项目成功的底层逻辑。我做完这个项目最大的收获不是那个能跑的应用而是彻底想通了一件事未来能拉开差距的不是谁更会用 AI而是谁更会定义问题、管理过程、对结果负责。这套本事在任何技术时代都不过时。最后再分享一个小实操技巧每次做完一个阶段让 Agent 用三句话总结“已完成、遗留项、下一阶段建议”把它贴到项目文档里。这样一来就算隔几周再翻开项目你和 Agent 都能快速找回状态。这是我这次实操里用得最顺手的一个小习惯强烈建议你也试试。