better-auth-best-practices

better-auth-best-practices 技能概览

better-auth-best-practices 是一份很实用的 Better Auth 集成落地指南，特别适合那些不满足于泛泛一句“加个 auth”提示、而是希望把 Better Auth 真正接对、配好的场景。对于在 TypeScript 应用里使用 Better Auth 的开发者来说，它尤其有价值：能帮助你梳理初始配置、auth.ts 放置位置、环境变量、数据库适配器、路由接线、migrations、sessions，以及带插件场景下的配置要点。

这个技能真正解决什么问题

当你的目标是让 Better Auth 集成尽量少踩可避免的坑时，就该用 better-auth-best-practices。它最擅长把“帮我在应用里接入 Better Auth”这种模糊需求，转成更完整、可执行的实施方案，明确安装步骤、文件预期位置，以及该怎么做校验。

最适合哪些用户

这个技能适合：

• 正在给新项目或现有项目接入 Better Auth 的开发者
• 需要处理 auth.ts、adapters、sessions、plugins 或 env 配置的 AI agents / 助手
• 想在参考官方示例前，先获得一个更稳妥起点的团队

如果你已经清楚自己使用的 framework 和 database，但需要一条可靠的 Better Auth 上手路径，这个技能尤其好用。

它和普通提示词有什么不同

普通提示词也许能生成“看起来像样”的认证代码，但经常会漏掉 Better Auth 特有的关键细节。better-auth-best-practices skill 提供的是基于仓库内容整理出的实操指引，重点包括：

• 必需的 env 变量，例如 BETTER_AUTH_SECRET 和 BETTER_AUTH_URL
• CLI 会去哪里查找 auth.ts
• 什么时候该运行 migration 或 schema generation 命令
• plugin 变更后需要重新执行 CLI 步骤
• 安装完成后可用 GET /api/auth/ok 做一个简单健康检查

因此，相比宽泛的“帮我做个登录系统”，它更适合安装决策和排障场景。

它不能替代什么

这个技能不能替代实时更新的 Better Auth 官方文档。仓库本身就明确建议用户前往 https://better-auth.com/docs 查看最新代码示例和 API 变更。更合适的用法是：把它当成 setup 加速器和决策辅助，再去对照官方文档确认 framework 相关实现。

核心采用判断

如果你希望获得带有真实落地细节的 Better Auth 专项 setup 指导，就值得安装 better-auth-best-practices。如果你需要的是完整 framework starter、生产级安全审计，或超出 Better Auth 初始集成范围的复杂授权架构，那它就不是你的主要解决方案。

如何使用 better-auth-best-practices 技能

安装 better-auth-best-practices 技能

使用以下命令安装：

npx skills add https://github.com/better-auth/skills --skill best-practices

这会从 better-auth/skills 仓库中添加 better-auth-best-practices 指南。

先看对的源文件

这个技能内容很精简。优先看：

• better-auth/best-practices/SKILL.md

这个技能目录下没有额外的 references/、rules/ 或辅助脚本，因此几乎所有可用信息都集中在这一个文件里。

先准备好它所需的最低安装上下文

在调用这个技能前，先整理好这些输入：

• framework 或 runtime
• database 选择及对应 adapter
• 你要用 email/password、OAuth，还是两者都要
• auth handlers 预期使用的 route path
• 是否需要 plugins
• auth.ts 在你的 repo 里应该放在哪里

如果没有这些信息，输出通常会停留在过于泛化的层面。

从 Better Auth 内建工作流开始

仓库给出了一套很直接的顺序：

1. npm install better-auth
2. 设置 BETTER_AUTH_SECRET 和 BETTER_AUTH_URL
3. 创建带 database 和 config 的 auth.ts
4. 创建 framework route handler
5. 运行 npx @better-auth/cli@latest migrate
6. 用 GET /api/auth/ok 验证

如果你的提示里没有这些检查点，最好明确要求模型按这个结构组织答案。

根据你的方案使用正确的 CLI 命令

这个技能特别强调了一个很关键的区别：

