AI 當工程師，我當主管

• 第一部　我的 AI Coding 三階段：每一階段都是被前一階段的失敗推出來的
• 第二部　我現在的開發流程

Fitness Expedition 運動 RPG · Codex · Python × Streamlit × Google Sheet

點圖可放大

• 只提供幾個規則說明的 md 檔，前端、後端、資料庫全由 AI 決定，資料庫接 Google Sheet
• 全程用自然語言提需求，沒有任何開發架構與流程
• 結果：畫面粗糙、沒有響應式、功能不齊、錯誤修不完

五個失敗原因

排序有意義——最不重要的那個，正好是當時我以為最重要的那個

規格驅動開發 Spec-Driven Development

• 什麼是 SDD：先把「要做什麼」寫清楚再動手——蓋房子先畫藍圖，不是拿起鐵鎚就開始敲
• AI 為什麼特別需要：上下文長度有限、分段作業，規格就是路線圖
• openspec：給 AI 用的 SDD 標準作業程序，npm install -g ＋ openspec init

案例：JJoy 家庭娛樂記帳 APP

JJoy 家庭娛樂記帳 · openspec · Vue 3 × Supabase × Netlify

自家的娛樂費規則（月預算 ＋ 有運動加 300 元）· 規則明確、規模小 · 不到一天做出來

但還有一個問題沒解決：規格寫得再細，仍有一整類問題是文字描述不出來的。

Google 5-Day AI Agents 課程　課程連結（免費，有興趣可以自己上）

三段光譜：差別不在有沒有用 AI

管理 context window ＋ Matt Pocock 的 Skill

• 對話變長之後，模型在後段的判斷品質會下降 → 工作單位要切到「一個全新對話裝得下」
• 命名會影響流程：決策卡與任務卡混用，整套流程會跟著偏掉

我現在的 dev skill，骨架來自這幾個 skill（點開看說明）。順序不能顛倒：grill → to-spec → to-tickets

把踩過的坑固化成標準作業程序

• 每個階段都有核准關卡——AI 不能自己往下一關走
• 工作單位是「一個全新對話裝得下」——避免中途遺失前面的決定
• 做成 Skill 而不是寫在提示詞裡：屬於動態 context，需要時才載入

為什麼從 openspec 換成自己這套

• openspec 的文件層數太多，小案子光是文件作業就佔掉半天
• 現在收成兩層：SPEC.md 一本總帳 ＋ changes/{功能}/delta.md 差異規格
• 入口也簡化：小軟體直接 grill 後開工；大軟體先用 wayfinder 釐清架構

動工之前，先把方向定下來，再把需求問清楚

wayfinder：想法太大、方向未定的時候

方向已經清楚、只差寫規格，就直接走 dev-spec。開一張沒必要的地圖只是增加流程成本

霧散了、方向定了，接下來才是把細節問到可以驗收的精確度。

grill：拷問模式

不是我寫需求給 AI，是 AI 反過來把我問到說清楚——因為我不知道自己漏了什麼

結束方式：輸出共識清單（問題 → 決定 → 理由一句），我確認後才動工。小軟體到這裡就能開工。

開案時一次把制度裝好

dev-kickoff：八個步驟

新專案走完整流程；既有專案補掛制度也走同一個 skill，只補缺的部分

專案 CLAUDE.md 的六條紅線

違反任一條就停下來，先取得我的同意

規格只寫行為，而且要先被另一個 AI 審過一輪

規格紀律：只寫行為，不寫實作。實作決策記在 delta 的 Implementation Decisions，那一節永遠不會併進 SPEC.md。

codex-peer-review：為什麼要找第二個 AI

• 規格自審，審不出源自自己假設的缺口
• 規格的缺口會一字不漏變成程式碼的錯誤；在文字這層修正只花幾行字
• Stop hook 硬性把關：規格檔沒蓋審查 marker 就不准收工——靠制度，不靠自律

• 垂直切片：每張卡切穿資料 → 邏輯 → 介面 → 測試的一條窄路，不是先做完整個資料層
• 一個功能通常 2～8 張卡；超過 8 張表示規格太大，該回頭分期
• 拆完就停，不在同一個對話開始實作

每做完一張卡就當場驗，不累積到最後

