# Agentic Dev Loop

> 系統化開發工作流，把「先研究 → 寫 plan.md → 依計畫實作 → 部署前雙閘驗證 → 部署」固定成一條可重複的迴圈，專為單人維護多個 Firebase / Google Apps Script / GCP Cloud Run 專案的情境設計。核心是「計畫先行、狀態外部化到檔案、依專案風險分級決定授權與驗證強度」，作為編排器串接三個既有 skill：進入專案前若尚未建立連動禁區 → project-guardrails 分析並寫入 CLAUDE.md，規劃時據以避開「改 A 壞 B」；部署前 Verify 雙閘 → web-security-reviewer 做安全/個資/壓力驗證、ui-ux-deploy-reviewer 做 UI/UX 與呈現層審查（僅當有前端介面）。MANDATORY TRIGGERS：使用者說「開一個新功能」「幫我規劃這個開發」「從頭把這個功能做到上線」「先研究再做」「整理成 plan.md」「這個專案要怎麼做（指要從規劃做到上線，不是單純問方向）」「修這個 bug（要有計畫地修）」「<專案名> 要加東西」（以專案名開頭的開發需求）「要部署到 Firebase / Cloud Run」「GAS 寫一個…」「我有個想法想做成工具」「幫我排開發的步驟」「走完整個開發到部署的流程」，或貼上 issue 連結、錯誤截圖、需求描述並希望有系統地把它從規劃做到上線時，都要套用此 skill。注意分流：若使用者只要「單獨檢查 UI/UX」用 ui-ux-deploy-reviewer、只要「單獨做安全審查」用 web-security-reviewer、只要「分析專案禁區」用 project-guardrails；本 skill 是把這些串成完整迴圈的編排器，當意圖是「有規劃、可重現、會走到上線」的整段開發時才觸發。**重要安全防漏：若使用者說的是泛泛的「部署前檢查」「上線前幫我檢查」而沒指明只要 UI/UX 或只要安全，應由本 skill 接手走 Verify 雙閘（同時跑 web-security-reviewer 與 ui-ux-deploy-reviewer），絕不要只做其中一道——尤其不要只做 UI/UX 而漏掉安全閘，那會讓含學生個資的專案在沒過安全驗證下就上線。**SCOPE：本 skill 是工作流編排器，不取代使用者對計畫的閱讀與判斷；只在使用者自己的專案上運作，不協助繞過授權

- Skill: `goingli0324/agentic-dev-loop-2` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add goingli0324/agentic-dev-loop-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goingli0324/agentic-dev-loop-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: goingli0324 (https://skillmd.com/u/goingli0324)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/goingli0324/agentic-dev-loop-2

---


# 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 結果），升 🔴。不確定時，往高一級靠。
>
> 🔴 的理由是具體的: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 不代寫、不繞過 AI 偵測;學術文字的作者責任始終在使用者身上。

## 跟 Matt 原版的關鍵差異（為什麼要改）

- **不預設全程 bypass。** 改成風險分級;🔴 一律關閉。
- **不建議多機常駐 / 遠端觸發 / 雙付費方案。** 單人、成本敏感、且每多一個常開執行點就多一個個資攻擊面;現階段收益不抵風險與開銷。
- **平行 session 收斂到 2–3 個，且工作/個人帳號分視窗**，降低誤部署。
- **保留使用者讀計畫**;TLDR 只當輔助。
- **新增兩個機構級關卡**:部署前帳號核對、🔴 強制安全驗證——這是 Matt 沒有、但維護機構資料的人必須有的合規層。
- **新增前置連動禁區分析**:進專案先確認 CLAUDE.md 有 project-guardrails 標記的禁區，規劃時據以避開「改 A 壞 B」——Matt 靠個人記憶與 GitHub 回滾，本 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/handoffs.md` — 與 project-guardrails（前置）、web-security-reviewer（Verify 安全閘）、ui-ux-deploy-reviewer（Verify UI/UX 閘）三個 skill 的交棒協定:何時交、交什麼、交完怎麼接回來，含 Verify 雙閘的適用判斷表。