create-next-project

创建 Next.js 项目

引导式全栈 Next.js 项目搭建。通过 6 个交互步骤，使用 Agent 团队并行执行，搭建、配置并部署可用于生产环境的应用。

核心技术栈（始终包含）

• Next.js（最新版），使用 App Router、TypeScript、Tailwind v4 和 src/ 目录
• Bun 作为包管理器和运行时
• Biome 用于 lint 检查和格式化（搭建完成后手动安装）
• shadcn/ui，使用 dashboard-01 区块作为应用外壳
• tweakcn 用于主题自定义（在 tweakcn.com 上使用网页编辑器）
• next-themes 用于浅色/深色模式
• better-auth 用于身份验证
• Vercel 用于部署

数据层（取决于数据库的选择）

• 选择 Convex：对所有客户端数据使用 Convex 内置的 useQuery/useMutation。不需要 TanStack Query。
• 其他所有数据库：安装 TanStack Query，以便在客户端获取数据。

---

步骤 0：加载技能

开始任何工作之前，调用以下技能，将指导内容加载到上下文中：

1. Skill(vercel-react-best-practices) - React/Next.js 优化规则
2. Skill(vercel-composition-patterns) - 组件组合模式
3. Skill(better-auth-best-practices) - 身份验证集成模式

在所有步骤中遵循这些指导。

---

步骤 1：搭建项目 + Git + 仓库

此步骤会在磁盘上创建基础项目，并纳入版本控制。

1a. 搭建项目

如果目标目录中已有文件（例如 .claude/ 目录），请先将它们移至 /tmp，再搭建项目，然后将它们移回。

create-next-app 现在支持 --biome 标志（其交互式提示会询问“Which linter would you like to use? ESLint / Biome / None”）——直接传入该标志，不要先使用 ESLint 搭建项目，再将其移除：

bunx create-next-app@latest <project-name> \
  --typescript --tailwind --app --src-dir \
  --import-alias "@/*" --use-bun --turbopack --biome --yes
cd <project-name>

1b. 将 biome.json 与项目配置对齐

生成的 biome.json 是一个合理的默认配置，但请将其覆盖为项目配置——确切的 JSON 和 Biome 2.x 规则差异完整列表（organizeImports 位置、无 files.ignore、文件夹忽略语法、css.parser.tailwindDirectives）请参阅 references/stack-defaults.md。

更新 package.json 脚本：

{
  "scripts": {
    "dev": "next dev --turbopack",
    "build": "next build",
    "start": "next start",
    "lint": "biome check .",
    "lint:fix": "biome check --write ."
  }
}

自动修复所有文件：

bunx biome check --write .

1c. 初始化 Git + 验证

git init
bun run build
bun run lint
git add .
git commit -m "Initial Next.js scaffold with Biome"

1d. 询问仓库选项

向用户提供 3 个选项：

1. 创建新的 GitHub 仓库——使用 gh org list 列出可用组织，询问用户要选择哪个组织，然后运行 gh repo create <org>/<name> --private --source=. --remote=origin（暂不推送）。切勿根据对话猜测组织名称——务必查询。
2. 使用现有远程仓库——询问远程 URL，然后运行 git remote add origin <url>（暂不推送）
3. 暂时跳过——继续操作，不添加远程仓库

重要：暂时不要推送到 GitHub。 推送会触发 Vercel 部署；如果数据库尚未配置，部署会失败。首次推送会在步骤 6 完成所有基础设施设置后进行。

---

步骤 2：询问所有项目问题

现在项目搭建已完成，请在一轮中收集所有需求。使用 AskUserQuestion 提出多个问题。

需要询问的问题：

1. 认证方式（多选）：

   • 电子邮件/密码（推荐默认选项）
   • OAuth 提供商（Google、GitHub、Apple）
   • Sigma/Bitcoin 认证（启用 BSV 的应用）
   • Passkeys/WebAuthn

2. 数据库：

   • Convex（实时、无服务器）——注意：会使用 Convex 自带的客户端替代 TanStack Query
   • Turso/libSQL（边缘 SQLite）
   • PostgreSQL（传统数据库）
   • SQLite（本地开发）

3. 可选软件包（多选）：

   • @ai-sdk/openai + ai - AI/Agent 功能
   • @bsv/sdk - BSV 区块链
   • @1sat-lexi/js - 1Sat Ordinals
   • @1sat/connect + @1sat/react - 1Sat 钱包集成
   • clawnet - ClawNet Agent 平台
   • resend - 事务性电子邮件
   • 无

4. 主题：“选择一个预设（nova、vega、maia、lyra、mira），在 ui.shadcn.com/create 创建自定义主题，或在 tweakcn.com 选择主题并粘贴注册表 URL。”

