第18章：AI 原生开发（二）—— LLM Rules 与 Agent Skills 详解

大语言模型 (Large Language Model, LLM) 的训练数据里 Encore 占比远低于 Express，不"教"就会写出 Express 风味的错误代码。本章详解官方的两代解法：整份规则文件 (LLM Rules) 与按需加载的技能包 (Agent Skills)，全部配合本机真实项目的落地剖析。

一、LLM Rules：把框架约定写给 AI 看

两个入口

# 新项目：encore app create 的交互里直接选择要适配的 AI 工具
encore app create

# 存量项目：一条命令补齐
encore llm-rules init

支持的目标工具：Cursor（.cursorrules / .cursor/rules/）、Claude Code（CLAUDE.md）、VS Code、Zed、以及通用的 AGENTS.md。命令按你的选择生成对应文件，并在支持的工具上顺带写好 MCP 配置（第 19 章）。

生成的内容互相通用——官方明确说 Encore 的 CLAUDE.md 不加修改就能当 Cursor rules 用（Cursor 会从项目根或 .cursor/rules/ 拾取）。

规则文件里到底有什么（本机实拍剖析）

以本机 B2B 项目保存的官方规则全文快照为例（agent-rules/encore-framework.md，1053 行），结构是一组 XML 风格标签：

开头：人设与风格守则

<llm_info>      ——设定助手人设（官方给它起名 Corey，"Encore 出品的 AI 编码助手"）
<corey_info>    ——能力画像：默认用 Encore.ts 做后端，熟悉分布式系统/Node/React
<nodejs_style_guide>     ——只用 import 不用 require、用内置 fetch、ES6+
<typescript_style_guide> ——interface 建模、内置工具类型优先、避免 any

主体：<encore_ts_domain_knowledge> 按主题分节的压缩版官方文档，每节 = 语法说明 + 最小可用示例：

也就是说：这份文件 ≈ 本教程第 3–16 章的机器可读版。它的价值是离线兜底——没有联网检索、没有 MCP 时，AI 也能按正确语法写 Encore 代码。

整份 Rules 的固有问题

1000+ 行全文常驻上下文，每轮对话都付 token 成本，且大部分内容与当前任务无关——写数据库迁移时不需要 streaming_apis 那 50 行。这个问题引出第二代方案。

二、Agent Skills：从"全文常驻"到"按需触发"

机制

Agent Skills（智能体技能）把整份规则拆成主题化技能包：每个技能一个 SKILL.md，frontmatter 里的元信息常驻（几行），正文只在任务匹配时才被智能体加载。这是 Claude Code / Cursor 等工具当前的通用技能机制，Encore 官方把自家领域知识全部按此打包。

安装

基于开源分发器 add-skill，从 GitHub 仓库 encoredev/skills 安装：

# 交互式：自动探测你在用的 AI 工具
npx add-skill encoredev/skills

# 查看全部可用技能
npx add-skill encoredev/skills --list

# 只装指定技能
npx add-skill encoredev/skills --skill encore-api --skill encore-database

# 指定目标智能体（可多个）
npx add-skill encoredev/skills -a cursor -a claude-code

# 全局安装（对所有项目生效）
npx add-skill encoredev/skills -g

支持 Cursor、Claude Code、Codex、OpenCode 等十余种智能体。Claude Code 也可走插件市场：

claude plugin marketplace add encoredev/skills
claude plugin install encore-skills@encore-skills

TypeScript 技能全清单（15 个）

另有 13 个 go- 前缀的 Go 版，本教程不涉及。

SKILL.md 解剖（以 encore-api 为例，本机实拍 272 行）

---
name: encore-api
description: Define typed API endpoints in Encore.ts using `api(...)` from
  `encore.dev/api`. Covers typed request/response interfaces, path/query/header/
  cookie params, request validation, and `APIError`. For raw endpoints
  (`api.raw()`) and inbound webhooks, use `encore-webhook` instead.
when_to_use: >-
  User wants to define an endpoint, route, or REST handler in their own
  service — anything with a typed JSON request/response shape. ...
  Trigger phrases: "POST endpoint at /orders", "typed endpoint",
  "GET /users/:id", "request validation", "return 404", ...
---

三个设计点值得注意：

1. description + when_to_use 是触发器：平时只有这几行进上下文，智能体据此判断"当前任务要不要加载这份技能"——when_to_use 甚至列出了触发短语；
2. 技能之间互相引路：encore-api 的 description 明确说"raw 端点和 webhook 去用 encore-webhook"——防止智能体加载错知识；
3. 正文 = 该主题的完整操作手册：API 四种签名、选项表、校验器表、错误码表、api.static 语法，最后一节 Guidelines 给出硬规则（"永远抛 APIError 而不是返回错误对象"等）。

