Wasp 的 AGENTS.md 详解每个 Wasp 项目内置的 AI Agent 工作规范以 waspello 示例为例【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp在 Wasp 生态中AGENTS.md是一个专门写给 AI 编码助手Coding Agent看的项目说明文件它告诉 Agent 去哪找对版本的文档、如何写 Wasp TypeScript Spec、新检出项目后按什么顺序初始化以及用什么命令验证改动是否有效。本文以 Wasp 官方示例 waspello一个 Trello 风格的看板应用中的 AGENTS.md 为主体结合仓库内的实际源码与 CLI 模板逐条解析这份文件的每一条规则并说明这些规则背后的工程依据帮助你在自己的 Wasp 项目中建立一套可被 Agent 直接执行的开发工作流。需要先指出一个重要的仓库事实examples/waspello/AGENTS.md并不是 waspello 独有的手写文件而是一个符号链接指向 Wasp CLIwaspc骨架项目模板中的 AGENTS.md。也就是说这份文件是随 Wasp 脚手架一起分发的“标准答案”——你用 CLI 新建的任何 Wasp 项目都会自带这套 Agent 工作规范。同目录下的CLAUDE.md又是指向AGENTS.md的符号链接意味着同一份规则同时服务于通用 Agent 约定AGENTS.md 规范和 Claude Code 的专属读取路径CLAUDE.md。一、文档检索规则先看main.wasp.ts的版本再查版本化文档AGENTS.md的第一组规则是“Docs”文档检索共四条核心目的是防止 Agent 拿错版本的文档来改代码文档索引入口从官方文档的llms.txt索引开始查起即 Wasp 官网根目录下的llms.txt。这个索引文件的完整内容在仓库中也有快照见 web/markdown-snapshots/llms.txt它按版本列出了各个文档地图docs map例如“Next (latest)”以及0.25到0.11.8的各历史版本。按项目锁定版本选择与main.wasp.ts中 Wasp 版本一致的文档地图。以 waspello 为例其 main.wasp.ts 中声明为export default app({ name: waspello, wasp: { version: 0.26.0 }, // ... });Agent 必须依据wasp: { version: 0.26.0 }这一行来决定查哪个版本的文档而不是默认查最新版。优先使用文档地图里的原始 Markdown URL文档地图中提供的是可直接抓取的纯 Markdown 地址快照中可以看到llms-current.txt、llms-{version}.txt这类地图文件以及llms-full-{version}.txt全量拼接文件而不是让 Agent 去猜wasp.sh/docs下的路由路径。这降低了 Agent 因 URL 结构变化而 404 的概率。冲突时的裁决规则“如果本文件AGENTS.md与版本化的 Wasp 官方文档冲突以官方文档为准并告知用户本文件可能已过时。”这条把 AGENTS.md 定位为“可能滞后的项目级提示”而把版本化官方文档定为最终事实来源single source of truth避免 Agent 固执地执行过时的项目备忘。这四条规则合起来构成一条检索链llms.txt 索引 → 按 main.wasp.ts 版本选地图 → 取原始 Markdown → 冲突时以官方文档为准。二、Wasp TypeScript Spec 编写规则ref导入与构造函数命名约定AGENTS.md的第二组规则是全文技术含量最高的部分——“Wasp TypeScript Spec”它约束 Agent 如何编写 Wasp 0.25 引入的 TypeScript 规格TS Spec。四条规则及在 waspello 中的对应实证如下。1.main.wasp.ts同时承载版本号与 App 规格规则原文“main.wasp.tscontains the Wasp version and the Wasp app specification.”main.wasp.ts包含 Wasp 版本与 Wasp 应用规格。waspello 的 main.wasp.ts 完整展示了这种结构app({ ... })调用里既声明了wasp: { version: 0.26.0 }又通过spec数组声明了路由与功能模块export default app({ name: waspello, wasp: { version: 0.26.0 }, title: (await readFile(appTitle.txt, utf-8)).trim(), auth: { userEntity: User, methods: { usernameAndPassword: {}, google: {} }, onAuthFailedRedirectTo: /login, }, client: { rootComponent: Layout }, spec: [ route(MainRoute, /, page(MainPage, { authRequired: true })), authSpec, cardsSpec, ], });这里authSpec、cardsSpec是各自模块文件导出的规格片段最后拼进主spec数组。2. 引用src/中的组件/函数必须加with { type: ref }规则原文“When it references app components/functions, import them fromsrc/withwith { type: ref }.”在 TS Spec 中main.wasp.ts处于“规格世界”普通import会把真实模块加载进规格上下文而 Wasp 需要的是对这些符号的“引用”。waspello 的实证代码main.wasp.tsimport MainPage from ./src/cards/MainPage with { type: ref }; import Layout from ./src/Layout with { type: ref };with { type: ref }是 ES 模块的 import attributes 语法Wasp 用它标记“这是一个指向 src/ 实现的引用而非直接执行”。模块内同理src/cards/cards.wasp.ts 用同样的方式引用./cards与./lists里的普通 TypeScript 函数createCard、getListsAndCards等。Agent 写新代码时若漏掉这个属性spec 的引用语义就会错乱。3.route/crud需要显式命名其余构造函数用声明名规则原文区分了两类构造函数route(name, ...)和crud(name, ...)显式传入名字其余构造函数不接收名字参数实体的名字就是声明时绑定的导入标识符。例如job(sendReminder, { ... })声明的 job 就叫sendReminder。waspello 中的route用法印证了前者route(MainRoute, /, page(MainPage, { authRequired: true }))中MainRoute是显式路由名/是路径第三个参数是带authRequired: true的页面声明——未登录访问会按onAuthFailedRedirectTo: /login重定向到登录页。而 src/cards/cards.wasp.ts 里的query/action就属于“不传名字”的一类export const cardsSpec: Spec [ query(getListsAndCards, { entities: [List, Card] }), action(createList, { entities: [List] }), action(updateList, { entities: [List] }), action(deleteList, { entities: [List, Card] }), action(createListCopy, { entities: [List, Card] }), action(createCard, { entities: [Card] }), action(updateCard, { entities: [Card] }), ];每个action的名字即其导入的函数标识符如createCardentities选项则声明了该 mutation 会变更哪些实体——这正是 README 中所说的“查询在变更时失效、实现实时刷新”的缓存失效机制的声明来源。Agent 若误以为action也需要第一个位置参数传名字就会写出非法 spec。4.wasp.sh/spec由 Wasp 生成禁止从 npm 安装规则原文“wasp.sh/specis generated by Wasp, dont install it from npm.”TS Spec 的所有构造函数app、page、route、query、action、Spec类型等都从这个模块导入。它在wasp install/ 编译流程中生成到本地waspello 的 tsconfig.wasp.json 将.wasp/out/types/spec纳入includenoEmit: true表明它只做类型检查不做产物输出。这条规则防止 Agent 尝试npm install wasp.sh/spec或把它写进package.json依赖——那是不会成立的路径正确做法是确保生成功程已运行。三、Fresh checkout 初始化序列install → env → migrate-dev → 视情况 seedAGENTS.md的第三组规则定义了在一个全新克隆或 git worktree里按顺序执行的初始化清单先运行wasp install在任何其他 Wasp 命令之前。这一步安装/同步 Wasp 依赖与生成物包括上面的wasp.sh/spec是后续 spec 类型检查与编译的前提。waspello 的 README.md 同样强调 “Runwasp installbefore using the project”。准备.env.server与.env.client从项目的 example 文件或 README 复制。waspello 的对应文件是 .env.server.example内含GOOGLE_CLIENT_SECRET、GOOGLE_CLIENT_ID两个 Google OAuth 的占位值因为main.wasp.ts的auth.methods启用了google: {}项目 README 的 “Env variables” 一节也说明要 “Copyenv.serverto.env.serverand fill in the values”。真实的.env.*被 .gitignore 默认忽略!.env.*.example白名单只放行示例文件所以新检出不可能自带这些文件必须手动创建。运行wasp db migrate-dev应用数据库迁移然后查看项目 README 确认是否需要 seed。waspello 有 migrations/ 目录含new_auth等迁移但 README 没有提及 seed 步骤所以按规则结论是此项目只需 migrate不需 seed。这条“去看 README 判断”的写法是刻意的——AGENTS.md 是跨项目模板它不能写死每个项目是否要 seed于是把决策依据指向项目自己的 README。数据库本身依赖 Postgres 运行。waspello README 给出的最省事方式是一个终端里wasp start db用 Docker 起本地 PostgreSQL另一个终端里wasp db migrate-dev。注意规则特意写了 “fresh cloneor worktree”——wasp install的生成物在.wasp/下且被 git 忽略见 .gitignore 的.wasp/每个新 worktree 都是“裸”的因此多 worktree 的 Agent 工作流里每开一个 worktree 都要重跑一遍该序列。四、验证规则用wasp compile校验不要直接跑tscAGENTS.md最后一组“Verification”规则只有两条但非常关键运行wasp compile来检查应用是否有效不要直接运行tsc来做验证。这与 Wasp CLI 官方文档的说法一致仓库内 web/docs/general/cli.md 明确写道——“wasp compile编译你的 Wasp 项目并报告任何错误但不运行应用。它是检查项目是否有效的快速方式特别适合 CI 或 AI Agent 使用。”从源码结构看第二条禁令有其必然性TS Spec 的合法性检查spec 结构是否合法、实体引用是否存在、auth 配置是否合规等发生在 Wasp 编译器里而tsc只能做 TypeScript 语法/类型层面的检查两者覆盖范围完全不同。此外main.wasp.ts引用的wasp.sh/spec是生成模块未经wasp install生成时直接tsc只会报一堆“模块不存在”的假错误反而误导 Agent。所以对 Agent 而言正确的工作闭环是改代码 →wasp compile→ 读编译诊断而tsc的保留场景只是人类对src/下普通 TS 代码做细粒度类型检查waspello 的 tsconfig.src.json 服务于这部分与tsconfig.wasp.json分工。五、把这套规范迁移到你自己的 Wasp 项目AGENTS.md的价值在于它把“Wasp 项目的隐性开发约定”压缩成了 Agent 可直接执行的清单。如果你在自己的 Wasp 项目里定制这份文件可以遵循同样的结构Docs 段保留“按main.wasp.ts版本选文档地图”的机制因为你的项目升级 Wasp 版本时这条规则自动跟着走TS Spec 段如果项目里用到job、event等更多构造函数可像骨架模板中的job(sendReminder, { ... })示例那样为本项目高频实体补充一两个命名约定例子Fresh checkout 段把“是否需要 seed”直接改写为本项目的事实例如“本项目需要运行wasp db seed”消除 Agent 再去查 README 的歧义Verification 段原样保留wasp compile优先、禁止裸跑tsc的规则。waspello 作为完整示例恰好展示了这套规范的全部使用场景main.wasp.ts 体现版本声明与命名路由src/cards/cards.wasp.ts 体现无名字构造函数的 query/action 声明src/auth/ 下的auth.wasp.ts体现模块化 spec 片段而 README.md 与 e2e-tests/Playwright 套件npm run testCI 每个 PR 都会跑则提供了规则之外的项目级补充信息——这正是 AGENTS.md 各条规则反复引用“项目 README”的原因AGENTS.md 管通用约定README 管项目特例两者互为校验。小结waspello 项目中的 AGENTS.md实际源文件为 waspc/data/Cli/starters/skeleton/AGENTS.md是 Wasp 官方为 AI Agent 制定的四段式工作规范按main.wasp.ts锁定的版本检索原始 Markdown 文档、以with { type: ref }导入和“route/crud 显式命名、其余用声明名”的约定编写 TS Spec、按 install → env → migrate-dev → seed 顺序初始化新检出、用wasp compile而非tsc验证。它随 Wasp CLI 骨架模板分发到每个新项目配合CLAUDE.md符号链接同时覆盖通用 Agent 与 Claude Code是 Wasp 在 AI 编码时代“规范即脚手架”设计思路的一个典型样本。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考