設定原型專案
從一個想法建立可運作的網頁應用，然後將其分享為一個公開連結。使用者提供方向與判斷；你負責技術工作。
技術棧
| 層級 | 預設工具 |
|---|---|
| 介面 (人們看到的和點擊的) | Next.js (App Router) + TypeScript + Tailwind + shadcn/ui (基礎 UI、中性主題、Lucide 圖示、Sera 風格) 來自一個 shadcn 預設集 |
| 伺服器工作 (密鑰、外部 API、AI 呼叫) | Next.js 伺服器動作 (Server Actions) |
| 資料 | 瀏覽器中的 IndexedDB (Dexie)。已安裝 Supabase CLI 以供後續使用 |
| 託管與分享 | Vercel |
| 設定與自動化 | 官方 CLI (vercel、supabase、gh、shadcn) + 此技能的腳本 |
IndexedDB 優先：無需帳號、無需金鑰、可離線運作。只有在資料必須在使用者或裝置之間共享、應用需要登入功能，或伺服器/排程任務需要讀取資料時，才轉移到 Supabase (請參閱 references/7-extend.md)。
始終使用最新的穩定版 (無需詢問)
- 升級永遠不需要批准，但有一個例外：來自第三方 Homebrew tap 的工具 (例如
supabase/tap)。在信任此類 tap 以及在設定過程中每次從其升級之前，都必須詢問，即使之前已獲批准。 - 否則，將每個 CLI 和套件更新到其最新的穩定版本：
npm i -g <cli>@latest、brew upgrade、winget upgrade、Node.js 目前的 LTS，以及在專案中執行npm outdated --json | jq -r 'keys[] + "@latest"' | xargs npm i。用一句話說明你升級了哪些內容。 - 除非使用者要求，否則永遠不要使用 canary、beta、rc 或
next標籤。不要憑記憶或這些文件來鎖定版本。 - 升級後，執行檢查 (
lint、typecheck、build)。如果其中一個失敗，請閱讀錯誤訊息以找出導致問題的套件，僅將該套件降級到其前一個主要版本的最新版本 (npm i -D <pkg>@^<major-1>)，然後重新執行。在PROTOTYPE.md的「決策」部分記錄鎖定版本及其原因。例如：TypeScript 7 破壞了 ESLint 的 TypeScript 外掛程式，因此鎖定typescript@^6，並保持其他所有套件為最新版。 - 當恢復一個現有的原型時，在開始新工作之前，請執行相同的升級和檢查流程。
建構步驟
在執行到某個步驟時再閱讀該步驟的參考文件。不要一次全部讀完。
| 步驟 | 使用者做的事 | 你做的事 | 參考文件 |
|---|---|---|---|
| 1. 設定 | 選擇一個資料夾 | 檢查工具及其依賴項，安裝缺少的部分，建構應用程式支架 | references/1-setup.md |
| 2. 連接 | 批准，在瀏覽器中登入一次 | 執行每個 CLI 的登入，確認其成功運作，將應用程式金鑰儲存在作業系統的憑證儲存庫中 | references/2-connect.md |
| 3. 規格 | 構思想法 | 提出簡短的來回問題，撰寫 SPEC.md | references/3-spec.md |
| 4. 建構 | 反應，重新導向 | 一次建立一個功能，並展示其運作狀態 | references/4-build.md |
| 5. 測試 | 嘗試使用 | 執行檢查，在真實瀏覽器中測試，修復問題 | references/5-test.md |
| 6. 發布 | 批准，分享 | 同步金鑰到 Vercel，部署，提供連結 | references/6-ship.md |
| 任何時候 | 要求新的功能 | 找到該工具的 CLI 或技能，詢問是否安裝並連接 | references/7-extend.md |
結果：一個在 localhost 上運作的應用程式，然後是一個任何人都能開啟的公開連結。
平台
| macOS | Windows | Linux | |
|---|---|---|---|
| 此技能腳本使用的 Shell | 終端機 (zsh/bash) | Git Bash (隨 Git for Windows 一起提供) | bash |
| CLI 的套件管理器 | Homebrew | winget (Supabase 使用 Scoop) | Linux 版 Homebrew 或 npm |
| 應用程式金鑰存放位置 | 鑰匙圈 (Keychain) | 認證管理員 (Credential Manager) | Secret Service (secret-tool)；否則為被 git 忽略的 .env.local |
- 使用
bash <絕對路徑>執行腳本。在 Windows 上從 PowerShell 或 cmd 執行時，單純的bash可能會啟動 WSL；請改用& "$env:ProgramFiles\Git\bin\bash.exe" <script>。Windows 上的 Claude Code 已經在 Git Bash 中執行其 shell。 - WSL 視為 Linux，但當
powershell.exe可存取時，secrets.sh會透過它使用 Windows 認證管理員。 - 雲端同步資料夾 (Dropbox、OneDrive、iCloud、Google Drive) 沒問題。在 Dropbox 資料夾中，請在建立支架後立即執行
bash SKILL/scripts/ignore-sync.sh <project>，以便 Dropbox 跳過node_modules、.next和測試輸出。
進度檔案
每個原型在其根目錄都有一個 PROTOTYPE.md (範本：templates/PROTOTYPE.md)。它包含步驟檢查清單、工具清單 (工具、版本、全域或專案安裝)、金鑰的名稱 (絕不包含值)、決策和連結。
- 在每個步驟結束時以及每當新增工具時更新它。
- 當在現有原型中被呼叫時，首先讀取
PROTOTYPE.md，並從第一個未勾選的步驟繼續。如果使用者提到了某個步驟 (例如「我們發布吧」)，則直接前往該步驟，但先執行該步驟的檢查。 - 所有步驟都已勾選，但使用者想要新功能：將其新增到
SPEC.md(必須有的功能 + 接受標準) 和PROTOTYPE.md的功能清單中，如果需要新工具則執行references/7-extend.md，然後針對該功能循環執行 建構 → 測試 → 發布。
你執行所有指令
使用者提供方向和批准；你自己執行所有指令。永遠不要要求他們輸入或貼上指令。
- **無需批准：**查閱資料；升級 (見上文)；在使用者要求建立原型後，安裝預設技術棧及其依賴項。用一句話說明你要安裝的內容及原因，然後執行。
- 先詢問 (用一句簡單明瞭的話解釋原因，獲得同意後自己執行；一次同意可以涵蓋所列的一批項目)：
- 登入 CLI
- 更改安全設定，例如信任 Homebrew tap (
brew trust supabase/tap)，以及從第三方 tap 升級工具 - 安裝超出預設技術棧的工具 (
references/7-extend.md) - 創建雲端資源 (Vercel 專案、Supabase 專案、GitHub 儲存庫、市集整合)
- 部署到生產環境
- 鎖定規格並從「規格」階段進入「建構」階段
- 如果使用者的請求已經明確要求一路做到最後 (例如「把它變成一個公開連結」)，這就等同於對建立 Vercel 專案和生產部署的批准。但在執行之前，仍然要用一句話說明你將要做什麼。
當一個指令需要使用者互動時 (瀏覽器登入、驗證碼、管理員密碼)：
- 解釋將會發生什麼以及他們會看到什麼。
- 在他們可以看到並回應的地方執行它：如果你有，在你的 Agent 應用程式的終端機面板 (一個「在終端機中執行」工具) 中執行。為每個登入建立一個以它命名的新分頁 (例如「Vercel 登入」、「GitHub 登入」)；永遠不要重複使用以其他名稱命名的分頁。將終端機面板切換到該分頁 (一個「顯示面板」工具)，並在你的訊息中連結該分頁。如果沒有面板，則為他們打開一個終端機視窗 (macOS：
osascript -e 'tell application "Terminal" to do script "cd <project> && <command>"'；Windows：start "" "%ProgramFiles%\Git\git-bash.exe" -c "<command>; read")。 - 等他們說「完成」，然後自己驗證 (
vercel whoami、gh auth status……)。永遠不要僅憑他們一句話就標記步驟完成。
秘密資訊 (API 金鑰、token)，按以下優先級處理：
- 首選自動化：Vercel Marketplace 整合 (金鑰會直接送到 Vercel，然後
secrets.sh pull-vercel)，或是一個提供者 CLI，其金鑰輸出你可以直接 pipe 給secrets.sh set NAME --stdin。使用者永遠不會看到或貼上金鑰。 - 最後手段是對話框：只有當服務兩者都不提供時，才執行
bash SKILL/scripts/secrets.sh ask NAME "去哪裡找到它"。它會在使用者的螢幕上打開一個隱藏輸入的對話框，並將值儲存在作業系統的憑證儲存庫中；任何內容都不會經過聊天或你的輸出。先告訴使用者將會出現一個對話框以及原因。 永遠不要在聊天中要求提供秘密資訊，永遠不要列印秘密資訊，永遠不要將其寫入程式碼或已提交的檔案中。
你的 shell 工作目錄可能在呼叫之間重置：所有專案指令都以 cd "<project>" && 開頭。長時間執行的指令 (npm run dev) 應在背景執行。
如何與使用者溝通
- 在每個操作之前，用一句簡單的話說明這能為他們做什麼：「正在添加一個瀏覽器資料庫，這樣你的清單就能在訪問之間保存。」
- 在每個步驟之後，用 2–3 行進行總結：現在什麼功能可以用了，他們可以嘗試什麼，下一步是什麼。
- 當有真正的選擇時，提供 2–3 個選項和一個建議。否則，選擇一個合理的預設值並說明你選擇了它。
- 展示，而非描述：在每次可見的更改後，打開
localhost(或截圖)。 - 錯誤：首先自己修復。只有在需要決策、批准、或使用者動手進行登入、輸入密碼或金鑰時，才請他們介入。
捆綁的檔案
scripts/preflight.sh [dir]— 檢查工具、依賴項、已安裝與最新版本、登入狀態、資料夾scripts/secrets.sh— 作業系統憑證儲存 (ask打開隱藏輸入對話框)、使用金鑰執行、匯出.env.local、Vercel 推送/拉取 (help查看用法)scripts/ignore-sync.sh <project>— 告訴 Dropbox 不要同步node_modules、.next和測試輸出scripts/wincred.ps1—secrets.sh使用的 Windows 認證管理員輔助腳本 (不要直接呼叫)scripts/discover.sh <tool>— 初步查詢新工具的 CLI、npm 套件和技能scripts/install.sh— 全域安裝此技能 (回退到專案層級)templates/—PROTOTYPE.md、SPEC.md、AGENTS.section.md、db.ts、actions.ts、smoke.spec.ts、playwright.config.ts
在這些文件中，SKILL 指的是此技能的資料夾，例如 ~/.agents/skills/setup-prototype-project。在執行腳本時，將其展開為絕對路徑：bash ~/.agents/skills/setup-prototype-project/scripts/preflight.sh。
常見錯誤
| 錯誤 | 正確做法 |
|---|---|
| 要求使用者執行或貼上指令 | 解釋、獲得同意、自己執行 (登入時使用可見的終端機)。 |
| 因為使用者說完成了就標記登入為完成 | 使用 CLI 進行驗證 (vercel whoami、gh auth status、supabase projects list)。 |
讓 Dropbox 同步 node_modules | 在建立支架後立即執行 ignore-sync.sh。 |
| 在安裝依賴項之前先安裝 CLI | 遵循 1-setup.md 中的安裝順序 (套件管理器 → git → Node.js → npm CLIs)。 |
憑記憶安裝 (npm i next@15) | 使用 @latest 穩定版；僅在檢查失敗時降級一個套件。 |
| 第一天就使用 Supabase | 從 IndexedDB 開始；當共享或登入成為必要條件時再升級。 |
| 從伺服器組件或伺服器動作 (Server Action) 中呼叫 IndexedDB | IndexedDB 僅存在於瀏覽器中。請在 "use client" 組件中使用它。 |
將 API 金鑰放在 NEXT_PUBLIC_ 變數中 | 任何 NEXT_PUBLIC_ 變數都會發送給每個訪客。將金鑰保留在伺服器端的伺服器動作 (Server Actions) 中。 |
| 在展示任何東西之前建立所有功能 | 一次只建立一個功能，展示其運作狀態，然後再反應。 |
| 未同步金鑰就部署 | 每次部署前執行 secrets.sh diff-vercel。 |
| 排程一個讀取 IndexedDB 的任務 | 伺服器任務無法看到瀏覽器資料。先將資料移至 Supabase (7-extend.md)。 |
| 未登出就提供連結 | 在分享之前，檢查生產環境 URL 是否能公開返回 200 狀態碼 (6-ship.md)。 |
| 未檢查誰發布就從搜尋結果安裝工具 | 優先選擇供應商的官方 CLI、套件或技能。在詢問時顯示發布者。 |