start-an-app

启动一个应用

将一个想法变成可运行的 Web 应用。先充分理解这个想法，然后再开始构建。从第一次提交开始，成果就是用户自己的应用——使用他们的名称、页面和数据模型，并且只包含他们需要的基础设施。应用绝不应该让人觉得是个模板。

先理解，再搭建脚手架。 访谈是这项技能中最有价值的部分，而不是走过场的形式。花十分钟提出好问题，就能打造出用户一眼就认得出的应用；跳过这一步，只会得到一个通用的 CRUD 外壳，用户还得自己重写。在双方就构建说明达成一致之前，唯一可以运行的命令是步骤 2a 中的技能安装命令；在步骤 3 之前，不会对应用本身进行任何操作。

基本原则

• 解释每个选择时，都要像向一位聪明但不写代码的朋友解释那样。先说“存放数据的地方”，再说“数据库”。每次首次提到一个技术术语时，都要简要介绍，然后正常使用。
• 弄清楚再继续。 对含糊的回答追问，不要自行假设来填补空白。“一个给俱乐部用的网站”还不是需求说明——会员在上面做什么？
• 一次只讨论一个主题。需求了解阶段要顺着对话展开，而不是照着清单提问；讨论技术选择时，一次只问一个问题，并给出推荐的默认选项，这样用户只需回答“按你的建议来”。
• 把遗漏作为建议提出，而不是盘问。“这类应用通常需要在发布后编辑条目的功能——要不要放进第一个版本？”比逐项核对清单更好，也能帮助用户了解自己真正想要什么。
• 先给出建议，再尊重选择。如果用户选了非推荐选项，就按用户的选择来，不要反复争论。
• 绝不要运行 drizzle-kit push。 架构变更始终要依次通过 db:generate 和 db:migrate，每次都如此，从第一张表开始。
• Id 随机生成 UUID——Better Auth 的表除外。 你定义的每张表都要有一个。Better Auth 的 CLI 生成的表保持原样，这也意味着任何指向用户的列都应使用 text，而不是 uuid。references/database.md 包含这两种情况。
• 应用直接搭建在当前工作目录中——该文件夹就是项目根目录。绝不要为它创建子文件夹，也不要 cd 进入子文件夹；用户已经通过当前所在位置选好了应用的存放位置。
• 技术栈是固定的：Next.js、TypeScript、Tailwind、shadcn/ui、Drizzle、Better Auth。访谈只在其中做选择（使用哪个数据库、采用哪种登录方式、电子邮件、上传、支付、AI、后台任务、文档、应用是否需要被搜索到，以及外观）——绝不替换这些组件，也绝不在它们之外再叠加第二个框架。文档是这个应用中的页面，不是旁边另建一个文档平台。
• 凡是属于用户的内容，都由 Better Auth 管理。 如果 Better Auth 为某项集成提供了插件——尤其是支付——就使用该插件，绝不要在旁边接入服务提供商的独立 SDK。用户只有一个事实来源，客户 ID 和 Webhook 也只有一个存放位置。
• 工具只是另一个调用方，不是第二种入口。 如果应用向 AI Agent 开放，每个工具都要调用与按钮相同的函数、执行相同的归属检查并写入相同的日志；用户身份应从令牌获取，而不是从模型传入的任何内容获取。references/mcp.md。
• 优先选择适合部署的方案。若某项功能在生产环境中的工作方式不同（如上传、Postgres），本地环境和部署环境必须使用同一份代码，只通过环境变量切换——绝不能让用户记住并切换到另一条代码路径。
• 每个应用都要有设置区域。 这不是最后的润色，而是从第一次提交就要具备的部分，并根据应用的规模调整。如果有账户，就要有个人资料、验证状态、密码、设备和注销方式。每个应用，无论是否有账户，都要有系统视图：配置了什么、发生过什么、正在运行什么。references/settings.md 和 references/ops.md。
• 应用在法律上对用户负有哪些义务，要自行判断，不能让用户回答。 是否需要隐私政策、服务条款或 Cookie 横幅，取决于应用的用途和加载的内容——个人日记不需要这些；供公众注册使用的产品需要前两项；只有在实际加载了非必要内容时才需要横幅，而会话 Cookie 不属于此类内容。做出判断，准确实现所需内容，并在构建清单中用一句话写明决定，让用户看到的是明确结论，而不是疏漏。references/legal.md。
• 应用在用户看不到的地方执行的所有操作，都必须能在应用内查看和控制。 如果应用会发送电子邮件、在后台运行任务或按计划执行操作，用户就能在应用内看到任务已执行、了解失败原因、停止任务并重试，而不是去托管平台的控制面板查看日志。让用户无法查看运行情况的功能，就不算完成。
• 要询问应用是否需要被搜索到，并实现两种答案对应的方案。 仅当应用有合理的机会被搜索到时才询问——例如面向公众的产品或内容网站。绝不询问个人工具或内部工具，也绝不给它们添加站点地图；应为其设置明确的浏览器标签页标题，并主动选择禁止出现在搜索结果中，这是交付内容，不是遗漏。references/seo.md。
• 只为实际存在的功能编写文档，并且只放在有人会阅读的地方。 这里的大多数应用都不需要文档。如果面向陌生用户注册的产品需要帮助页面，四篇诚实的说明胜过二十篇；描述应用并不具备的功能，比没有页面更糟——它会让用户去找一个根本不存在的按钮。references/docs.md。
• 每个应用都要有成文的设计系统，之后不得擅自覆盖。 访谈中要像询问其他需求一样询问外观，并在第一个界面出现之前将其写入项目根目录的 DESIGN.md，以主题令牌而非建议的形式体现。从此以后，它必须遵守：在组件中硬编码颜色、字号或圆角是 Bug，不是捷径；“这样看起来更好”正是让应用出现五种蓝色的原因。AGENTS.md 和 CLAUDE.md 都要指向它，确保下一个打开项目的 Agent 也遵守规范。references/design.md。
• 优先使用维护者自己提供的技能，而不是先搜索。 shadcn、Vercel、Better Auth 和 Anthropic 都为自己的库发布了 Agent 技能。步骤 2a 会一次性全局安装这些技能；从那以后，遇到这些库相关问题时，应首先查阅它们，优先于搜索、博客文章或记忆。阅读随 API 提供的文件，比研究资料更快，也往往更准确。
• 绝不编写或接受版本号。 无论是在安装命令、package.json 代码片段、正文还是 Docker 镜像标签中，都不可以。本技能中的任何文件都不固定版本，也绝不应加入版本号。每次安装都使用当前稳定版，步骤 2 会确定它是什么。在技能文件中写入版本号，就是给谎言加上时间戳：它会悄无声息地过时，并让应用使用去年的 API 构建。
• 永远不要使用已弃用的内容。 如果当前版本弃用了参考文件中的某项内容、对其重新命名或以新内容取代，就使用替代方案，而不是仍然“能用”的旧路径。所谓仍然能用，正是已弃用的含义；它只是延迟生效的移除通知，而继续使用它会让用户不得不进行他们并未要求的重写。
• 没有运行过的检查，就明确说没运行，绝不要声称通过。 仅仅因为你写了应该让应用实现某项功能的代码，就说应用确实能做到，这是回忆，不是验证。能运行的检查就实际运行；无法运行时——例如没有浏览器、密钥或域名——说明无法运行哪项检查，以及需要什么条件。用户会把沉默理解为成功。
• 所有命令、包名和配置都放在参考文件中，绝不放在本文件中。只加载用户所选分支对应的参考文件。
• 如果某条参考命令因为工具发生变化而失败（例如标志重命名或初始化流程不同），就查阅该工具的官方文档，使用当前等效方案并完成任务；最后告诉用户，本技能的参考文件需要更新。