• npx @better-auth/cli@latest migrate：用于内建 adapter 流程
• npx @better-auth/cli@latest generate：用于 Prisma 或 Drizzle 的 schema generation

这点非常重要，因为“运行 Better Auth CLI”这种说法太模糊了。如果你使用的是 Prisma 或 Drizzle，一定要在提示里明确写出来，这样输出才会使用 generate，而不是默认给你 migrate。

明确说明 auth.ts 文件位置

Better Auth CLI 会在以下位置查找 auth.ts：

• ./
• ./lib
• ./utils
• ./src 下的路径

如果你的项目用的是自定义位置，就要明确告诉 agent 使用 --config。这是接入阶段最常见的阻碍之一：代码看起来没问题，但 CLI 仍然找不到配置文件。

在提示中写清环境变量决策

这个技能点名了两个关键变量：

• BETTER_AUTH_SECRET
• BETTER_AUTH_URL

它还特别说明：只有在这些 env 变量未设置时，才应该在 config 里定义 baseURL 或 secret。这个细节可以避免重复配置或配置冲突。想让输出质量更高，建议在提示中补充：

• 本地和生产环境各自的 base URL
• secrets 如何管理
• 使用的是 .env.local、平台 secrets，还是 Docker env

把模糊请求改写成高质量的 better-auth-best-practices 提示

弱提示：

• “Set up Better Auth for my app”

更强的提示：

• “Use the better-auth-best-practices skill to set up Better Auth in a Next.js TypeScript app with PostgreSQL and Drizzle. Put auth.ts under src/lib. We need email/password now and Google OAuth later. Show required env vars, route handler placement, whether to run generate or migrate, and how to verify setup with /api/auth/ok.”

为什么这样更有效：

• framework 清楚
• adapter 路径清楚
• 文件位置清楚
• 认证方式清楚
• CLI 选择没有歧义
• 验证步骤被明确纳入

要求按实施顺序输出

想把 better-auth-best-practices 用好，最好要求答案按下面的顺序给出：

1. 要安装的 packages
2. env 变量
3. auth.ts
4. route handler
5. migration 或 schema 命令
6. plugin additions
7. 验证步骤
8. 可能的失败点

这种结构最符合这个技能的优势，也能减少来回追问。

使用带 plugin 感知的提示

这个技能明确提醒：添加或修改 plugins 之后，要重新运行 CLI。如果你的方案依赖 plugins，最好一开始就把这个要求写进提示里。否则模型可能只给出一个看似正确的核心配置，却漏掉 plugins 带来的 schema 或 migration 更新。

在扩大范围前先验证集成

不要刚装完就直接跳到完整 UI 流程。先确认：

• env 变量已正确加载
• auth.ts 可以被发现
• CLI 已成功执行
• GET /api/auth/ok 返回 { status: "ok" }

这是最能提升安装成功率的实用检查点。

面向 Access Control 的 better-auth-best-practices 最佳工作流

对于 better-auth-best-practices for Access Control，建议先用这个技能把认证基础搭起来，再在其上叠加授权要求。一个比较好的提示写法是：

• “Set up Better Auth first, then show where role or permission checks should be attached in route handlers, session handling, or plugin config. Separate what Better Auth config handles from what app-level access control must enforce.”

这样可以避免模型夸大 Better Auth setup 的能力，好像只要配好它就自动解决了所有授权逻辑。

better-auth-best-practices 技能常见问题

这个技能适合第一次安装 Better Auth 吗？

适合。它在首次安装阶段最有价值，因为它覆盖了人们最常漏掉的反复性 setup 决策：env 变量、文件放置位置、CLI 用法，以及验证方式。如果你的集成已经很稳定，只是偶尔查一个很小的 API 细节，那它的价值就没那么高了。

不看文档，只用 better-auth-best-practices 够吗？

不够。仓库本身就说明应该去看 better-auth.com/docs 获取最新示例和 API 细节。更合适的方式是：先用这个技能提高 setup 质量、减少猜测，再去文档核对具体实现。

