設計歷程：規格驅動開發・Eric 老師

開場

老師的話

透過SDLC(軟體開發生命週期)來探討n8n workflow，進行設計前的探索到提案與規格確定。即可明確整個完整的n8n workflow順暢。接下來再來透過AI Agent進行task設計。可確保n8n工作流的完整性與正確性。這一段影片敘述如何進行具有事前規劃的workflow設計步驟與概念。尤其是n8n workflow node會進行許多外部的API Connector或者是進行MCP Function calling，這些如果都採用節點進行相關設定，卻沒有整個專案的外部組態配置管理?維護工作流將會產生若干的問題。另外關於CI/CD架構與維運的問題，是否可以被確保? 這設計步驟影片給大家參考看看。

影片 13 分鐘，在 YouTube 開啟。下面照影片順序整理，圖都取自影片的投影片，點圖可以放大。

第 1 節

規格驅動開發：先寫檔案，再寫程式

這個做法叫規格驅動開發（Spec-Driven Development，SDD）。AI 拿到需求不會馬上寫程式，而是先把幾份檔案寫清楚，每份只回答一個問題：

檔案	回答的問題
提案	為什麼要做、要改變什麼、明確不做什麼
規格	系統對外看得到的行為
設計	怎麼做、為什麼這樣做、捨棄了哪些方案
任務清單	步驟，還有每一步怎麼驗證做完了

規格驅動的設計流程：一句需求→探索→提案→規格與設計→任務→實作→驗證 — 一句口語需求 → 探索 → 提案 → 規格／設計 → 任務 → 實作 → 驗證。

為什麼要這麼麻煩？AI 寫程式很快，可是方向一錯，錯得也很快。先把檔案對齊，後面實作就是照表操課，每一步都查得到理由。

第 2 節

探索：先查資料，也查實際環境

起點是一段很口語的需求：定期抓台北市 YouBike 資料、存到 Google Drive 的 Ubike 資料夾、打包成 Docker 映像，而且需求裡直接附上了 Google 帳號密碼。AI 做的第一件事不是動手，而是把需求裡的每個假設拿出來檢查。

探索一：資料從哪裡來

直覺會想寫爬蟲，但台北市本來就有公開的 JSON：一千多個站點、約 940 KB、不用金鑰、大約每分鐘更新一次。有現成 API 就不要自己爬，這是第一個決策。

探索二：帳號密碼能不能用

帳號密碼能不能用的判斷圖：密碼不可行、個人 Gmail 的 Service Account 沒有儲存空間、採用 OAuth2 — 密碼：Google 已停用而且有外洩風險；個人 Gmail 的 Service Account 沒有自己的儲存空間，上傳會失敗；只剩 OAuth2。

密碼一旦出現在對話或程式碼裡，就要當作已經外洩、馬上換掉。

OAuth2 授權流程時序圖 — OAuth2 流程：在 Google Cloud 建 Client ID／Secret 放進環境變數 → 在 n8n 按一次「用 Google 登入」由本人同意 → n8n 把拿到的 Token 加密存起來，之後每次排程都用它上傳。程式拿到的是有範圍、可以隨時撤銷的授權，不是你的密碼。

探索三：「最新資訊」怎麼存

最新資訊怎麼存的三個方案比較 — 只留最新沒有歷史；每次都存一天 144 個檔；最後兩個都要：最新檔每 10 分鐘覆蓋、每小時另存一份快照。一份不到 1 MB，一個月約 680 MB，免費 15 GB 可以用一年半。

設計習慣：先問資料要拿來做什麼，再用數字估算成本。

探索四：檢查實際環境

檢查實際環境：n8n 版本、舊容器、埠號 — 映像標 latest 實際是 1.100.1，所以固定版本；主機上的舊 n8n 容器沒有 volume，一刪資料就沒了，所以不動它、另開新的；5678 埠已被占用，改用 5679。

這些都不是事先想得到的，是實際查了才知道。

第 3 節

提案：寫下「明確不做的事」

提案回答為什麼要做：YouBike 資料只有當下狀態、沒有歷史，所以需要一個不用人管的流程把它一直存下來。

提案：明確不做的事 — 不爬網頁、不轉 CSV 也不做分析、不自動刪除舊快照、不動既有的 n8n 容器。

重點：寫出不做什麼，實作的時候就不會越做越多，範圍才守得住。

第 4 節

規格：只寫外部看得到的行為

規格：六條需求 — 6 條需求、15 個情境：定期取得、寫入前驗證、覆蓋最新檔、每小時快照、OAuth2 授權、自動部署。

判斷小技巧：換一種實作方式，外部看到的行為都不變，那段內容就不屬於規格，應該放進設計。所以規格裡看不到任何節點名稱。

寫法：SHALL 與 WHEN／THEN — 需求用 SHALL／MUST NOT 這種不留餘地的字眼寫；每條至少配一個 WHEN／THEN 情境，例如「回應是空陣列時不寫入，執行標為失敗」。每個情境都能直接變成一個測試案例。

一次執行的行為流程圖 — 前四條需求串起來就是一次執行：抓資料（失敗重試最多 3 次）→ 驗證是不是非空陣列，不過關就失敗、不碰任何檔案 → 更新最新檔 → 分鐘數在 00–09 就另存整點快照。