第 1a 步 — 理解想法

从这里开始，直到思路清晰为止。

“你要做什么？像跟朋友介绍一样描述一下。”

然后继续追问。留意名词（应用需要跟踪的事物）和动词（人们对这些事物进行的操作）——它们会成为数据库表和页面。继续追问，直到两者都足够具体：

• “带我过一遍流程——有人第一次打开应用时会做什么？”
• “然后呢？是什么让他们第二天又回来？”
• “你说的 [他们含糊的说法] — 在屏幕上实际会是什么样？”
• “你现在已经在用类似的东西吗？这个应用比它好在哪里？”

然后用通俗的话复述数据模型，让他们来纠正。这是整个技能中价值最高的问题，因为不懂得设计架构的人，完全可以告诉你架构有什么问题：

那么，这个应用会保存一份徒步记录列表——每条记录都有日期、路线名称、距离、徒步感受和一些照片。这些都只属于你，其他人看不到。我理解得对吗？还是说它还需要记住其他内容？

第 1b 步 — 找出遗漏

用户已经告诉了你理想流程。剩下的就是你的工作。默默过一遍以下问题，只提出确实适用的那些——作为带有建议的推荐，而不是测验：

• 数据属于谁？ 每位用户私有、团队共享，还是公开？这会决定应用中的每个查询，也是人们最容易忘记说明的事。
• 内容可以修改吗？ 大多数描述只涵盖创建。通常也需要编辑和删除，但几乎从没人提起。
• 有没有特殊角色？ 例如能看到比其他人更多内容的管理员、版主或所有者。
• 第一天会是什么样？ 应用刚打开时没有任何数据。那个界面应该显示什么？
• 有任何与时间相关的内容吗？ 截止日期、提醒、定期项目、“本周”视图。
• 需要通知任何人吗？ 注册、邀请或发生某些事情时发送邮件。如果需要，这就是第 1c 步中的邮件问题——沿用他们的回答，不要问两遍。
• 有没有需要花一段时间的操作？ 不应该让用户等待的工作——导入文件、生成报告、调用响应缓慢的服务、定时执行的任何操作。大多数应用都没有；有这类操作的应用通常会在这里提到，而不是在理想流程中提到。
• 用手机还是桌面设备？ 这会尽早影响布局决策，而且很容易询问。
• 第一个版本明确不包含什么？ 直接问清楚。明确哪些内容不做，才能让第一个版本按时交付；也能让你有理由省略某些功能，而不是靠猜。

通常有两三个问题比较重要。把九个问题全提出来就像审问——只挑那些会改变你构建方案的问题。

第 1c 步 — 技术选择

现在进入分支问题。一次问一个，每个问题都给出建议。不要询问他们已经告诉过你的内容——如果描述已经让答案显而易见（“付费简报”、“照片日记”），就顺带确认，而不是再提问：“听起来大家会为此付费——我来配置一下。”