• 驗收清單不寫成 md，產成 HTML：docs/verify/index.html ＋ data.js ＋ results/
• 雙擊就能開、不用起伺服器、填寫自動存在瀏覽器、可分次完成、最後匯出 JSON
• 整個資料夾進版本控制，這是專案的驗收歷史帳

四個篩選鈕：全部／只看未測／只看高風險、人工必測／只看不通過。逐卡驗收階段，結案鈕是鎖住的，跑完 dev-verify-spec 才解鎖。

找不到證據就填 false，不推測「應該有測過」——這一欄的用途是決定我把時間花在哪。

人工必測｜風險高｜自動化測試 ✗｜AI 驗過 ✗｜跨環境

純看版面（這一項 AI 完全驗不了）。

① 登入頁與「請設定你的密碼」頁：
   欄位寬度、按鈕位置、字級看起來合不合理？把視窗拉窄會不會爆版？

② 人員主檔的操作欄現在一列有四顆按鈕＋一行狀態文字，
   會不會太擠、擠到看不懂哪顆是哪顆？

覺得哪裡不對就寫在備註裡，這種事只有你看得出來。

不通過：三選一

1. 當場修：改動小、在這張卡的範圍內
2. 開新卡：牽涉範圍超出這張卡
3. 延後：對應的規格條文不得合併進 SPEC.md

全部卡做完 → dev-verify-spec

• 三問檢查：漏做／多做（範圍擴張）／做錯
• 跨卡整合驗收：單卡都通過，不代表串起來會正確——這是逐卡驗收唯一的結構性缺口
• delta 合併回 SPEC.md（由我看 diff 核准）→ change 資料夾搬到 done/ 封存

git 是唯一的還原機制，但指令沒人教

顯示目前變更 → 安全掃描 → 規劃 commit 計畫（判斷要不要拆）→ 逐筆 commit → 確認後才 push

37 個修改檔 ＋ 8 個新增檔，建議分成 3 筆。拆分邏輯是按性質分，不是按時間分。

commit 訊息照 Conventional Commits 寫：這是業界通用的規範，格式是 type: 說明文字。好處是讀歷史紀錄時，光看前綴就知道這筆在做什麼，工具也能據此自動產生版本紀錄。

繁體中文、動詞加受詞、30 字以內，說「做了什麼」而不是「為什麼」。

上線前的六項收尾檢查

還有 change 沒收完怎麼辦：卡做完了就引導跑 dev-verify-spec 驗收合併；卡沒做完，就問我要完成還是放棄。放棄的 change 搬到 done/ 並註明「未實作即關閉」，它的條文不得出現在 SPEC.md。

不是二選一，是同一條光譜上的刻度。決定落在哪一端的，是「產出需要被驗證到什麼程度」。

兩個問題就能決定

1. 這東西出錯，誰會受影響？
2. 這東西會存在多久？

右邊那欄的「harness」是什麼

不是提示詞寫得更長，是把「這件事怎麼被做完」整個架起來。對照 Day 1 的 context 分類：靜態的每次都載入，動態的需要時才載入

• 小工具走完整流程 → 流程本身的成本超過它防的風險（所以要有輕量通道，所以方向清楚就不開地圖）
• 正式系統直接 vibe 上線 → 就是第一部那個坑。Vibe Coding 不等於 Vibe 上線

這套流程真正在管的，不是 AI 夠不夠聰明，而是「做完了」由誰認定。

我的文章

• 打造家庭娛樂記帳 APP — Vibe Coding 從零到上線的實踐心得
• Day 1　為什麼你的 AI 比較聰明？關鍵不在模型
• Day 2　幫你的 AI Agent 裝上萬用插頭
• Day 3　Prompt 的下一步：把經驗變成 Skill
• Day 4　Vibe Coding 的陰影：當 AI 開始自己寫程式
• Day 5　Vibe Coding 不等於 Vibe 上線：AI 寫程式，要先寫規格
• Fable 5！來完善我的開發流程吧！

其他來源

• Wayfinder 真正管理的是「現在還不能決定的事」（阿星導讀）
• 別再把時間耗在規格書上，先做一個能丟掉的版本（阿星導讀）
• OpenSpec 讓 SDD 變簡單的三個指令（高見龍）