bootstrap

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Bootstrap & Scaffolding Wizard

项目搭建与初始化向导

1. The Bootstrapping Process

1. 初始化流程

When a user requests to create a new project or a complex new feature, you MUST NOT start writing code immediately. Instead, you MUST act as a technical product manager. Your goal is to build purely serverless applications using the Pragmatic DDD architecture.

You MUST ask the user a series of assessment questions (detailed below). The outputs of this assessment MUST be explicitly separated into two files:

AGENTS.md
: Global, high-level technical configurations (e.g., "Pragmatic DDD, Neon DB, Better Auth"). This file is automatically attached to all agent prompts, so it MUST be kept concise.
Product Requirements Document (PRD): A separate markdown file (e.g.,
```
docs/PRD.md
```
) containing the detailed business features and user stories. The agent MUST consult this file whenever it needs feature context, but it MUST NOT be placed inside
```
AGENTS.md
```
.

当用户请求创建新项目或复杂新功能时，你绝不能立即开始编写代码。相反，你必须扮演技术产品经理的角色。你的目标是使用Pragmatic DDD架构构建纯无服务器应用。

你必须向用户提出一系列评估问题（详情如下）。评估结果必须明确分为两个文件：

AGENTS.md
：全局、高层级的技术配置（例如："Pragmatic DDD, Neon DB, Better Auth"）。该文件会自动附加到所有Agent提示中，因此必须保持简洁。
产品需求文档（PRD）：单独的Markdown文件（例如：
```
docs/PRD.md
```
），包含详细的业务功能和用户故事。Agent需要功能上下文时必须查阅此文件，但不得将其放入
```
AGENTS.md
```
中。

2. Assessment Questions

2. 评估问题

You MUST ask the user the following questions to shape the architecture:

Persistence: Is this a simple static page, or a full application requiring a database?
- Constraint: If a DB is required, you MUST use Docker Compose for local development. For production, you MUST suggest Neon (since it scales to zero and auto-awakes) and discourage Supabase (which doesn't auto-awake when paused).
Authentication: Does the app need authentication?
- Constraint: If yes, ask which type. Suggest Email OTP, Magic Links, or OAuth2. You MUST strongly discourage traditional email/password for security reasons. If email auth is chosen, you MUST use
```
Better Auth
```
  +
```
Resend
```
  +
```
@react-email/components
```
  (required to compile React components for emails).
Workspaces & Billing: Will the app be managed by individual user accounts only, or by Workspaces/Organizations?
- Constraint: If billing or payments are involved, you MUST explicitly ask if the billing is tied to the Workspace or to the individual User. This dictates the UI sidebar layout.
Internationalization (i18n): Will the app support multiple languages?
- Constraint: If yes, you MUST use the custom library-free i18n implementation and explicitly separate public (
```
app/[locale]
```
  ) and private (
```
app/dashboard
```
  ) route handling.
Project Scope: Is this a serious production-ready project from day one, or a quick draft/boceto?
- Constraint: If it is a draft, you MUST NOT install or configure testing libraries (
```
vitest
```
  ,
```
testcontainers
```
  ) initially to save time. Remind the user that the Pragmatic DDD architecture allows adding tests easily later. If it is serious, testing libraries MUST be installed from the start.

你必须向用户提出以下问题以确定架构方向：

持久化方案：这是简单的静态页面，还是需要数据库的完整应用？
- 约束条件：如果需要数据库，本地开发必须使用Docker Compose。生产环境必须建议使用Neon（因为它可以缩容至零并自动唤醒），不推荐Supabase（暂停后无法自动唤醒）。
认证机制：应用是否需要认证功能？
- 约束条件：如果需要，询问具体类型。建议使用邮箱OTP、魔法链接或OAuth2。出于安全原因，必须强烈不推荐传统的邮箱/密码认证。如果选择邮箱认证，必须使用
```
Better Auth
```
  +
```
Resend
```
  +
```
@react-email/components
```
  （用于编译邮件用React组件）。
工作区与计费：应用仅由个人用户账户管理，还是支持工作区/组织管理？
- 约束条件：如果涉及计费或支付，必须明确询问计费是绑定到工作区还是个人用户。这将决定UI侧边栏的布局。
国际化（i18n）：应用是否支持多语言？
- 约束条件：如果需要，必须使用无自定义库的i18n实现，并明确区分公共路由（
```
app/[locale]
```
  ）和私有路由（
```
app/dashboard
```
  ）的处理方式。
项目范围：从一开始就是严肃的生产就绪项目，还是快速草稿/原型？
- 约束条件：如果是草稿，初始阶段不得安装或配置测试库（
```
vitest
```
  、
```
testcontainers
```
  ）以节省时间。提醒用户实用DDD架构允许后续轻松添加测试。如果是生产就绪项目，必须从一开始就安装测试库。

3. Product Requirements Document (PRD)

3. 产品需求文档（PRD）

After the initial technical boundaries are set, you MUST ask the user for the core idea of the application.

You SHOULD suggest features to help flesh out the idea.
Once the idea is clear, you MUST generate a Product Requirements Document (PRD) and save it as a separate markdown file (e.g.,
```
docs/PRD.md
```
).
The PRD MUST ONLY contain business features and user stories. It MUST NOT mention specific technologies or libraries.

在确定初始技术边界后，你必须询问用户应用的核心构想。

你应该提出功能建议以完善构想。
一旦构想明确，必须生成产品需求文档（PRD）并保存为单独的Markdown文件（例如：
```
docs/PRD.md
```
）。
PRD必须仅包含业务功能和用户故事，不得提及具体技术或库。

4. Architecture & Bounded Contexts Recognition

4. 架构与限界上下文识别

Once the PRD is defined, you MUST explicitly identify the main domain entities of the SaaS. These entities will dictate the Bounded Contexts (isolated modules) of the application.

You MUST also recognize core/cross-cutting contexts that are not tied to a specific business entity, such as
```
auth
```
(for authentication) or
```
shared
```
(for common utilities and cross-module infrastructure).

You MUST evaluate what technologies to add based on our strict serverless philosophy:

Deployment: Default to Vercel or Google Cloud Run.
Async & Background Jobs: If the app needs to process information that is slow, takes time, or does not need an immediate synchronous response, you MUST use Google Cloud Run Jobs triggered via Inngest.
Long-running/Scheduled Workflows: If the app requires logic that spans across days or has specific scheduling per client, you MUST use Inngest.

PRD确定后，必须明确识别SaaS的主要领域实体。这些实体将决定应用的限界上下文（独立模块）。

还必须识别不绑定到特定业务实体的核心/横切上下文，例如
```
auth
```
（认证）或
```
shared
```
（通用工具和跨模块基础设施）。

必须基于严格的无服务器理念评估要添加的技术：

部署：默认使用Vercel或Google Cloud Run。
异步与后台任务：如果应用需要处理缓慢、耗时或不需要即时同步响应的信息，必须使用Google Cloud Run Jobs，由Inngest触发。
长期运行/定时工作流：如果应用需要跨多天的逻辑或针对客户端的特定调度，必须使用Inngest。

5. UI Libraries & Component Strategies

5. UI库与组件策略

This architecture leverages the

shadcn/ui

CLI to integrate components like shadcn/ui and Magic UI. You MUST apply the following UI construction rules:

该架构利用

shadcn/ui

CLI集成shadcn/ui和Magic UI等组件。必须遵循以下UI构建规则：

Preferential Hierarchy

优先级层级

When building the UI, you MUST follow this hierarchy in order of preference:

Building Blocks: High-level page structures.
Individual Components: Primitives like buttons, dialogs, etc.
Templates: You MUST NOT use templates unless explicitly requested by the user.

构建UI时，必须按以下优先级顺序执行：

构建块：高层级页面结构。
独立组件：按钮、对话框等基础组件。
模板：除非用户明确要求，否则不得使用模板。

Tooling and MCP Initialization

工具与MCP初始化

You MUST check if the

shadcn

skill and the respective MCP servers (

shadcnui

and

magicui

) are installed.

To install the shadcn skill: run

npx skills add https://github.com/shadcn/ui --skill shadcn

To install the shadcn MCP: run
```
npx shadcn@latest mcp init --client <cliente>
```
(where
```
<cliente>
```
is
```
claude
```
,
```
cursor
```
,
```
vscode
```
, or
```
opencode
```
depending on the user's IDE). If the IDE is not listed, consult the shadcn documentation.

To install the Magic UI MCP: update the MCP configuration file (generated by shadcn or currently active) and append the following server:

json

{
  "mcpServers": {
    "magicuidesign-mcp": {
      "command": "npx",
      "args": ["-y", "@magicuidesign/mcp@latest"]
    }
  }
}

必须检查

shadcn

技能和相应的MCP服务器（

shadcnui

和

magicui

）是否已安装。

安装shadcn技能：运行

npx skills add https://github.com/shadcn/ui --skill shadcn

安装shadcn MCP：运行
```
npx shadcn@latest mcp init --client <cliente>
```
（其中
```
<cliente>
```
根据用户IDE选择
```
claude
```
、
```
cursor
```
、
```
vscode
```
或
```
opencode
```
。如果IDE未列出，请查阅shadcn文档）。

安装Magic UI MCP：更新MCP配置文件（由shadcn生成或当前激活的文件），并添加以下服务器：

json

{
  "mcpServers": {
    "magicuidesign-mcp": {
      "command": "npx",
      "args": ["-y", "@magicuidesign/mcp@latest"]
    }
  }
}

Authentication UI

认证UI

You MUST consult the shadcn MCP to suggest building blocks for the authentication pages.

Login Page Default:
```
npx shadcn@latest add login-04
```
. You MUST verify no existing login page conflicts before running this.
Signup Page Default:
```
npx shadcn@latest add signup-04
```
.
Adaptation: After installing these blocks, you MUST adapt them to the project's styling rules and ensure only the active authentication methods (e.g., specific social logins, magic links) are rendered, removing passwords if they are disabled.

必须参考shadcn MCP建议认证页面的构建块。

默认登录页面：
```
npx shadcn@latest add login-04
```
。运行前必须验证无现有登录页面冲突。
默认注册页面：
```
npx shadcn@latest add signup-04
```
。
适配调整：安装这些构建块后，必须根据项目样式规则进行调整，确保仅渲染激活的认证方式（例如特定社交登录、魔法链接），如果禁用密码则移除相关模块。

Dashboard Sidebar Layout

仪表盘侧边栏布局

You MUST avoid placing the main navigation in a top bar. You MUST prefer a traditional navigation sidebar on the left using shadcn building blocks.

Workspaces & User Profiles: If the app supports workspaces, you MUST default to
```
npx shadcn@latest add sidebar-07
```
, which allows quick switching between profiles and workspaces. Place billing/payments settings accurately on the user section or workspace section based on the assessment answer.
User Profiles Only: If the app DOES NOT use workspaces, you MUST still use
```
sidebar-07
```
. However, you MUST manually remove the Workspaces segment from the component and move the User Profile selector to the top of the sidebar (replacing the dashboard/workspace switcher).

必须避免将主导航放在顶部栏。必须优先使用左侧传统导航侧边栏，基于shadcn构建块。

工作区与用户配置文件：如果应用支持工作区，必须默认使用
```
npx shadcn@latest add sidebar-07
```
，该组件允许在配置文件和工作区之间快速切换。根据评估结果，将计费/支付设置准确放置在用户区域或工作区区域。
仅用户配置文件：如果应用不使用工作区，仍必须使用
```
sidebar-07
```
。但必须手动移除组件中的工作区部分，并将用户配置文件选择器移至侧边栏顶部（替换仪表盘/工作区切换器）。

Micro-interactions & Aesthetics

微交互与美观性

The application SHOULD feel highly polished using micro-interactions and animations.

Every action that takes time (e.g., submitting a form, executing a Server Action) MUST be visually represented using components from the aforementioned libraries (e.g., loading spinners on buttons, disabled states, loading text).
Use the MCP to find specialized interactive components. If a suitable component cannot be found, you MUST create or modify the existing ones.
Custom Animations: If you need to create custom interactive components or complex animations from scratch, you MUST use Framer Motion (now known as motion.dev).
You SHOULD suggest the component library websites to the user so they can visually browse and choose blocks/components they like.

应用应通过微交互和动画实现高度精致的体验。

每个耗时操作（例如提交表单、执行Server Action）必须使用上述库的组件进行视觉反馈（例如按钮上的加载 spinner、禁用状态、加载文本）。
使用MCP查找专用交互组件。如果找不到合适的组件，必须创建或修改现有组件。
自定义动画：如果需要从零开始创建自定义交互组件或复杂动画，必须使用Framer Motion（现称为motion.dev）。
你应该向用户推荐组件库网站，以便他们直观浏览并选择喜欢的构建块/组件。

6. The Pre-Flight Proposal

6. 预启动提案

Before creating any files or writing code, you MUST present a comprehensive report (the "Pre-Flight Proposal") to the user. This proposal acts as a final confirmation step and MUST include:

What is going to be built (Summary of the PRD and chosen domain contexts).
With what technologies (Summarizing the decisions from the assessment wizard).
How it will be structured, specifically outlining the proposed folder structure (including the planned Bounded Contexts in
```
src/
```
and the routing structure in
```
src/app/
```
).

You MUST ask the user if they agree with this proposal or if they want to make any changes before you begin generating the scaffolding.

在创建任何文件或编写代码之前，必须向用户提交一份全面的报告（"预启动提案"）。该提案作为最终确认步骤，必须包含：

要构建的内容（PRD摘要和选定的领域上下文）。
使用的技术（评估向导中决策的总结）。
结构方式，具体概述提议的文件夹结构（包括
```
src/
```
中规划的限界上下文和
```
src/app/
```
中的路由结构）。

必须询问用户是否同意此提案，或者是否需要进行任何修改，然后再开始生成脚手架。

7. Project Execution & Scaffolding Flow

7. 项目执行与搭建流程

If the Pre-Flight Proposal is approved, you MUST start scaffolding the codebase following this exact sequential order:

如果预启动提案获得批准，必须严格按照以下顺序开始搭建代码库：

Phase 1: Next.js Initialization

阶段1：Next.js初始化

Determine the installation directory.
- If the current folder is mostly empty (e.g., only containing
```
skills
```
  or a README), you MUST initialize the application in the current directory using
```
.
```
  to avoid deep nesting.
- If the target folder is occupied, prompt the user for a new folder name and apply it to the CLI.

Run the Next.js scaffold command:

bash

npx create-next-app@latest . --ts --tailwind --biome --app --src-dir --import-alias "@/*" --yes

确定安装目录。
- 如果当前文件夹基本为空（例如仅包含
```
skills
```
  或README），必须在当前目录初始化应用，使用
```
.
```
  避免深层嵌套。
- 如果目标文件夹已被占用，提示用户输入新文件夹名称并应用于CLI命令。

运行Next.js搭建命令：

bash

npx create-next-app@latest . --ts --tailwind --biome --app --src-dir --import-alias "@/*" --yes

Phase 2: Shadcn & Dependencies

阶段2：Shadcn与依赖项

Once Next.js is installed, you MUST initialize

shadcn

before anything else.

Run
```
npx shadcn@latest init
```
and configure it according to Next.js strict standards.
Proceed to install the
```
shadcn
```
skill and MCP servers as described in Section 5 (Tooling and MCP Initialization).
Then, begin adding the building blocks and components (e.g., login, sidebar) requested in the UX phase.

Next.js安装完成后，必须先初始化

shadcn

，再进行其他操作。

运行
```
npx shadcn@latest init
```
并根据Next.js严格标准进行配置。
按照第5节（工具与MCP初始化）中的描述安装
```
shadcn
```
技能和MCP服务器。
然后开始添加UX阶段要求的构建块和组件（例如登录、侧边栏）。

8. Infrastructure Setup

8. 基础设施设置

(Apply these rules once the coding phase begins and Docker is required)

(在编码阶段开始且需要Docker时应用这些规则)

Docker Compose Setup (PostgreSQL 18)

Docker Compose设置（PostgreSQL 18）

This architecture relies heavily on Testcontainers for integration testing. For local development, Docker Compose is used.

Crucial Constraints for Postgres 18:

You MUST use PostgreSQL 18 (e.g.,
```
postgres:18.1-alpine
```
).
Default mounting behavior requires you to map the volume strictly to
```
/var/lib/postgresql
```
to avoid permission errors.
You MUST provide fallback defaults for environment variables (e.g.
```
${POSTGRES_USER:-postgres}
```
) so the containers can run from a DevContainer without a pre-existing
```
.env
```
file.
Healthchecks are generally unnecessary for standard local development without strict orchestration loops like Swarm. You MAY omit them to keep the file simple.

该架构严重依赖Testcontainers进行集成测试。本地开发使用Docker Compose。

Postgres 18的关键约束：

必须使用PostgreSQL 18（例如：
```
postgres:18.1-alpine
```
）。
默认挂载行为要求将卷严格映射到
```
/var/lib/postgresql
```
以避免权限错误。
必须为环境变量提供回退默认值（例如
```
${POSTGRES_USER:-postgres}
```
），以便容器可以在没有预存
```
.env
```
文件的DevContainer中运行。
对于没有严格编排循环（如Swarm）的标准本地开发，健康检查通常不必要。可以省略以简化文件。

DevContainers (Optional)

DevContainers（可选）

The use of DevContainers is optional. However, if requested by the user or utilized to maintain a uniform environment, the

.devcontainer/devcontainer.json

MUST be wired to use the

docker-compose

compose.dev.yml

file as its backend.

Critical Requirements for the DevContainer:

Docker-outside-of-Docker (DoOD): Because our integration tests use
```
@testcontainers/postgresql
```
, the DevContainer environment MUST have Docker socket access. Always include
```
"ghcr.io/devcontainers/features/docker-outside-of-docker:1"
```
with
```
"enableNonRootDocker": true
```
in the features list.
Mounts and Users: The
```
remoteUser
```
SHOULD typically be
```
node
```
and the environment MUST map
```
/workspace
```
.

使用DevContainers是可选的。但如果用户要求或用于保持环境一致性，

.devcontainer/devcontainer.json

必须配置为使用

docker-compose

或

compose.dev.yml

文件作为后端。

DevContainer的关键要求：

Docker-outside-of-Docker (DoOD)：因为我们的集成测试使用
```
@testcontainers/postgresql
```
，DevContainer环境必须具有Docker套接字访问权限。必须在功能列表中包含
```
"ghcr.io/devcontainers/features/docker-outside-of-docker:1"
```
并设置
```
"enableNonRootDocker": true
```
。
挂载与用户：
```
remoteUser
```
通常应为
```
node
```
，环境必须映射
```
/workspace
```
。

References

参考资料

You MUST refer to the following foundation files to see a complete working setup of DevContainers and Docker Compose orchestration:

```
[dockerfile](references/dockerfile)
```
: Multistage setup.
```
[compose.dev.yml](references/compose.dev.yml)
```
: Local compose orchestration (showing volume mounts and fallback env variables).
```
[.devcontainer.json](references/devcontainer.json)
```
: The VSCode DevContainer configuration with DoOD enabled.

必须参考以下基础文件查看DevContainers和Docker Compose编排的完整工作配置：

```
[dockerfile](references/dockerfile)
```
：多阶段构建配置。
```
[compose.dev.yml](references/compose.dev.yml)
```
：本地编排配置（展示卷挂载和回退环境变量）。

[.devcontainer.json](references/devcontainer.json)

：启用DoOD的VSCode DevContainer配置。