1. “谁会使用它——暂时只有你，还是还有其他人／公众？” → 只有我／试试一个想法：推荐 SQLite（“你的数据会保存在项目中的一个简单文件里——无需额外安装或运行任何东西”）。 → 其他人／计划用于生产环境：推荐 Postgres（“大多数正式应用使用的数据库——它会在你的机器上的 Docker 中运行，因此只需一条命令即可启动，不会永久安装任何东西，而且这也是你在生产环境中会使用的同一个数据库”）。 → 使用 Postgres 需要安装并运行 Docker Desktop。承诺使用前先确认这一点；如果他们没有安装且不想安装，可以提供 SQLite 或免费的托管 Postgres 作为替代方案。

2. “用户需要登录吗？” → 不需要账号：完全跳过身份验证。 → 需要：推荐默认使用电子邮件 + 密码（“开箱即用，无需配置”）。 → 如果他们想要“使用 Google 登录”：表示可以，并提前说明预期情况——需要免费配置 Google Cloud，包含几个复制粘贴步骤；可以提出一起完成，或之后再添加。

3. “应用需要发送任何电子邮件吗——确认地址、重置密码，或告知某人发生了什么？” → 不需要：完全跳过电子邮件。登录仍然可用；只是添加相关功能之前无法验证或重置密码。 → 需要：推荐 Resend。尽早如实说明预期情况，因为这是唯一需要他们可能尚不具备的条件的组件：“发送给自己可以立即使用。要发送给其他人，你需要一个域名和几条 DNS 记录——大约十分钟，而且免费。”如果他们没有域名，也照样采用，并说明发送步骤要等有了域名才能进行——与此同时其他功能都能正常运行，电子邮件会输出到终端。 → 如果他们说不需要登录，但需要电子邮件，也没问题——联系表单或通知不需要账号。

4. “用户会上传任何内容吗——照片、文档、个人资料图片？” → 不会：完全跳过文件存储。 → 会：无需选择，因此不要提供选项。说明具体处理方式：“开发期间，上传的文件会保存到项目中的一个文件夹。部署时，它们会自动转到正规的云存储中——代码不变，只需连接一个存储服务。”只有在他们询问时才提及 Vercel Blob。

5. “用户需要付费购买任何内容吗——订阅或一次性购买？” → 不需要：完全跳过支付功能。 → 需要：推荐 Polar（“他们会为你处理全球销售税和增值税，这通常是最棘手的部分”），如果他们已经在使用 Stripe 或需要使用它，则将其作为备选方案。 → 支付功能需要账号。如果他们说不需要登录，请直接说明并添加登录：“我们也需要账号，这样应用才能知道各订阅属于谁。” → 提前说明预期情况：所有内容都会在测试模式下设置，不会涉及真实资金；之后只需切换一个密钥即可正式启用。

6. “应用需要任何 AI 功能吗——例如聊天，或生成文本或内容？” → 只有在需要时才添加 AI 基础设施。如果需要，请说明他们需要一个 OpenRouter API 密钥（可免费创建），并告诉他们在哪里获取——一个密钥，即可使用多种模型。

7. “是否有任何任务需要持续独立运行——在用户关闭标签页后继续执行，或按计划运行？” → 默认选择不需要，大多数应用都应该如此。服务器操作足以妥善处理保存记录、发送一封电子邮件或调整一张图片的大小；为此添加任务系统只会增加开销，还附带一个仪表板。 → 如果任务必须在重启后继续运行、失败后自动重试、按计划运行、批量处理许多项目，或等待几分钟到几天，则选择需要。例如导入电子表格、生成报告、调用响应缓慢的外部服务或发送每夜摘要。 → 如果需要：推荐 Inngest（“它会在应用之外运行任务，发生崩溃时会从中断处继续，自动重试，而且你可以在开发过程中查看每个步骤的执行情况”）。它可以免费开始使用，而且开发期间完全不需要账号。

8. “其他软件是否可以代表你使用这个应用？这样你就能让 Claude 添加条目或提取摘要，而无需亲自打开应用？” → 这是一个真正的二选一问题，所以照实询问，不要偏向任何一方。选“是”意味着，应用的主要操作也会成为 AI Agent 可调用的工具，并受到相同的登录和权限控制——可立即通过 Claude Code 使用；应用部署到公开位置后，也可通过 Claude.ai 或 ChatGPT 使用。选“否”意味着由用户通过浏览器使用应用，这完全没问题，而且以后可以添加此功能，不会影响之前构建的任何内容。 → 如果对方拿不准，值得说明：这些工具最终就是应用已有的那几项功能，因此主要成本在于登录接入；此外还有一个页面，列出所有有权访问的 Agent，并提供一个按钮来撤销访问权限。 → 这需要账户，和支付功能一样。如果对方之前拒绝了登录，用一句话说明即可——“Agent 必须以你的身份登录，这样应用才知道它正在访问谁的数据”——不要把它说成障碍。

9. “用户未登录访问应用时，应该看到什么？” → 这决定了应用的入口：是供其他人注册使用的正式落地页，还是个人工具直接进入应用。不要想当然地认为需要营销页面——references/pages.md 给出了判断依据。

10. “是否应该提供几页帮助文档，让用户无需登录也能阅读？” → 仅当第 9 题的答案是正式落地页时才询问——也就是面向陌生用户开放注册的产品，尤其是收费产品。个人工具只有一个已经知道如何使用它的用户，而内部工具的文档通常只是一条发给三位同事的消息；这时提问只会让对方同意一件没人会读的东西。不要问、不要构建，也不要提及。 → 默认答案是否。说明选择“是”的实际成本：需要编写四到六篇简短页面，并且每次界面改动后都要确保内容仍然准确。如果对方想要，就根据他们已经提供的信息，说出你会撰写哪些页面——“入门指南、工作原理、套餐与账单、连接 Claude”——这样他们同意的是具体内容，而不是笼统的文档概念。