版本管理

安装后项目根多一个 skills-lock.json，锁定每个技能的来源仓库、路径与内容哈希：

{
  "version": 1,
  "skills": {
    "encore-api": {
      "source": "encoredev/skills",
      "sourceType": "github",
      "skillPath": "encore/api/SKILL.md",
      "computedHash": "5744aa5a…"
    }
  }
}

升级：npx skills update（在项目根执行，按 lock 文件对齐远端最新版）。

三、本机项目的落地策略（可直接抄）

encore.ts.ticketBookingB2B（Encore.ts + Vue3 的真实业务项目）的四条实践：

1. 精选安装而非全量：只装了 8 个与项目相关的技能（api / auth / code-review / database / frontend / secret / service / testing）——不用 pubsub、cron、cache 就不装，少占触发判断的注意力；
2. 自定义技能与官方技能同机制并存：.claude/skills/deploy-selfhost/ 是自写的发版操作手册技能，复用同一套 frontmatter 触发机制——官方技能的格式就是你写团队技能的模板；
3. 整份 Rules 降级为离线兜底：agent-rules/encore-framework.md 保留在仓库，但项目 CLAUDE.md 里明确标注"仅作离线兜底，勿再默认通读"——框架细节以 skills 按需触发为准；
4. 项目 CLAUDE.md 只写项目的事：业务口径、踩坑硬规则、目录导读；框架知识全部外包给 skills。两层职责分明：CLAUDE.md 回答"这个项目怎么回事"，skills 回答"Encore 怎么写"。

这套分层的效果：常驻上下文最小化，而任何时刻智能体需要的知识都在两跳之内（触发技能或读兜底文件）。

四、常见误区

1. 不装任何 Rules/Skills 就让 AI 写 Encore——得到 Express 风味的幻觉代码（require、手写路由注册、忘 encore.service.ts）。
2. Rules 与 Skills 全都装且全文常驻——重复且浪费上下文；选一个为主（新项目直接 Skills），Rules 做兜底。
3. 全量安装 15 个技能"图省事"——触发判断也有成本，按项目用到的原语精选。
4. 把业务规则写进技能、把框架语法写进项目 CLAUDE.md——两层倒挂，维护混乱。
5. 手改安装到本地的 SKILL.md——skills update 会覆盖；定制走自建技能。
6. 忘了 skills-lock.json 提交进 git——团队成员装出不同版本的技能。

五、实践练习

1. 在任一 Encore 项目跑 encore llm-rules init，读一遍生成的规则文件，对照本章第一节的结构表逐段辨认。
2. npx add-skill encoredev/skills --list 看全清单，按你的项目实际用到的原语精选安装 5–8 个。
3. 打开安装后的 encore-database/SKILL.md，把 frontmatter 的 when_to_use 触发短语翻译成中文，体会触发器设计。
4. 仿照官方格式给自己的项目写一个技能（如"本项目发版流程"或"上游接口对接规范"），验证智能体能按 description 触发。
5. 对比实验：同一个"加一个带校验的订单查询端点"任务，分别在裸环境与装好 skills 的环境让 AI 做一遍，数一数第一遍里不符合 Encore 约定的地方。

六、总结

1. LLM Rules 是第一代方案：encore llm-rules init 生成 CLAUDE.md/.cursorrules 等，内容≈整部框架手册的机器可读版（本机实拍 1053 行、30 余节），价值在离线兜底。
2. Agent Skills 是第二代：15 个 TS 技能按主题拆分，frontmatter 触发、正文按需加载，npx add-skill encoredev/skills 一键安装、skills-lock.json 锁版本。
3. SKILL.md 三设计：description+when_to_use 当触发器、技能间互相引路、正文含硬规则 Guidelines。
4. 落地四原则：精选安装、自定义技能同机制、Rules 降兜底、项目 CLAUDE.md 只写业务。
5. 官方技能格式就是你写团队技能的最佳模板。

请继续阅读：第19章:AI 原生开发（三）MCP Server。

原始资料引用

• Using Encore with AI Tools
• GitHub: encoredev/skills
• 本机实拍：encore.ts.ticketBookingB2B/agent-rules/encore-framework.md、.claude/skills/*/SKILL.md、skills-lock.json

Related Documents

• 第17章:AI 原生开发（一）
• 第19章:AI 原生开发（三）