5. 在 CLAUDE.md 中引用的技能（从已安装的插件中多选）：

   • 列出可用技能
   • 始终包含 vercel-react-best-practices 和 vercel-composition-patterns

记录所有答案——它们将为研究 Agent 和构建团队提供参考。

---

第 3 步：派遣研究 Agent

派遣并行研究 Agent（使用 Agent 工具并设置 run_in_background: true），为每个构建工作流收集上下文。每个 Agent 都会阅读相关源代码、文档或技能，以便构建 Agent 获得所需的一切信息。

Agent 分配（同时运行）：

研究 Agent 1：UI + 布局

• 阅读 references/layout-architecture.md 和 references/stack-defaults.md
• 如果用户提供了 tweakcn URL，告知构建 Agent
• 如果项目有特定的布局需求（例如，类似 Discord 的界面、仪表板），研究相应模式

研究 Agent 2：认证

• 阅读 references/auth-setup.md
• 根据用户选择调用相关认证技能：
  • Sigma：Skill(sigma-auth:setup-convex) 或 Skill(sigma-auth:setup-nextjs)
  • Passkeys：阅读 better-auth 的 passkey 文档
  • OAuth：记录各提供商所需的环境变量
• 如果使用 Convex，研究 @convex-dev/better-auth 适配器模式

研究 Agent 3：数据层

• 如果使用 Convex：调用 Skill(convex-best-practices)，阅读 Convex 架构模式
• 如果使用 Turso/PostgreSQL/SQLite：阅读 references/tanstack-query-setup.md
• 如果项目已有数据模型，或需要从旧项目迁移，阅读相应源文件
• 确定数据层所需的所有环境变量

研究 Agent 4：可选软件包（仅当用户选择了软件包时）

• 研究每个所选软件包的配置需求
• 确定环境变量、提供商设置和集成模式

等待所有研究 Agent 完成后，再执行第 4 步。

---

第 4 步：派遣构建团队

创建一个 Agent 团队（使用 TeamCreate），并分配专职 Agent。向每个 Agent 提供第 2 步的完整上下文和第 3 步的研究结果。

团队结构：

• Agent 1：UI + 布局 + 主题（阶段 2-3）——shadcn 初始化、dashboard-01 区块、主题提供商、单布局重构
• Agent 2：数据层（阶段 4）——根据数据库选择设置 Convex 或 TanStack Query
• Agent 3：认证（阶段 5，等待 Agent 2）——better-auth 服务端/客户端配置、登录/注册页面、中间件
• Agent 4：配置 + 可选软件包（阶段 6-7，等待所有其他 Agent）——可选软件包、.claude/CLAUDE.md、.env.vercel、最终构建/ lint 检查

Agent 协作：

• Agent 1（UI）和 Agent 2（Data）可以并行运行
• Agent 3（Auth）必须等待 Agent 2 完成（需要数据层存根/配置）
• Agent 4（Config）在其他所有 Agent 完成后运行（需要了解所有环境变量）

每个 Agent 都必须获得项目路径、Step 2 的答案、相关的 Step 3 调研内容、所需的特定参考文件内容、Biome 2.x 规则（禁止非空断言等），并收到在提交前运行 bun run build + bun run lint 的指示，同时使用描述性提交信息。

每个 Agent 的具体命令和职责请参阅 references/build-team.md。

---

Step 5：通过 Vercel 配置数据库

所有 Agent 完成且本地构建通过后，请在首次部署前配置数据库。不配置数据库就部署会导致部署出错，并可能创建重复或断连的数据库实例。

这是一个有人参与的流程：用户自行创建 Vercel 项目并添加存储（Agent 不应创建 Vercel 项目）。然后使用 vercel link 关联本地项目，使用 vercel env pull 拉取环境变量，并完成数据库专属设置——Convex 需要通过 Vercel Marketplace 集成按步骤完成 4 步指南；Turso/PostgreSQL/SQLite 则只需执行更简单的 CLI 或控制台操作。

完整的分步说明（包括 Vercel 项目和存储设置、关联、拉取环境变量，以及 Convex/Turso/PostgreSQL/SQLite 的各自配置）、Convex _generated/ 存根文件，以及 Convex 特有问题的完整列表，请参阅 references/database-provisioning.md。

---

Step 6：首次部署 + 持续工作流

配置好数据库并设置环境变量后，推送代码以触发首次部署：

git push -u origin main

或者，如果用户尚未设置 GitHub 远程仓库，先使用 gh org list 列出组织，询问用户选择哪个组织，然后运行 gh repo create <org>/<name> --private --source=. --remote=origin --push。

