第20章：AI 原生开发（四）—— AI 开发实战工作流
约 5 分钟 · 更新于 2026-09-02
前三章备齐了零件：友好的框架底座、Rules/Skills、MCP。本章把它们组装成日常可用的工作流——三层上下文模型、官方四条最佳实践、一个端到端开发循环，以及本机真实项目沉淀的经验与反模式清单。
一、三层上下文模型
AI 智能体在 Encore 项目里的上下文按"变化频率"分三层：
text
┌──────────────────────────────────────────────────────┐
│ 第一层 LLM Rules / 项目 CLAUDE.md │
│ "怎么写"——框架约定 + 项目硬规则（静态，常驻） │
├──────────────────────────────────────────────────────┤
│ 第二层 Agent Skills │
│ "深挖某主题"——按任务触发加载（准静态，按需） │
├──────────────────────────────────────────────────────┤
│ 第三层 MCP Server │
│ "现在什么样"——schema/trace/服务图（动态，实时） │
└──────────────────────────────────────────────────────┘
三层各司其职、缺一有各自的病症：
| 缺了谁 | 症状 |
|---|
| Rules/CLAUDE.md | Express 风味幻觉代码、违反项目硬规则（裸跑 vitest、金额单位写错） |
| Skills | 冷门原语（streaming、cache keyspace）语法靠猜 |
| MCP | 不了解现状：重复建表、字段名对不上、改坏依赖方 |
配置清单（一次性，10 分钟）：
bash
encore llm-rules init # 第一层
npx add-skill encoredev/skills --skill ... # 第二层（精选）
claude mcp add --transport stdio encore-local -- encore mcp run --app=<id> # 第三层
二、官方四条最佳实践
- 少写规定性 prompt，给探索留空间。不要替智能体指定端点名、表名、列名——让它 get_services / get_databases 自己发现。你规定得越细，它越可能与现状冲突；你给方向、它对齐现状，生成的代码反而更贴合既有约定。
- 用 trace 验证，而不是只看代码。AI 写完让它跑一遍再 get_trace_spans 自检。查错表、鉴权没执行、N+1 查询、意外的服务调用——代码评审看不出来、trace 一眼看穿。把"贴 trace 证明"写进你对 AI 的任务验收标准。
- 架构问答交给 MCP。"哪些服务依赖 payments？""谁订阅了 order-created？"——这类问题智能体秒答且必准（读的是应用模型，不是猜的）。团队新人 onboarding 也适用。
- Rules 与 MCP 组合使用。文档（约定）+ 传感器（实况），第 17 章的老话，是四条里最基础的一条。
三、端到端开发循环（标准作业流程）
以真实任务为例："给已登录用户加一个'我的订单'列表端点，支持按状态过滤"。
text
你 下达任务（说清业务意图与验收标准，不指定实现细节）
│
AI ① 发现 get_services → order 服务已有端点风格、auth 已配 Gateway
│ get_databases → orders 表真实结构（status 列是 TEXT，有索引）
│ （encore-api skill 触发 → 校验器/分页写法）
│
② 实现 写 api() 端点：auth: true + getAuthData 取 UID
│ + Query<string> 状态过滤 + 参数校验
│
③ 自验 encore test → 单测过（mock getAuthData）
│ call_endpoint → 真调一次
│ get_trace_spans → 鉴权 span 在、SQL 只扫 orders、走了索引
│
你 ④ 审查 重点看业务口径：状态枚举全不全？金额字段单位？分页边界？
│ （语法与结构框架已兜底，第 17 章三道防线）
│
⑤ 收尾 git 提交；接口变更 → encore gen client 重新生成前端 SDK
与传统 AI 辅助开发的差别集中在 ③：自验环节全部本地真实闭环——真库、真调用、真 trace，AI 的"完成"是可核查的事实而非声明。
验收话术模板
给 AI 的任务里直接附验收标准，效果显著：
完成后请：1) encore test 全绿并贴输出；2) 用 call_endpoint 真调一次并贴 trace span 摘要，证明鉴权执行且只查了 orders 表；3) 列出你改动的全部文件。
四、本机项目经验（encore.ts.ticketBookingB2B）
真实业务项目（B2B 分销预订工作台，AI 辅助开发为主）沉淀的四条：
- 测试纪律入硬规则：AI 助手默认爱裸跑 npx vitest（训练数据里的习惯），会因拿不到运行时绑定而误报失败。「测试必须 encore test，禁裸 vitest」要白纸黑字写进项目 CLAUDE.md——写了之后此类事故归零。
- 构建期约束提前告知：api.static 的目录与 notFound 文件在静态分析期就必须存在（第 3 章）。AI 在干净分支上工作时会撞上"删了前端产物就构建失败"，把这类项目特有约束写进 CLAUDE.md 免得它反复试错。
- 审查重心迁移：AI 生成基础设施代码后，评审里语法/结构问题几乎绝迹（框架兜底），错误集中在业务口径——金额分转元、上游字段语义、状态机流转。审查清单要相应改版：少看"写得对不对"，多看"理解得对不对"。
- 硬规则编号化并在代码注释引用：项目 CLAUDE.md 的踩坑规则带编号（"规则 N"），代码注释里 // CLAUDE.md 规则 7 反向引用——AI 改代码时会顺着注释找到规则原文，防止"修一处坏一处"。
五、反模式清单
- 上下文三层缺配就开工——第一节病症表对号入座。
- prompt 里替 AI 写好表结构和端点签名——与现状冲突时 AI 会硬凑，不如让它先 get_databases。
- 只验"编译过"——Encore 的编译门槛只拦结构错误；encore test + trace 才是完整验证。
- 让 AI 绕过原语——"帮我用 pg 直连查一下"这类指令会在代码里留下追踪盲区（第 12 章）；一切 I/O 走原语。
- 把生产凭据/生产数据放进本地环境——MCP 的安全模型建立在"本地即试验场"上（第 19 章），别自己拆掉。
- AI 改完不重新生成客户端——前端类型静默过期（第 15 章），把 gen client 挂进任务收尾清单。
- 用对话记忆代替项目 CLAUDE.md——"上次跟它说过了"不作数，会话是易失的，规则要落盘。
- 一次让 AI 做整个系统——按服务/按端点切任务，每个循环走完"发现→实现→自验→审查"，小步快跑。
六、给团队的落地清单
项目初始化（一次）
每个 AI 任务（循环）
每次踩坑（沉淀）
七、实践练习
- 给你的练习项目走完一遍"落地清单·项目初始化"，截图三层配置各自的生效证据。
- 用第三节的验收话术模板给 AI 下达"我的订单列表"任务，检查它交回的三件套是否齐全。
- 故意在 prompt 里指定一个与现状不符的表名，观察 AI 的行为；再改成"先查 schema 再实现"，对比结果。
- 让 AI 通过 trace 找出你埋的慢查询（pg_sleep），并要求它给出修复 + 修复后的 trace 对比。
- 把你项目里最近三次人工 review 揪出的 AI 错误归类：语法/结构 vs 业务口径，验证第四节第 3 条的比例判断。
八、总结
- 三层上下文模型：Rules/CLAUDE.md（约定）→ Skills（按需深挖）→ MCP（实时实况），缺一层有一层的病。
- 官方四实践：少规定多探索、trace 验证、架构问答走 MCP、文档+传感器组合。
- 标准循环五步：发现 → 实现 → 自验（test + call + trace）→ 人工审业务口径 → 收尾（提交 + 重新生成客户端）。
- 真实项目经验：测试纪律入规、构建期约束告知、审查重心迁移到业务、硬规则编号化。
- AI 时代 Encore 的核心价值一句话：把"AI 写的代码能不能信"从主观判断变成本地可复核的客观事实。
全书到此完结。回到 教程总览，或从 实战篇 开始动手。
原始资料引用