Agentic dev loop

Agentic Dev Loop（系統化開發迴圈）

把開發從「想到就改、改到哪算哪」轉成一條可重複、可中斷續做、可被稽核的迴圈。靈感來自 Matt Van Horn 的 agentic engineering 工作流，但針對單人維護多個含真實使用者資料的專案做了大幅收斂——他沒有合規責任，維護真實使用者資料的人有。

與另三個 skill 的分工（不重疊，是四條正交軸）

本 skill 是編排器，串接 project-guardrails、web-security-reviewer 與 ui-ux-deploy-reviewer。四者問的是不同問題，不要混為一談：

	問的問題	頻率	產出	在迴圈位置
project-guardrails	這專案哪些程式碼牽一髮動全身（改 A 壞 B）？	每專案一次（架構大改重跑）	CLAUDE.md 的「連動禁區」段落	前置（餵進規劃）
agentic-dev-loop 風險分級	這專案碰不碰個資、要多嚴？	每次開工定級	授權強度 + 是否強制 Verify	Step 0
web-security-reviewer	這段碼安不安全、會不會漏個資？	每次上線前	風險報告 + 修正版程式碼	Step 4 Verify（安全閘）
ui-ux-deploy-reviewer	這介面好不好用、呈現層程式碼乾不乾淨？	每次有前端介面的上線前	20 原則問題清單 + 部署放行檢核表	Step 4 Verify（UI/UX 閘）

兩個澄清，避免把它們混在一起：

• 「連動禁區」（程式碼互鎖風險）與「風險分級」（資料敏感度）是兩條不同的軸。一個模組可能高連動但低個資（如計分演算法），也可能低連動但高個資（如寫學員名單的函式）。前者由 project-guardrails 標記、規劃時避開；後者由本 skill 定級、決定授權與驗證強度。
• Verify 的兩個閘刻意不重疊：web-security-reviewer 管安全/個資，ui-ux-deploy-reviewer 管好不好用/呈現層程式碼品質（它自己的 SCOPE 就把安全讓給前者）。兩者都會讀 CLAUDE.md 的連動禁區，所以 project-guardrails 的產出在出口端也被用到。

核心心法（先讀，再進流程）

1. 計畫先行。 除非是一行字就能改完的事，動手前一定先有 plan.md。計畫是「能熬過 session 崩潰、context 流失、隔天才回來做」的存檔點；對話氣泡是金魚記憶，檔案才是白板。
2. 狀態外部化。 把「問題是什麼、要動哪些檔、驗收標準、要遵循的既有模式、目標帳號與專案」全寫進檔案，而不是留在腦中或對話裡。session 死了，指向同一份 plan 就能接著做。
3. 規劃才是高價值工作。 把多數心力放在把計畫想清楚；實作只是把想清楚的事執行出來。一份好計畫值得反覆改三輪，劣質計畫會讓實作來回鬼打牆。
4. 授權強度跟著專案風險走，不是一招走天下。 Matt 全程 bypass permissions；在碰學生個資的 repo 這樣做等於拆掉實驗室的門。本 skill 用三級風險分流（見下）決定授權與驗證強度。
5. 使用者讀自己的計畫。 可以請模型給 TLDR 幫你快速掃，但 TLDR 是輔助、不是替代。這條底線同樣適用於程式碼:AI 是加速器，不取代你的判斷。會上線、會碰資料的計畫，至少自己讀過一遍。

在全域 CLAUDE.md 紀律之下運作（單一紀律源頭）

本 skill 不自創修改紀律，它執行的是 ~/.claude/CLAUDE.md（全域）裡的「程式碼精簡與連動性紀律」。凡涉及怎麼寫、怎麼改、改完交什麼，一律以全域檔為準，本 skill 只負責把它編排進迴圈的對應步驟：

迴圈步驟	對應全域 CLAUDE.md 段落
Step 0 確認連動禁區	§二.1（改動前讀專案 CLAUDE.md、觸及禁區先停下回報）
Step 1 Research	§七 研究先行（確認 API／寫法是當下正確版，依據記進 plan.md）
Step 2 Plan 範圍盤點	§二.2–.3（grep 所有呼叫點；影響>3 檔先回報）
Step 3 Build	§一 撰寫原則 + §二「改動中」（最小 diff、一次一需求、逐一確認呼叫點）；§五 交付就緒（空/載入/錯誤/無效輸入/外部失敗）
Build 出口	§二.7（強制輸出影響範圍清單 + Smoke test 清單，含 §五 未涵蓋項）、§二.8（誠實標註不確定處）
Verify	§六 機密與設定管理（新增讀寫密鑰/個資的路徑 → 安全閘）
Deploy 前	§三、§四（test:smoke / /predeploy；smoke 清單未人工驗證視同未過）+ 交付就緒閘（可觀測性/回滾）