什么情况下它比普通 AI 提示更好？

当任务本身高度依赖 Better Auth，且对安装细节敏感时，它会明显更好。通用提示词可能会漏掉：

• BETTER_AUTH_SECRET 的长度预期
• BETTER_AUTH_URL
• auth.ts 的查找路径
• generate 和 migrate 的区别
• plugin 变更后需要重新执行 CLI 步骤

better-auth-best-practices 指南是 framework 专属的吗？

不完全是。它提供的是一套可迁移的 Better Auth 工作流，但你仍然需要结合官方文档或自己的应用上下文，补齐 framework 专属的 route 和 handler 代码。如果你没有说明自己使用哪个 framework，得到的建议通常会更宽泛。

初学者能用 better-auth-best-practices 技能吗？

可以，但初学者往往需要提供比自己想象中更多的上下文。至少要写明 framework、database，以及想要的登录方式。否则输出可能在技术上没错，却不能直接运行。

它能端到端覆盖 Access Control 吗？

不能单独完成。better-auth-best-practices for Access Control 适合用来建立 auth setup 基础，并指出授权关注点应该接在哪里，但应用层的 permission rules、受保护路由以及 enforcement strategy，仍然需要你自己定义。

什么情况下不该使用这个技能？

以下情况可以跳过：

• 你并没有使用 Better Auth
• 你只是想从文档里找一个非常具体的 API 示例
• 你需要完整的生产级安全审计
• 你的核心问题是应用授权设计，而不是 Better Auth 安装

如何改进 better-auth-best-practices 技能的使用效果

给技能提供具体的项目信息

想更快拿到高质量输出，最有效的方法是直接提供：

• framework
• runtime
• database 和 ORM
• auth.ts 位置
• 登录方式
• plugin 列表
• 部署环境

当这些信息明确后，better-auth-best-practices 技能会变得更加可执行。

提前要求它处理高概率失败点

一个强提示通常会包含：

• “List the top setup mistakes for this stack”
• “Tell me if the CLI will fail to find auth.ts”
• “Say whether I should use generate or migrate and why”
• “Show how env vars override config values”

相比只让它输出代码，这类问题更能产出有价值的安装指导。

不只要代码，也要验证方法

很多糟糕的 auth 输出看起来很完整，但实际上没有经过验证。建议要求模型补充：

• GET /api/auth/ok 的预期结果
• CLI 命令成功后应该看到什么
• route 失败时要检查哪些地方
• 添加 plugins 后哪些内容需要重新确认

相比单纯索要更长的代码示例，这样更能提升首轮答案的可用性。

改进面向 Access Control 的 better-auth-best-practices 提示

如果你的目标还包含授权，最好在请求里把关注点拆开：

• “Part 1: Better Auth installation”
• “Part 2: session shape and claims”
• “Part 3: app-level route protection and permission checks”

这样可以避免回答把 setup 步骤和业务特定的访问控制逻辑混在一起。

在第一轮答案后继续迭代

拿到第一版后，可以继续用更具体的补充要求细化，例如：

• “Rewrite for Prisma instead of built-in adapter”
• “Move auth.ts to src/utils”
• “Add plugin changes and tell me which CLI command to re-run”
• “Adapt this to production env handling”

这个技能最适合响应明确调整，不适合那种笼统的“帮我优化一下”。

留意几个主要失败模式

最常见的低质量输出包括：

• 缺少 env 变量
• 文件路径假设错误
• 针对 adapter stack 使用了错误的 CLI 命令
• 没提到 plugin 变更后要重新执行 CLI
• setup 完成后没有验证步骤

如果答案里缺了这些点，最好先要求修正，再开始实现。

把这个技能当作 setup 视角，而不是最终权威

想真正发挥 better-auth-best-practices skill 的价值，最佳方式是先用它梳理一份清晰的安装计划，再去 https://better-auth.com/docs 核对精确语法和 framework 专属代码。两者配合，才是把这个技能稳妥落地成可运行集成的最好方式。