App builder
一個可重複的方法,將想法變成已部署、經過測試、安全的全端網頁應用程式,適用於任何技術棧。這個方法從建構一個真實的端對端專案(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、…」)。在每次工作階段開始時,精確地閱讀這些。同時也要瀏覽專案的 manifest 檔案(
package.json、vercel.json、docker-compose.yml…)和使用者的作業系統:如果他們使用了某個有筆記但計畫沒有列出的技術,請閱讀該筆記並將其加入清單。新專案在技術棧確定後選擇他們的筆記(流程階段 2)。 - 讓它不容忽略: 專案的指令檔案(
CLAUDE.md或AGENTS.md,每個工作階段都會載入)會指示在每個工作階段開始時閱讀docs/plan.md及其堆疊筆記,無論請求是什麼。否則,一個從未觸發此技能的工作階段永遠看不到這份清單。此技能存在於儲存庫之外,因此措辭應優雅降級:計畫是自包含的;堆疊筆記「只有在 app-builder 技能已安裝時」才讀取。 - 在採用新的服務或函式庫之前, 先檢查是否有對應的筆記。
- 新教訓該放哪裡: 如果它只在使用某個產品時才成立,就放在該產品的筆記中(如果沒有則建立一個:
stacks/<product>.md,以「載入時機:…」開頭)。如果它任何地方都成立,就以通用的詞彙放在reference/中,以該產品為例,並指向其筆記。例如:「當遠端服務斷開閒置連線時重試一次」放在reference/lessons.md;而執行此操作的 libSQL 擷取包裝器則放在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中保持最新狀態。 - 應用程式按預期運作: 每個里程碑結束時必須可執行,在真實瀏覽器中展示,並將結果顯示給使用者。
- 恢復力: 每個外部依賴項和長時間運行的程序都必須有一個針對「如果它失敗了怎麼辦?」(當機、緩慢、速率限制、中途崩潰、重複傳遞)的計畫性答案,記錄在計畫的故障模式表格中,在程式碼中處理,以白話告訴使用者,並經過測試。
- 效能: 商定目標(例如:頁面在目標受眾附近於一秒內回應),部署後測量;沒有明顯浪費的工作(未建立索引的查詢、不必要的輪詢、過大的 payload)。
- 品質: 每個里程碑都必須通過
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、Cache Components、代理、路由處理器、伺服器動作、React 19 表單、開發伺服器 |
stacks/vercel.md | Vercel 主機:區域、環境變數與重新部署、CLI、日誌、建構時設定 |
stacks/turso-libsql.md | 使用 Drizzle 的 SQLite/libSQL、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 上開發:Smart App Control、PowerShell、Docker、CLI |