11. “搜索引擎和 AI 助手是否应该能够找到这个应用？” → 仅当应用面向公众时才询问：比如供用户注册的产品，或以内容为核心的网站。对于个人或内部工具，不要询问。用一句话说明你会改为做什么：“没人需要找到这个应用，所以我会为浏览器标签页设置一个合适的名称，并让它不出现在搜索结果中”——这就是要交付的内容，而不是不做任何事。 → 适用时，默认答案是是，而且成本很低：添加站点地图、robots.txt、llms.txt，以及用于分享链接时显示的预览卡片。如果上面关于文档的问题答案是“是”，要提到这些页面也会被编入索引——对大多数产品来说，人们实际搜索的主要就是这些页面。 → 还有一个子问题，且仅适用于应用的内容本身就是产品时（例如博客、目录）：是否允许 AI 爬虫使用这些内容进行训练。搜索和引用爬虫是另一回事，值得允许——这样助手才能附上链接来推荐这个应用。references/seo.md 对两者作了区分。

12. “应该是什么样子？” → 向每个应用提问，并且放在最后问——只有了解应用是什么之后，提出方案才有价值；个人工具和产品一样，也值得拥有自己的设计视角。这是唯一一个影响所有屏幕的回答。 → 一口气说出三种回答方式，因为人们不知道哪些方式可行：“你可以随意描述——‘平静简约’、‘看起来像 Linear’、‘温暖，像纸张’。也可以贴上你已有的内容——品牌色、字体、完整的设计文档、风格指南。或者说‘你来选’，我会给你提个方案，你再否决。” → 如果他们贴上了内容，就完全以此为准——颜色、字体、间距、语气、组件规范，所有内容都按原样使用，而不是仅作灵感参考。若其中没有涵盖应用所需的某些内容（通常是深色模式或圆角），就按照其风格补足，并说明哪些部分是你补充的。 → 如果他们用文字回答，就把它转化为具体决策，而不是形容词。“平静简约”可以落实为指定的中性色基底、一个强调色、宽裕的圆角和特定字体——这样他们纠正的是具体内容，而不是认同一种氛围。 → **如果他们说“你来选”，就直接提出方案，不要再问一次。**给出两三个有明确名称的方向，每个用一行说明，并根据应用本身来构思：开发者工具、儿童阅读记录器和发票应用不该长得一样。推荐其中一个。references/design.md 介绍了如何选择。 → 无论采用哪种方式，答案都会在步骤 4 中成为项目根目录下的 DESIGN.md，之后构建的每个页面都必须遵循它。

步骤 2 — 获取当前事实

分支已选定，现在要了解当下构建它们实际涉及什么。分两步，按此顺序进行：**先安装这些库的维护者发布的技能，再只研究这些技能尚未解答的内容。**反过来做，会浪费一轮研究，重新发现只需安装一下就能知道的内容。

步骤 2a — 安装官方技能

shadcn、Vercel、Better Auth 和 Anthropic 都为自己的库发布了 Agent 技能。这些技能由 API 的提供方编写并持续更新，涵盖了本次构建的大部分内容——组件、React 和 Next 模式、登录、AI SDK、MCP 工具。跳过这些技能的 Agent 会在构建时花时间寻找其实已经在磁盘上的文档，最后还可能找到针对旧版本编写的博客文章。

在下面的调研和构建清单之前，全局安装整套技能。 全局安装——使用 -g——有两个原因。用户当前所在的文件夹即将变成应用目录，而 create-next-app . 拒绝在非空目录中运行；如果按项目安装，就会在其中创建 .claude/ 和 skills-lock.json，导致每次构建都得想办法绕开。并且，这些是针对固定技术栈的文档，而不是某个应用专用的：安装一次后，它们就能用于下一个应用，也能用于之后打开这个应用的每个会话。

先用一句话说明你要做什么，因为连续安装六项会有明显的停顿：“在规划之前，我先把这些工具背后的团队发布的说明手册拉取下来——这样之后就不用猜他们的文档了。”然后运行安装命令。

npx skills add https://github.com/shadcn-ui/ui --skill shadcn -g --agent claude-code -y
npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices -g --agent claude-code -y
npx skills add https://github.com/vercel-labs/agent-skills --skill deploy-to-vercel -g --agent claude-code -y
npx skills add https://github.com/better-auth/skills --skill better-auth-best-practices -g --agent claude-code -y
npx skills add https://github.com/vercel/ai --skill ai-sdk -g --agent claude-code -y
npx skills add https://github.com/anthropics/skills --skill mcp-builder -g --agent claude-code -y

--agent claude-code -y 可让每次安装都以非交互方式进行；两个标志缺一不可，否则命令会停在提示处，等待无人作答。即使某个分支没有被选中，也要安装全部六项——在被读取之前，它们不会产生任何影响；而两个针对特定分支的技能，正是用户在添加 AI 或 Agent 访问权限时会需要的。

即使某些技能已从之前的应用安装过，也要运行全部六项。 重新添加是刷新，不是重复安装，而且比检查更省事。不能因为之前运行过这项技能，就假设它们已经安装——构建时要从磁盘读取，而不是凭对上次的记忆。