第 5 節

設計：七個決策，每個都寫理由與被捨棄的方案

系統架構圖 — n8n 跑在 Docker 容器裡，對外 5679 埠；volume 放資料庫與加密後的憑證；.env 放金鑰、Client ID 與資料夾 ID；每 10 分鐘抓一次開放資料，透過 OAuth2 寫進 Drive。

決策 D1 到 D3 — D1 直接呼叫 API，逾時 30 秒、失敗重試 3 次。D2 只放一個排程、用分鐘數判斷要不要存快照（兩個排程在整點會同時觸發、重複抓、甚至同時改同一個檔）。D3 驗證不過就丟出錯誤，後面節點全部不跑，舊檔不會被壞資料蓋掉。

一個被修正過的設計：minute < 10

設計修正：minute 等於 0 改成 minute 小於 10 — 探索階段的草稿寫「分鐘 == 0 才存快照」。設計階段再檢查一次發現：排程不一定準時，n8n 忙或容器剛重啟，整點那次可能晚一分多鐘，這樣那個小時的快照就漏了。改成「分鐘 < 10」能容許延遲，每 10 分鐘跑一次，每小時也剛好只有一次落在這個範圍。

決策 D4：搜尋後更新或建立 — D4 最新檔先搜尋、找到就更新內容（檔案 ID 不變，分享連結永遠有效）、找不到才建立。捨棄「把檔案 ID 記起來」：檔案一被手動刪掉，記住的 ID 就失效，流程會一直失敗。小坑：搜尋節點要開「永遠輸出資料」，不然第一次找不到檔案流程就停住。

決策 D5：固定 ID 對應憑證 — D5 工作流是用 ID 找憑證的。憑證如果事後才在畫面上手動建，ID 對不上，得一個一個節點重新連。所以兩邊都用固定 ID，憑證骨架只放佔位字串，真正的值啟動時才從環境變數帶進來；工作流一匯入就對上憑證，使用者只要按一次授權。

決策 D6、D7：容器啟動流程 — D6 憑證只在第一次啟動匯入（volume 裡放一個標記檔判斷），工作流每次啟動都匯入並啟用——同一個 ID 的憑證再匯入一次會把已授權的 Token 蓋掉。D7 映像固定版本不用 latest，每次建出來的結果才會一樣。

風險與緩解 — OAuth 同意畫面停在「測試中」，Refresh Token 七天就過期，流程跑一週突然授權失敗 → 發布成正式版，這一步直接列進任務清單。加密金鑰一遺失，存好的憑證就解不開 → README 提醒一定要備份。

第 6 節

任務清單：六組二十四項，每項都寫怎麼驗證

任務：六組二十四項 — Google 端準備（本人操作 4 項，黃色）→ 專案骨架 3 項 → 憑證與工作流 5 項 → Docker 部署 5 項 → 端到端驗證 6 項 → 文件 1 項。建 OAuth 用戶端要帳號本人操作，AI 沒辦法代勞。

從規格追溯到任務 — 每條需求至少對應一個實作任務和一個驗證任務。例如「寫入前驗證」對應任務 5.4：故意餵一個空陣列，確認最新檔沒被改動。找不到驗證任務的需求，就代表清單有漏洞——這是 AI 自我檢查的方法。

第 7 節

實作與驗證：照設計長出來的工作流

檔案都齊了才進實作。10 個節點的工作流跟設計圖幾乎一模一樣（節點逐一說明見本課第 3 節）。這次抓到 1,807 個站點，快照檔名已經用台北時間算好。

n8n 執行紀錄：每 10 分鐘自動執行都成功 — 執行紀錄：每 10 分鐘自動跑一次都成功；點開 9:00 那次，下面的整點快照支線也亮了——規格裡「整點快照」的情境在真實環境被驗證過。

憑證畫面顯示帳號已連線，Client ID 和 Secret 都從環境變數帶進來，工作流檔案裡找不到任何機密。最後用指令跑 OpenSpec 的嚴格驗證，提案、規格、設計、任務四份檔案都完整。

第 8 節

重點回顧

先探索：查資料來源，也查實際環境，不要憑想像設計。
規格只寫行為，設計才寫怎麼做、為什麼。
每個決策都記下被捨棄的方案，之後回頭看才知道當初在想什麼。
每條需求都要有驗證任務，做完了才有證據。

對照老師提的兩個問題（整理者補充）：
① 外部組態配置管理：這條流程的做法是金鑰、Client ID、資料夾 ID 全放 .env，憑證用固定 ID 的骨架、值在啟動時由環境變數帶入（決策 D5），節點裡不寫死任何設定。換帳號或換資料夾只改 .env，不用進畫面一個一個節點改。
② CI/CD 與維運：映像固定版本（D7）、工作流 JSON 每次啟動都重新匯入並啟用（D6），所以 git 裡的那份就是正本，重建容器結果一樣。再往前一步，可以把 OpenSpec 的嚴格驗證和「空陣列不寫入」這類驗證任務放進 CI，每次改工作流都自動跑一遍才准部署。