持续开发时需要打开两个终端：运行 bunx convex dev（如果使用 Convex，则会推送到开发部署环境），同时运行 bun dev（Next.js 通过 .env.local 连接到开发环境的 Convex）。生产环境会在 Vercel 构建期间通过 convex deploy 连接到生产环境的 Convex 部署——开发和生产环境拥有独立的数据、环境变量和函数代码。

部署后，请确认应用可以正常加载且没有客户端错误、身份验证正常工作、主题切换正常。运行 Skill(react-doctor) 和 bun run lint，并修复所有提示的问题——全新项目应该获得 100 分，而不只是“通过”。

首次部署完整流程、双终端开发工作流、开发与生产环境对比表、完整验证清单，以及 .env.vercel 文件模式（在 Step 1/4 中创建该文件，列出项目所需的所有环境变量，并将其作为 .gitignore 例外提交到仓库），请参阅 references/deployment-workflow.md。

核心原则

• 全程使用 Bun——绝不使用 npm、npx 或 yarn。所有操作都使用 bun、bunx
• 直接使用 --biome 搭建项目——create-next-app 现在有 --biome 标志；搭建时就传入该标志，而不是之后再移除 ESLint。仍需用项目统一配置覆盖生成的 biome.json
• Biome 2.x 配置——使用 assist.actions.source.organizeImports、在 files.includes 中使用否定模式（不使用 files.ignore）、设置 css.parser.tailwindDirectives: true
• 将 react-doctor 得分提升至 100——在宣布项目完成前运行 Skill(react-doctor)。新项目没有任何理由得分低于 100
• 不使用非空断言——Biome 会标记 process.env.FOO!。始终验证环境变量，并以清晰的错误信息抛出异常：

  // WRONG
  const url = process.env.DATABASE_URL!;
  // RIGHT
  const url = process.env.DATABASE_URL;
  if (!url) throw new Error("DATABASE_URL environment variable is required");
  

• 延迟初始化处理程序——依赖环境变量的身份验证路由处理程序必须延迟到请求时初始化，而不是在模块求值时初始化
• 为 cron 操作显式声明返回类型——避免循环类型引用
• 使用 Convex 替代 TanStack Query——使用 Convex 时，使用来自 convex/react 的 useQuery/useMutation。不要安装 TanStack Query。
• 优先使用 CLI——使用 create-next-app、shadcn、biome、vercel、gh CLI
• shadcn v4 安全标志——迭代添加组件时使用 --dry-run 和 --diff，先预览更改再应用
• 使用最新版本——所有安装都始终使用 @latest
• 构建验证——每个提交检查点都运行 bun run build
• 数据库就绪前不要推送——通过 Vercel Storage 配置数据库之前，绝不要推送到 GitHub。推送会触发 Vercel 部署；如果没有连接数据库，部署就会失败，造成部署损坏，还可能产生重复且未连接的数据库实例
• Agent 团队——在 Claude Code 中，使用 TeamCreate 并行执行第 2 至第 7 阶段。为每个 Agent 提供充分的上下文，因为它们无法查看对话历史。

其他资源

参考文件

• references/stack-defaults.md——配置 Biome、主题提供程序、Tailwind 或 shadcn/ui 时阅读；包含准确的配置、预设和安全标志
• references/layout-architecture.md——将 dashboard-01 模块重构为单布局模式（导航栏/侧边栏框架 + 路由内容）时阅读
• references/auth-setup.md——为任何身份验证方式（电子邮件/密码、OAuth、Sigma、通行密钥）或数据库适配器接入 better-auth 时阅读
• references/tanstack-query-setup.md——为非 Convex 项目设置数据层（提供程序、自定义钩子）时阅读
• references/build-team.md——派遣第 4 步的构建团队前阅读；包含每个 Agent 的逐条命令职责和上下文检查清单
• references/database-provisioning.md——在第 5 步阅读；包含完整的 Vercel + 数据库配置步骤（Convex、Turso、PostgreSQL、SQLite）、Convex _generated/ 存根及 Convex 注意事项
• references/deployment-workflow.md——在第 6 步阅读；包含首次部署顺序、持续开发工作流、开发与生产环境对照表、验证清单以及 .env.vercel 模式

相关技能

• vercel-react-best-practices——React/Next.js 优化规则
• vercel-composition-patterns——用于构建可扩展应用的组件组合模式
• frontend-design——避免通用审美的 UI 设计
• better-auth-best-practices——身份验证集成模式
• convex-best-practices——Convex 模式（使用 Convex 时）
• sigma-auth:setup-convex——使用 Convex 的 Sigma 身份验证
• sigma-auth:setup-nextjs——使用 Next.js 的 Sigma 身份验证（非 Convex）