不会有任何内容写入项目。它们会安装到用户自己的 ~/.claude/skills/ 下，因此步骤 4 搭建的文件夹会保持为空，create-next-app . 也能正常运行。

各技能的用途：

技能	何时阅读
shadcn	添加、组合或设置任何组件的主题时——references/stack.md、pages.md、settings.md、docs.md
vercel-react-best-practices	编写任何 React 或 Next 代码时：服务端组件与客户端组件、数据获取、表单、缓存，以及步骤 5 中的真实页面
better-auth-best-practices	阅读 references/auth.md，以及之后所有扩展 src/lib/auth.ts 的内容——支付、Agent 访问权限、设置
ai-sdk	阅读 references/ai.md
mcp-builder	阅读 references/mcp.md——工具设计、命名，以及工具返回的内容
deploy-to-vercel	构建期间不用。安装它是为了步骤 8 的交接，以及之后负责部署应用的人

技能与参考文件不一致时的优先级。 与下方调研采用相同的划分。官方技能在 API 细节和其自身库的惯用方式上优先——名称、签名、导入、选项、使用哪个 Hook、哪个组件，以及当前推荐的模式。本技能的参考文件在组件如何接入此应用方面优先——各文件负责的内容、如何对接架构、会话、日志和设置区域。若参考文件手动实现了官方技能提供的一流方案，就采用技能中的方案并删除临时实现，然后在交接时说明。

技能不会决定范围。 官方技能可能会热心地推荐某项功能、某个提供方或额外的软件包。应用包含什么由步骤 3 决定，并与用户达成一致；不能因为技能热心推荐就扩大范围。

步骤 2b — 检查还缺什么

本技能刻意不指定任何版本——版本由这一部分确定。它只需要一轮并行子 Agent 调研，就能避免代价高昂的失败：满怀信心地基于已经变更的 API 构建应用。 对每个选定的分支各派出一个子 Agent，并在同一条消息中一次性派出，让它们同时运行。 只研究访谈选中的分支——如果应用不收款，研究支付就毫无意义。基础项目、数据库、页面步骤和可发现性始终算作分支。

为每个分支提供相同的任务说明，填入各自的包名；如果第 2a 步的表格为该分支指定了技能，还要提供技能路径：

如果此分支指定了 <skill> 技能，请先阅读该技能——它安装在 ~/.claude/skills/ 下，是维护者自己的文档，优先级高于搜索到的任何内容。只研究技能未解答的内容，并标明哪些发现来自技能。然后：查找 <packages> 的当前稳定版本。报告：每个包的最新稳定版本；最近两个主版本内弃用、更名、移至其他包或移除的内容；此参考文件使用的 <the specific things this reference file uses> 的当前导入路径和函数签名；自此之后新增、可取代 references/<file>.md 中手写代码的任何功能；以及可能导致其中内容失效的迁移说明。优先查阅包自身的文档和变更日志，而不是博客文章或搜索摘要，并核实注册表上实际发布的内容，而非仅依据文档页面的说法。明确说明哪些内容已通过一手来源核实，哪些是推断得出的。

Agent 访问分支需要在任务说明中额外加上一句，因为它所涉及的变动不只发生在包上：确定当前 Model Context Protocol 规范的修订版，并根据该修订版的变更日志和弃用功能注册表，检查 references/mcp.md 中的假设。 即使没有任何包更名或签名变化，协议修订版也可能弃用文件所依赖的内容，而上述任务说明会完全漏掉这一点。其他分支都不依赖于版本独立于库发布的规范。

可发现性分支不安装任何包，而是研究相关惯例，因此请为它提供单独的任务说明：确认 Next 当前对 sitemap、robots 和 opengraph-image 的 MetadataRoute 文件约定；并且——仅当应用需要被发现时——确定 AI 爬虫当前使用的用户代理标识，按训练、搜索／引用和用户主动发起分组；确认 llms.txt 是否已超越提案阶段，发展到有具名爬虫文档说明会读取它的程度。爬虫名称可能随时变化；在 robots.ts 中写错名称不会报错，只会让规则悄无声息地匹配不到任何内容。

每个参考文件顶部都有 Last verified 日期。根据日期安排核查工作：最近核实过的文件只需确认一遍，已于一年前核实的文件则应假设已有内容发生变化。

然后，在安装任何内容之前，先进行协调：

• 仅使用最新稳定版。 不使用候选版本、Beta 版、next 或 canary 标签——除非用户明确提出，并且知道原因。
• 有新功能就使用新功能。 参考文件有时会手动实现某些功能，因为当时库还做不到。如果现在可以了，就使用内置功能并删除变通方案——references/mcp.md 会明确指出最可能需要这样做的地方。
• API 细节以调研结果为准；各部分如何配合则以本技能为准。 名称、签名、导入路径、选项、标志：采用调研发现的内容。各部分分别负责什么，以及它们如何与应用的其余部分连接：参考文件说了算。大多数参考文件会在开头针对其依赖重申这一分工。
• 如果调研结果与已安装的技能不一致，请先判断分歧的类型。 对于当前发布的内容——版本、已拆分的包、已更改的签名——以注册表为准，采用调研结果，因为技能是文件，而文件会过时。对于多个都可行的模式该选哪一种，以官方技能为准；这是库作者对自家库的说明。如果技能描述的内容已被注册表标记为不存在，请在交接时说明——值得知道维护者的技能已经过时。
• 如果参考文件中的方案现已弃用，就采用替代方案并用它完成工作。不要折中。
• 只有在发生变化时才告知用户。 用一句简洁的话说明：“Better Auth 自本文写成以来已将其移至单独的包——我会使用新的包。”绝不要叙述调研后发现一切正常的过程；那只是凑字数。
• 记录过时内容。 调研结果中凡是与之矛盾的内容，都应在最后的交接说明中列出，以便修正本技能。

