goingli0324 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 的產出在出口端也被用到。
核心心法（先讀，再進流程）
- 計畫先行。 除非是一行字就能改完的事，動手前一定先有
plan.md。計畫是「能熬過 session 崩潰、context 流失、隔天才回來做」的存檔點；對話氣泡是金魚記憶，檔案才是白板。 - 狀態外部化。 把「問題是什麼、要動哪些檔、驗收標準、要遵循的既有模式、目標帳號與專案」全寫進檔案，而不是留在腦中或對話裡。session 死了，指向同一份 plan 就能接著做。
- 規劃才是高價值工作。 把多數心力放在把計畫想清楚；實作只是把想清楚的事執行出來。一份好計畫值得反覆改三輪，劣質計畫會讓實作來回鬼打牆。
- 授權強度跟著專案風險走，不是一招走天下。 Matt 全程 bypass permissions；在碰學生個資的 repo 這樣做等於拆掉實驗室的門。本 skill 用三級風險分流（見下）決定授權與驗證強度。
- 使用者讀自己的計畫。 可以請模型給 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＋測驗結果的組合,且報告檔案通常長期留存。
🔴 的理由要寫得具體:若所屬機構曾發生個資事故、或負有法定通報義務，這一級的每一步都要把「萬一外洩」當成預設情境來設計，而不是事後補救。
開發迴圈:（前置）Guardrails → Research → Plan → Build → Verify 雙閘 → Deploy
第 0 步:定級、收斂範圍、確認連動禁區
做三件事:
- 定級——確認這次動的 repo 屬於哪一級（🟢🟡🔴），決定後面的授權與驗證強度。
- 收斂範圍——確認目標 Firebase 帳號與專案 ID（或 GCP 專案、GAS script）、這次要解的問題。輸入可以是文字需求、GitHub issue 連結、錯誤訊息截圖、會議逐字稿。範圍模糊時先問一兩個關鍵問題，不要腦補。
- 確認連動禁區——檢查該專案的 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 雙閘的適用判斷表。