哪裡與全域重複，就以全域為準、本 skill 指過去即可，不重述也不另立一套。

專案風險三級分流（每次開工先定級）

開工第一件事:確認這次動的 repo 屬於哪一級。級別決定後面每一步的嚴格度。

級別	典型專案	授權	部署前安全驗證	帳號確認
🟢 個人 sandbox	my-portfolio（個人作品集）、純實驗 repo	可開 bypass	可選	仍要確認，但風險低
🟡 公開、無/少個資	my-learning-pwa（自學 PWA）	局部授權，敏感操作仍確認	建議（上線前）	必確認
🔴 含個資 / 機構系統	org-registration-system、org-camp-system（營隊系統）、活動座位表（含外賓姓名）、線上測驗系統（含作答結果）、校務管理系統	不開 bypass	強制（未驗不上線）	強制雙重確認

判定規則:只要 repo 會儲存、傳輸或顯示可識別到個人的資料，一律當 🔴——不限學員/學生，外賓、受測者、應徵者同樣算。my-learning-pwa 預設 🟡;若它開始記錄可識別的學習者作答資料（例如綁定身分的 placement 結果），升 🔴。不確定時，往高一級靠。

分級最常被低估的兩類（判準是「資料裡有沒有名字」，不是「專案看起來多正式」）:

• 活動座位表／名單類:看起來只是排版工具,但具名席位揭露的是誰出席、誰與誰同桌。
• 線上測驗／問卷類:姓名＋email＋測驗結果的組合,且報告檔案通常長期留存。

🔴 的理由是具體的:CLC 曾發生個資外洩、走過 PIMS-2-09 與教育部通報流程。這一級的每一步都要把「萬一外洩」當成預設情境來設計，而不是事後補救。

開發迴圈:（前置）Guardrails → Research → Plan → Build → Verify 雙閘 → Deploy

第 0 步:定級、收斂範圍、確認連動禁區

做三件事:

1. 定級——確認這次動的 repo 屬於哪一級（🟢🟡🔴），決定後面的授權與驗證強度。
2. 收斂範圍——確認目標 Firebase 帳號與專案 ID（或 GCP 專案、GAS script）、這次要解的問題。輸入可以是文字需求、GitHub issue 連結、錯誤訊息截圖、會議逐字稿。範圍模糊時先問一兩個關鍵問題，不要腦補。
3. 確認連動禁區——檢查該專案的 CLAUDE.md 有沒有「連動禁區（修改前必讀）」段落。沒有 → 先交棒 project-guardrails 跑一次分析並（經你確認後）寫入 CLAUDE.md，再回到本迴圈;有 → 把禁區清單讀進來，作為規劃時的避雷依據。交棒方式見 references/handoffs.md。

第 1 步:Research（研究先於規劃）

動筆寫計畫前，先補齊「當下」的外部知識，避免用過時的內建知識做決策:

• 用 web 搜尋 / /last30days 類研究掃過 Reddit、X、官方文件、近期討論，特別是要選型時（例如某套件 vs 另一套件、某 Firebase 功能的現況）。
• 讀目標 repo 既有的模式與慣例（命名、資料夾結構、過去的 plan.md 與 bug 紀錄）。
• 把研究結論濃縮成幾條「決策依據」，準備餵進計畫。 研究不足就直接寫計畫，是這條迴圈最常見的失敗點。

第 2 步:Plan（產出結構化 plan.md）

依 references/plan-template.md 的模板產出計畫。一份合格計畫至少包含:問題陳述、採用方法與理由、要動的檔案清單、驗收標準（怎樣算做完）、要遵循的既有模式、目標帳號/專案/部署目標、風險級別、以及這一輪要不要走 Verify。 特別檢查:這次要動的檔案，有沒有踩到 CLAUDE.md 連動禁區裡的模組? 有 → 在計畫裡明確標出受影響的「被依賴方」，並把「驗證這些下游沒被弄壞」寫進驗收標準。 計畫存進該 repo 的 plans/ 或 docs/plans/，檔名帶日期與主題。這份檔案是後續所有步驟的單一事實來源。

第 3 步:Build（依計畫實作）

照計畫把任務逐項做掉。實作紀律直接遵循全域 CLAUDE.md:§一 撰寫原則(KISS、命名即文件、不留死碼)、§二「改動中」(最小 diff、一次一需求、修改共用元件要逐一確認每個呼叫點)。實作中若發現計畫有誤，回去改 plan.md 再繼續。 🔴 repo 全程不開 bypass;每個會寫入資料或改設定的操作都要經過確認。 測試依專案類型:

• PWA / 前端(如 my-learning-pwa):有 Playwright smoke 測試(test:smoke，見全域 §四),跑它。
• GAS / 無自動化測試的專案:用手動 smoke 清單代替。 Build 出口強制照全域 §二.7 輸出兩份清單:(a) 影響範圍清單——本次觸及的檔案/函式 + 被哪些功能使用;(b) Smoke test 清單——部署前要手動驗證的具體功能點(具體到「開 X 頁 → 操作 Y → 應見 Z」)。無法靜態確認的呼叫點,照 §二.8 明確寫進 smoke 清單,不要假設沒事。

第 4 步:Verify（部署前雙閘驗證）

迴圈出口有兩道刻意分工、不重疊的閘。先判斷這次改動各自要不要走，再交棒。

閘 A:安全/個資/壓力 → 交棒 web-security-reviewer

• 🔴 repo:任何上線/部署前強制。
• 🟡 repo:對外公開前建議。
• 任何「會碰個資、對外開放、AI 生成的碼、要 harden」的情況。
• 純後端（GAS、Cloud Run API）也走這道。

閘 B:UI/UX 與呈現層 → 交棒 ui-ux-deploy-reviewer

• 僅當這次改動觸及前端介面（PWA、網頁前端、有畫面的 GAS Web App）才走。
• 純後端 API、無介面的排程/資料處理 → 跳過這道。
• 它會讀 CLAUDE.md 連動禁區、依 20 原則出問題清單與部署放行判斷，並自己把安全議題讓給閘 A。

兩道閘的關係:並行、不互相取代。 一個有前端又碰個資的改動（多數 my-learning-pwa 功能）兩道都要走;一個純 GAS 後端只走閘 A。交棒方式與該交什麼，見 references/handoffs.md。

接回主迴圈的硬規則:任一閘有未解的 P0 / Critical / High，就不進第 5 步部署。 回到 Build 修掉,必要時更新 plan.md 驗收標準後再驗一次。

第 5 步:Deploy（部署）→ 雙閘放行 + smoke 閘 + 帳號核對

部署前要同時滿足:(a) Verify 兩道閘該走的都走了、且無未解 P0/Critical/High;(b) smoke 閘——有 test:smoke 的專案跑過(可用 /predeploy 自動偵測串接),Build 出口那份 smoke 清單已人工逐項驗過(照全域 §三,未驗證視同未過);(c) 通過 references/deploy-safety.md 的操作核對。最關鍵一條:部署前明確核對目標帳號與專案——若你有多個 Firebase CLI 帳號與專案，誤部署是真實會發生的風險。部署設定（.firebaserc、--account/-P 旗標、appsscript.json 權限）通常已被 project-guardrails 列為 CLAUDE.md 連動禁區。本 skill 不替使用者執行部署、不寫入真實金鑰、不改分享權限;這些列成待辦由使用者親自操作。

（選用附註）把成果轉成學術產出

開發成果要變成研討會摘要、論文章節或期刊段落時，交棒給學術書寫 skill——那是離開本迴圈、進入學術書寫流程的轉場，本 skill 不代寫。

一定要對使用者講清楚的限制

• 本 skill 是流程編排，不保證程式正確或安全;正確性靠測試與 Build 出口的 smoke 清單，安全與易用性靠 Verify 雙閘的 web-security-reviewer 與 ui-ux-deploy-reviewer，撰寫與修改紀律一律以全域 CLAUDE.md 為準（本 skill 不重述、不另立）。
• 研究步驟用的是當下可搜尋到的資訊，仍可能不全;選型決策請保留人工覆核。
• 三級分流是經驗法則，不是法律或合規判定;涉及個資合規（PDPA / PIMS）以權責單位與正式程序為準。
• 本 skill 不執行部署、不動環境設定、不寫真實祕密值——這些永遠是使用者親自操作的待辦。

Reference files

• references/plan-template.md — plan.md 的結構化模板與驗收標準寫法（含 Firebase / GAS / Cloud Run 三種變體）。要產出計畫時讀這份。
• references/deploy-safety.md — 多帳號/多專案部署前檢查清單（Firebase CLI、clasp、Cloud Run），以及帳號誤用的防呆做法。要部署時讀這份。
• references/design-rationale.md — 本 skill 為什麼這樣收斂（與 Matt 原版的六項差異）。要改動流程本身時才讀。
• references/handoffs.md — 與 project-guardrails（前置）、web-security-reviewer（Verify 安全閘）、ui-ux-deploy-reviewer（Verify UI/UX 閘）三個 skill 的交棒協定:何時交、交什麼、交完怎麼接回來，含 Verify 雙閘的適用判斷表。