第 3 步 — 制定方案

在动手之前，用通俗的话重述计划。示例格式：

我将为你搭建：“TrailLog” — 一款只属于你的徒步日志。

**它会记住什么：**徒步记录 — 日期、路线、距离、感受和照片。 **你可以做什么：**记录徒步、稍后编辑、删除记录，按时间倒序查看。 **登录方式：**邮箱和密码，因此只有你能访问。 **外观：**宁静的户外风格 — 暖白色背景、深绿色点缀、柔和的圆角，以及用于标题的衬线字体。设计会记录在 DESIGN.md 中，确保每个屏幕风格一致。 **照片：**开发期间保存在项目中；部署时会迁移到云存储。 **通过 Claude 使用：**你可以直接在 Claude 中记录徒步，或询问过往记录，无需打开应用；还可以在应用内查看并撤销该访问权限。 **还包括：**一个设置页面，可更改密码和删除账户；以及一个系统页面，显示已配置的内容和发生的情况。 **法律事项：**无需处理 — 只有你自己使用，而且这里不会追踪任何人，因此不需要隐私政策、服务条款或 Cookie 横幅。 **搜索发现：**无需索引 — 只有你自己使用，因此我会为浏览器标签页设置合适的名称，并让它不出现在搜索结果中。 **第一版不包含：**与朋友分享徒步记录、地图和统计页面 — 等基础功能合适后，这些都很容易添加。

这样可以吗？

请写明数据模型和明确的第一版不包含清单 — 这两项能避免之后重做。法律事项这一行无论如何都要写，而且要用陈述句，而不是提问：此示例说明了无需处理的内容及原因；如果是面向公众的产品，则应写明需要哪些页面。由 references/legal.md 来确定。搜索发现这一行也无论如何都要写；此示例展示了更难处理的情况 — 即使应用刻意不出现在搜索结果中，也仍要写明，因为只写“无 SEO”会显得像是遗漏了什么。面向公众的产品则应写明需要哪些内容：站点地图、robots.txt、llms.txt，以及用于分享链接的预览卡片。只有在文档相关问题已提出且答复为“是”时，才写帮助页面这一行；并且要列出具体页面，而不是笼统承诺提供文档。每份方案都要包含外观这一行，这也是以较低成本修正设计的机会：写明具体决策 — 背景、点缀色、圆角、字体 — 而不是只写氛围，因为“简洁现代”这种说法谁都不会反对，因此也就没有明确达成共识。如果对方提供了设计系统，要说明会使用他们的设计系统，并指出你需要自行补充的内容。还要提及任何需要对方提供、项目才能正常运行的事项（如 Docker 正在运行、API 密钥、电子邮件域名或服务商账户），避免开发过程中出现意外。

取得明确同意。对方有异议时，做相应调整。如果答复重新讨论的是应用是什么，而不只是调整细节，就回到第 1a 步 — 现在处理比数据模型建好后再处理更省事。

第 4 步 — 搭建骨架

按顺序完成以下事项。每份参考资料都有一个 Verify 部分 — 进入下一步前必须完成。它们是你在过程中进行的自查；第 6 步才是必须通过命令验证的部分。其中所有路径都相对于当前工作目录。

**第 2a 步安装的技能要与这些文件一起阅读，而不是等构建失败后再读。**那里的表格说明了每项技能应配合哪些步骤使用：shadcn 和 vercel-react-best-practices 适用于几乎所有步骤；从登录开始使用 better-auth-best-practices；ai-sdk 和 mcp-builder 则用于各自对应的步骤。编写相应文件的代码之前，先阅读相关技能。搜索网上已有的答案，而这台机器上已经安装了相关技能，正是本步骤要避免的浪费。 从步骤 2 开始，DESIGN.md 将决定这些步骤构建的每个界面的样式——设置区域、邮件、同意界面、法律页面和文档。它们都不会重新决定应用的外观，也不会在组件中写入颜色、字号或圆角半径。

1. 基础项目 → references/stack.md
2. 设计系统 → references/design.md（始终执行；写入 DESIGN.md、主题令牌、AGENTS.md 和 CLAUDE.md）
3. 数据库（SQLite 或 Docker 中的 Postgres 分支）→ references/database.md
4. 登录（如果选择；邮箱+密码，可选 Google）→ references/auth.md
5. 邮件（如果选择）→ references/email.md（如果执行了登录步骤，还会接入验证和密码重置）
6. 文件上传（如果选择）→ references/storage.md
7. 付款（如果选择）→ references/payments.md（需要登录）
8. AI 功能（如果选择）→ references/ai.md
9. 后台任务（如果选择）→ references/jobs.md
10. 落地页和控制面板 → references/pages.md
11. Agent 访问（如果选择）→ references/mcp.md（需要登录）
12. 公共文档（如果选择）→ references/docs.md（很少执行；仅适用于用户提出且确认需要公共文档的产品）
13. 法律页面和 Cookie 同意，按应用需要的程度处理 → references/legal.md（由我们决定，绝不询问；通常无需处理）
14. 账户设置 → references/settings.md（需要登录；只有在没有登录功能时才跳过）
15. 系统可见性 → references/ops.md（始终执行）
16. 可发现性 → references/seo.md（始终执行，但对大多数应用来说，这意味着设置真实标题并避免被搜索到）

