第17章：AI 原生开发（一）—— 为什么 Encore.ts 对 AI 友好

从本章起进入本教程的重点：用 AI 开发 Encore.ts 应用。先讲清底层逻辑——为什么这个框架天然适合 AI 智能体 (agent) 写代码；后三章分别展开三件工具：LLM Rules 与 Agent Skills（第 18 章）、MCP Server（第 19 章）、组合实战工作流（第 20 章）。

一、问题：TypeScript 生态的"选择爆炸"

让 AI 裸写一个 TypeScript 后端，它面对的第一批决策不是业务，而是架构：

• Web 框架：Express / Fastify / Hono / Koa / NestJS？
• 校验：Zod / Joi / class-validator？
• 数据库层：Prisma / Drizzle / Knex / 裸 pg？
• 项目结构、鉴权方案、配置管理、运行时……

官方博客做过一个实验：同一个 prompt 提三次，得到三套完全不同的技术栈——一次 Express + pg，一次 Fastify + Prisma，一次 Hono + Drizzle。每套都"对"，但互不一致。

这对团队意味着什么：

1. 审查成本爆炸：每次生成都要先审架构再审业务；
2. 不可积累：上周 AI 写的模块和这周的连不上；
3. 注意力错配：AI 的推理预算花在"选型"上，而不是你真正关心的业务逻辑上。

二、Encore 的答案：用约定吃掉决策

Encore.ts 把上述所有决策收敛为框架约定：

• API 只有一种写法：api(选项, 类型化函数)；
• 数据库只有一种声明：new SQLDatabase + SQL 迁移；
• 消息只有一种形态：Topic / Subscription；
• 鉴权只有一种骨架：authHandler + Gateway；
• 项目结构只有一种约定：服务 = 目录 + encore.service.ts。

关键行为差异（官方观察）：当智能体看见已有的服务结构和基础设施声明时，它"会按同样的模式追加端点，而不是另起炉灶"——决策空间收窄后，生成结果稳定、可预测、可审查。AI 从"架构师 + 码农"退回"码农"，架构由框架和你把住。

量化：少写 87% 的代码

官方对比（智能体需要生成/理解的代码量）：

代码少 87% 的复利：生成 token 少、出错面小、审查快、上下文窗口里能装下更完整的应用。

三、三道防线：AI 生成代码的容错架构

约定收敛解决"写得散"，Encore 还有三道机制兜住"写得错"：

防线一：编译期——静态分析当门卫

"Any deviation is caught as a compilation error."

AI 幻觉出的 API 形态、引用不存在的数据库、忘了服务声明——活不过 encore run。传统栈里这些问题要等运行时甚至上线后才炸；Encore 把反馈周期压缩到秒级，而"快速失败 + 明确报错"恰好是 AI 迭代循环最吃的补给（报错信息直接喂回去就能自修）。

防线二：运行时——Rust 层校验兜底

AI 忘写参数校验？请求还是要过 Rust 层的类型 schema 校验（第 4 章）——缺字段、错类型的请求进不了业务代码。校验不再依赖"AI 记得写"，而是框架强制。

防线三：验证闭环——真实基础设施可自测

encore run 拉起的是真 Postgres、真消息队列（第 2 章），encore test 提供隔离测试库（第 15 章）。于是 AI 的"我写完了"可以立即变成可核查的事实：

AI 写代码 → encore run 编译过 → encore test 测试过 → 真实调用 → trace 验证

对比之下，裸栈的 AI 工作流通常止步于"编译过"——数据库是 mock 的、队列是假的，"看起来对"与"真的对"之间没有桥。

四、内置 AI 工具三件套总览

在天然友好的地基上，Encore 提供三件显式的 AI 工具，分工正交：

┌────────────────────────────────────────────────────┐
│ LLM Rules       "怎么写"     框架约定与语法（静态）  │ → 第 18 章
├────────────────────────────────────────────────────┤
│ Agent Skills    "领域深挖"   按任务加载的知识（按需）│ → 第 18 章
├────────────────────────────────────────────────────┤
│ MCP Server      "现在什么样"  运行中应用实况（实时）  │ → 第 19 章
└────────────────────────────────────────────────────┘

