应用构建器 是做什么的?
一种可重复的方式,用于将创意转化为已部署、已测试、安全的 Web 应用,适用于任何技术栈。它源于端到端构建一个真实项目的经验(AI 辩论竞技场:Next.js、Drizzle、Better Auth、Vercel、Turso、QStash、Vitest、Playwright),包括过程中犯下的每一个错误。核心(本文件、profiles/、reference/)与栈无关;特定于某个产品或框架的内容位于 stacks/ 中,仅由使用该产品的项目读取。请遵循本流程;不要即兴发挥。
从这里开始(每次会话)
- 查找项目状态。 如果
docs/plan.md存在,请先阅读它:它记录了配置模式、已做的决策以及当前里程碑。从那里继续;不要重复询问已解决的问题。 - 选择模式(仅限新项目)。用通俗语言询问一次:
"您是否希望参与技术选择(代码、托管、数据库),还是由我处理这些,只向您询问应用的功能和外观?"
- 参与 → 读取
profiles/technical.md - 不参与 → 读取
profiles/guided.md将答案记录在docs/plan.md的“我们如何工作”部分。模式决定了提问和解释的方式;流程和下面的质量要求对两者相同。
- 参与 → 读取
- 读取项目使用的栈笔记(见下方“栈笔记”)。
- 读取
reference/process.md并按顺序遵循其阶段。在阶段指向其他参考文件时加载它们,而不是一开始就全部加载。
栈笔记
stacks/ 中每个技术对应一个文件:设置步骤、陷阱以及在真实项目中学习到的修复方法。
- 需要读取哪些: 计划中的“我们如何工作”部分列出了它们(“栈笔记:nextjs, vercel, …”)。在每次会话开始时精确读取这些文件。同时查看项目的清单文件(
package.json、vercel.json、docker-compose.yml…)和用户的操作系统:如果他们使用了某个笔记中未列出的技术,则读取该笔记并将其添加到列表。新项目在确定技术栈时选择其笔记(流程阶段 2)。 - 确保不被遗漏: 项目指令文件(
CLAUDE.md或AGENTS.md,在每个会话中加载)要求在每个会话开始时读取docs/plan.md及其栈笔记,无论请求是什么。否则,从未触发此技能的会话将看不到该列表。该技能位于仓库之外,因此措辞要能优雅降级:计划是自包含的;栈笔记仅在“已安装应用构建器技能”时读取。 - 在采用新服务或库之前, 检查是否存在相应的笔记。
- 新经验归何处: 如果仅在使用某个产品时适用,则放在该产品的笔记中(如果不存在则创建:
stacks/<product>.md,以“当…时加载”开头)。如果在任何地方都适用,则以通用术语放在reference/中,以该产品为例并指向其笔记。示例:“当远程服务断开空闲连接时重试一次”放在reference/lessons.md中;实现该功能的 libSQL fetch 包装器放在stacks/turso-libsql.md中。 - 笔记记录学习时的事实(限制、模型列表、价格),并注明日期:请重新检查。
审计现有项目
当被要求将本技能应用于已存在的项目(或重大变更后)时,不要重新启动流程;而是审计并报告:
- 将
docs/plan.md与templates/plan.md进行比较,列出缺失的部分。 - 逐节检查
reference/quality-gates.md(安全性、弹性、性能(含真实测量和 Lighthouse)、UI 清单、两种主题的可访问性、运营和配额)。 - 搜索代码中
reference/lessons.md和项目栈笔记中的反模式。 - 询问项目从未回答的启动问题(例如账户生命周期、配额滥用)。
- 按优先级报告差距(真正的差距、计划差距、低优先级、已做好的方面),并附带修复建议。所有者拒绝的差距应记入计划的“已接受风险”表。在所有者同意之前,不做任何更改。
不可妥协的要求(两种模式)
- 阶段和里程碑: 按照
reference/process.md中的阶段进行,构建小的里程碑,每个里程碑在下一个开始之前都是可运行、已测试、已演示并已提交的。在启动时与用户商定里程碑列表,并保持其在docs/plan.md中为最新状态。 - 应用按预期工作: 每个里程碑结束时都是可运行的,并在真实浏览器中演示,结果展示给用户。
- 弹性: 每个外部依赖和长时间运行的过程都应有针对“如果它失败了怎么办?”(宕机、缓慢、限速、中途崩溃、重复投递)的规划答案,记录在计划的故障模式表中,在代码中处理,以通俗语言向用户展示,并经过测试。
- 性能: 商定目标(例如,目标受众附近页面响应时间在一秒内),部署后测量;没有明显浪费的工作(未索引查询、不必要的轮询、过大的负载)。
- 质量: 每个里程碑通过
reference/quality-gates.md中的检查点(Lint、类型检查、单元测试、端到端测试、构建、CI、UI 审查清单)。没有已知的重大缺陷被遗留。 - 安全性:
reference/quality-gates.md中的安全检查清单在每个里程碑都适用,而不是作为最终的一次性检查。 - 可维护的设计: 业务规则存在于简洁、无框架的模块中,并附带单元测试;外部服务位于小的接合层后面(一个文件即可切换);计划和 README 保持最新。
- 适当级别的测试: 规则使用单元测试,用户流程使用端到端浏览器测试,任何付费或慢速的外部服务(AI 模型、支付)需要有脚本化的模拟。
- 成本可控: 用户的预算在计划中明确说明;任何可能产生费用的内容都有上限、无需绑定银行卡的免费套餐,或用户自己的密钥。
- 秘密永不通过聊天传递: 用户自己将秘密放入
.env.local和托管平台控制面板中,或通过市场集成注入(见reference/third-party-setup.md)。 - 首先自己验证: 更改或部署后,在向用户报告或要求用户查看之前,先亲自检查结果(浏览器、托管平台的日志和通过 CLI 的部署状态、探测脚本)。仅在需要用户参与时才请求他们:登录、秘密、资金、批准。亲自检查生产环境是发现隐藏错误的方式。
- 诚实的报告: 说明哪些已验证以及如何验证的、哪些未验证、哪些失败了。切勿声称执行了你未运行的检查。
- 验证易变的事实: 价格、免费套餐限制、库 API 和版本在依赖它们之前,应对比当前来源(
node_modules中的文档、官方页面)进行验证,并引用来源。
本技能中的文件
| 文件 | 用途 |
|---|---|
profiles/technical.md | 如何与技术所有者合作:询问什么、决定什么、宣布什么 |
profiles/guided.md | 如何与非技术所有者合作:语言、选择、逐步点击说明 |
reference/process.md | 从启动到移交的阶段,以及每个阶段必须产出的内容 |
reference/quality-gates.md | 完成定义、测试策略、弹性、性能、安全和 UI 审查清单 |
reference/stack-defaults.md | 默认技术栈和架构、预算等级、何时偏离 |
reference/environment.md | 飞行前检查及权限设置,可消除大多数中断 |
reference/third-party-setup.md | 账户、秘密以及以最少手动工作配置托管/数据库/队列 |
reference/lessons.md | 已遇到的具体陷阱及其修复方法,以与栈无关的术语描述。每个里程碑前略读 |
templates/plan.md | 项目 docs/plan.md 的骨架 |
栈笔记(仅当项目使用它们时读取):
| 文件 | 涵盖内容 |
|---|---|
stacks/nextjs.md | Next.js App Router、缓存组件、代理、路由处理程序、服务器操作、React 19 表单、开发服务器 |
stacks/vercel.md | Vercel 托管:区域、环境变量和重新部署、CLI、日志、构建时设置 |
stacks/turso-libsql.md | SQLite/libSQL 与 Drizzle、Turso:设置、迁移、远程读取、空闲连接断开 |
stacks/better-auth.md | Better Auth:邮箱确认、密码重置、账户关联、会话陷阱 |
stacks/upstash-qstash.md | Upstash QStash:本地开发服务器、签名、延迟、调度、配额 |
stacks/ai-providers.md | Vercel AI SDK、Groq、Google AI Studio、OpenRouter(连接流程、免费模型)、Ollama |
stacks/gmail-smtp.md | 通过 Gmail 发送账户电子邮件,无需域名 |
stacks/playwright.md | Playwright 端到端测试:选择器、隐藏页面、本地模拟 |
stacks/github.md | GitHub 仓库、Actions CI、GitHub 登录 |
stacks/google-oauth.md | Google 登录:Cloud 项目、同意屏幕、品牌、本地和生产环境共用一个客户端 |
stacks/windows.md | 在 Windows 上开发:智能应用控制、PowerShell、Docker、CLI 工具 |