**设计系统排在第二位，紧接着脚手架之后，因为后续每一步都会读取它。**它需要项目已经存在——它要编辑的是 globals.css 和 layout.tsx——而且必须在构建任何界面之前就绪，因为事后再把主题应用到已编写的页面上，就意味着要逐一修改所有页面。这里也会写入 AGENTS.md 和 CLAUDE.md，因此后续每一步以及今后打开此项目的每个 Agent 都会遵循同一份文档。

其余步骤的顺序也很重要：付款、文件上传和 Agent 访问都会扩展登录步骤构建的内容；页面步骤需要前面的功能全部就绪；设置和系统可见性则依赖页面步骤创建的导航。Agent 访问排在页面步骤之后，因为它的同意界面必须与应用的其他部分风格一致；它又排在其余步骤之前，因为每个步骤只有在 Agent 访问已执行时才会添加相应版块。接下来是文档，因为它只能描述已存在的分支；它还必须先于法律页面，这样法律页面检查页脚时才能看到文档链接。法律页面排在所有功能分支之后，原因正好相反——隐私页面必须说明所有这些功能；它又排在设置之前，因为只有在构建了横幅时，设置中才会添加 Cookie 偏好版块。任何会修改 src/lib/auth.ts 的操作，都意味着要重新生成 Better Auth 架构并再次运行 db:generate + db:migrate——参考文件会说明具体位置。

**可发现性排在最后，因为它是唯一必须了解每个公共页面的步骤。**它会根据同一个列表生成站点地图和 llms.txt，而法律页面和文档都会向列表中添加页面——如果提前编写站点地图，一旦它们执行完就会出错。

最后三个步骤并不是时间紧张时可以省略的润色工作。其中两个能让脚手架变成用户可实际使用的应用，第三个则决定了是否有人能找到它。

步骤 5 — 让它真正属于用户

这不是润色，而是大部分价值所在。步骤 4 搭建的脚手架只是基础设施；在这里，应用才会真正呈现出用户自己的特色。

• 用用户的想法为项目命名（包名、页面标题、可见品牌）。
• 数据库表采用步骤 1a 中的名词，每张表都有 UUID 主键，并应用步骤 1b 中的所有权规则——添加 userId 列（类型为 text，与 Better Auth 匹配）；如果数据是私有的，则每个查询都必须限定到对应用户。
• 构建真正的页面：references/pages.md 中的入口页和仪表板、真实的导航，以及步骤 1a 中接入的动词——如果差距检查表明需要，还要包括编辑和删除。这是应用中 React 最密集的部分，也是 vercel-react-best-practices 发挥作用的地方——服务端组件与客户端组件的选择、数据的获取位置，以及表单的功能。使用 shadcn 组件组合界面，而不是手写近似的标记；并按照 DESIGN.md 构建——设计决策已经做出并达成一致，因此这一步应将判断力用于应用本身，而不是再次挑选颜色。
• 不要填充通用内容：每一处可见文本都应该符合用户的应用。不要出现 “Item”、“Welcome to Next.js” 或 lorem ipsum。这包括设置区域、电子邮件、法律页面、任何文档，以及浏览器标签页——一个叫 “Notifications” 的版块列出应用从不发送的通知类别、一封署名为 “My App” 的电子邮件、一个每个其他页面都写着 “hikes” 的应用却使用谈论 “user-generated items” 的隐私政策，或者仍显示 “Create Next App” 的标签页，都和满屏 lorem ipsum 一样，属于同一种失败。
• 只构建此应用实际需要的设置版块。一个空的 Billing 标签页，或一个不发送电子邮件的应用却设置了 Notifications 标签页，都不如缺少它们。
• 如果选择支持 Agent 访问，工具也要以动词命名——用 log_hike，而不是 create_item；工具数量只需满足用户实际会提出的少数几种需求，不要每张表都配一个工具。
• 完成标准：用户打开应用就能知道它是什么，无需别人解释；用户也能从头到尾完成应用存在的主要用途。

步骤 6 — 验证

应用已经构建完成，但还没有任何证据证明它能正常工作。你刚完成的每个验证部分，都由编写受检代码的同一个 Agent 确认过；记忆不等于证据——即使应用满足了所有这些要求，也可能无法编译。

references/verify.md 列出了要运行的命令：类型检查、架构漂移检查、构建、lint、以生产模式运行应用、检查每个路由是否都能响应、用两个账户互相测试，以及检查移除密钥后的应用。逐一查看每条命令的输出。编写了命令要测试的代码，正是运行该命令的理由，而不是跳过它的理由。

有两点必须特别说明，因为任何一点做错都会造成损害：

• 先检查架构，再构建。 build 会先运行 db:migrate，所以如果还有未生成的架构改动就开始构建，就会执行无人审阅过的 SQL——这正是 references/database.md 明确禁止的事，却被本该用于发现问题的步骤执行了。
• 用户必须先注册，之后才能创建任何探测账户。 创建的第一个账户会成为管理员。如果测试数据抢先占用了这个位置，之后又被删除，用户就会被锁在自己的系统页面之外。