• LLM Rules：随框架发布的规则文件（CLAUDE.md / .cursorrules），教会智能体 Encore 语法与约定——弥补训练数据里 Encore 占比低的问题；
• Agent Skills：把规则拆成主题化技能包，智能体按任务触发加载，不占常驻上下文；
• MCP Server：模型上下文协议 (Model Context Protocol, MCP) 服务器，内置在 CLI 里，把应用模型 + 运行实况（schema、trace、服务图）开放给 AI 工具。

一个对照记忆：Rules/Skills 是文档（告诉 AI 世界应该什么样），MCP 是传感器（告诉 AI 世界现在什么样）。两者缺一：只有文档，AI 不了解你的现状；只有传感器，AI 不懂框架写法。

五、AI 调试的质变：从"读代码猜"到"看运行事实"

传统 AI 辅助调试的天花板是"把代码贴给它猜"。Encore 的可观测体系给了 AI 新的证据来源——官方博客的真实案例：智能体通过 trace 发现 email.sendReceipt 在下单响应路径上同步阻塞 2.8 秒，建议改成 Pub/Sub 异步处理，响应时间改善约 8 倍。

这类问题（同步阻塞、N+1 查询、鉴权没执行、查错表）在代码评审里很难看出来，在 trace 里一眼看穿。第 19、20 章会把"用 trace 验证 AI 代码"发展成标准工作流。

六、冷静的另一面：AI + Encore 的边界

1. 业务口径 AI 不懂：金额分转元、状态机流转、上游契约字段——这些错误三道防线都拦不住，仍是人工审查重点（本机 B2B 项目的经验：AI 生成基础设施代码后，审查重心恰恰从语法转移到了业务口径）；
2. 训练数据劣势真实存在：不装 Rules/Skills 时，AI 会把 Express 习惯带进来（如 app.use 思维、require 导入）——所以第 18 章的配置不是可选项；
3. 约定之外的自由度仍需人把关：服务怎么拆、事件怎么设计，框架不替你决定，AI 给的方案要过第 6、7 章的决策表。

七、常见误区

1. "Encore 对 AI 友好 = 不用配置直接让 AI 写"——不装 Rules/Skills 的 AI 仍会写出 Express 风味的错误代码。
2. 把 87% 的数字当营销词——它的本质是"框架吃掉的样板代码不需要 AI 生成"，可以在自己的项目里复算。
3. 认为三道防线能拦业务错误——防线管结构与语法，业务口径靠测试与人审。
4. 只用 MCP 不配 Rules（或反过来）——文档与传感器缺一不可。
5. 用"AI 写得快"论证跳过测试——恰恰相反，AI 时代 encore test 闭环是把关成本最低的一环。

八、实践练习

1. 做官方同款实验：给任意 AI 助手同一个"写一个订单 API + Postgres"的 prompt 跑三次（不提 Encore），对比三次的框架/校验/DB 选型——亲眼看看选择爆炸。
2. 再让它用 Encore.ts 写同一需求（贴上第 3、5 章的示例做参照），对比生成代码的行数与稳定性。
3. 拿第 14 章的 uptime 项目，故意让 AI 写一个引用不存在数据库的端点，观察 encore run 的报错，把报错喂回 AI 看它能否自修。
4. 复算 87%：统计你手头任一 Express/NestJS 服务里"框架样板"（路由注册、校验、DB 连接、日志、追踪接入）占总行数的比例。

九、总结

1. 裸 TypeScript 的选择爆炸让 AI 每次都重新发明架构；Encore 用约定收敛决策空间，AI 输出变得稳定可审查。
2. 官方量化：典型后端功能约减少 87% 的生成代码。
3. 三道防线：编译期静态分析、运行时 Rust 校验、真实基础设施的自测闭环。
4. 三件套分工：Rules 教约定（静态）、Skills 供深挖（按需）、MCP 给实况（实时）——文档 + 传感器缺一不可。
5. AI 不懂业务口径；防线之外的审查重心从语法转向业务。

请继续阅读：第18章:AI 原生开发（二）LLM Rules 与 Agent Skills。

原始资料引用

• How AI Agents Want to Write TypeScript（官方博客）
• Using Encore with AI Tools
• How to Deploy AI-Generated Code to Production

Related Documents

• 第16章:部署
• 第18章:AI 原生开发（二）