如果某项检查需要浏览器、服务提供商或人员协助，references/verify.md 会列出相关要求。请注明哪些检查无法运行。

步骤 7 — 用全新视角审查

门禁能证明应用可以构建、提供服务并响应请求，却无法判断应用是否真的能做事——一个空项目也能通过其中的每条命令，因为无物可泄漏时就不会发生泄漏。因此，最后一项检查必须由构建者之外的人来完成。

在一条消息中派出所有评审者，让他们同时开始工作，方式与步骤 2 相同：始终检查是否信守承诺，以及是否符合他们的风格；凡是涉及登录的地方，都检查所有权；根据已运行的分支调整可操作性。评审说明见 references/verify.md。

他们只根据步骤 3 的构建说明检查应用。 这份说明是唯一的标准，因为它是用户真正批准的内容——他们批准的是对应用的描述，却无法阅读交付给他们的代码。弥合这道落差就是全部工作。评审者只报告应用与说明不符之处；绝不提出另一份说明。任何会改变应用本质的内容，都留到交接时交由用户决定，就像步骤 3 时一样。

他们阅读的是证据，而不是正在运行的应用。四个 Agent 无法共用一个端口或浏览器，因此要在步骤 6 期间一次性采集所有证据并交给他们。发现的问题分为 broken、missing 或 worth knowing；现在只修复前两类，且任何修复都不能扩大门禁范围或改变范围。

最多进行两轮，然后停止并报告剩余问题。 第三轮往往会让 Agent 开始修改自己并不理解的代码，只为消除报告中的问题。用一句话告知用户此步骤正在进行——否则他们只会看到终端毫无动静。

步骤 8 — 交接

• 列出所有无法运行的检查，以及完成这些检查所需的条件——浏览器、域名、支付密钥等。整理成一份简短清单，让他们打开应用后能在一分钟内逐项处理。步骤 7 后仍未修复的发现，以及任何你不同意的发现，也放在这里，每项占一行并说明原因。
• 如果步骤 2 的调研结果与实际情况相矛盾，或任何参考命令需要临时修改，就在末尾说明——指出哪个文件、哪里有误——以便修正这项技能。用一行告诉用户；他们可能就是负责修正的人。
• 法律分支：清楚直白地说明一次，隐私政策和条款页面是根据应用实际行为整理出的初稿，不构成法律建议。然后简短列出 src/lib/legal.ts 中只有他们才能填写的字段——通常是联系地址和条款适用的法律——让他们能在一分钟内处理。如果没有 Cookie 横幅，说明原因以及什么情况会改变这一点，用一行写明：“这里没有追踪任何人，所以无需征求同意——以后添加分析功能时就需要了。”
• 提升可发现性，但不公开到搜索：指出开关所在的两个位置——src/app/layout.tsx 中的 robots: { index: false } 和 src/app/robots.ts——并说明如果应用将来公开，应该修改这里。在已上线的产品中保留这些设置，会让他们失去所有预期访客，而且毫无迹象可察。
• 提升公开可发现性：明确说明，站点地图是邀请，不是排名保证；llms.txt 是一种提议中的约定，没有主要 AI 爬虫承诺会读取它；而爬虫实际获准执行的操作，完全由 robots.txt 决定。只需提示他们查看一次预览卡片——它展示了分享链接的样子，也是别人评判应用时最先看到的内容。
• 文档分支：说明页面数量，并指出这些内容目前都属实，因此也最容易过时。如果某个页面因为需要解释流程而难以编写，就指出是哪一页——这是应用本身的问题，不是页面的问题。
• 用一行说明：本次构建使用了维护者自己的技能，包括 shadcn、Vercel、Better Auth、AI SDK 和 MCP 的技能；这些技能在步骤 2a 安装了一次，现在这台机器上的每个项目都能使用，并可通过 npx skills update -g 更新。应用自身的文件夹中没有添加任何内容。指出 deploy-to-vercel 是唯一尚未使用的技能：等他们准备好时，它会负责将应用部署上线。
• 最后用通俗易懂的语言总结：如何启动应用（如果 Postgres 在 Docker 中运行，则包括 pnpm db:up）、.env 中每个条目的用途，以及两到三个合理的后续步骤。
• 用一行提示他们查看 DESIGN.md：其中记录了应用的视觉风格，AGENTS.md 和 CLAUDE.md 会引导各个 Agent 查看它；在该文件和 globals.css 中更改颜色，就能一次性调整所有页面的样式。说明哪些部分由他们提供，哪些是你提出的——这些内容最可能需要修改。
• 向他们展示系统页面并说明其用途。它能回答“为什么那封邮件没有送达？”和“它还在运行吗？”，而他们不会自行找到这个页面。
• 如果本地环境与生产环境不同，就清楚说明一次性切换项：为上传内容连接 Blob 存储，将 POSTGRES_URL 指向托管数据库，把支付密钥从测试模式切换出来，在域名验证完成后添加 Resend 密钥，添加 Inngest 密钥并同步应用，将 BETTER_AUTH_URL 指向实际域名，以便为该域名签发 Agent 令牌，并将 APP_URL 设为同一实际域名，避免站点地图、规范链接和预览卡片中出现 localhost。每项都是托管平台上的设置，无需修改代码——请明确说明这一点，因为人们往往以为这部分很难。另有两项需要在托管平台之外操作：在 DNS 中验证电子邮件域名，以及首次部署后将应用与 Inngest 同步；请明确指出这两项。