# Agentic Dev Loop

> 從研究、plan.md、實作、Verify 雙閘到部署的開發迴圈編排器。當使用者要有計畫地把一個功能或 bug 從規劃走到上線（「開一個新功能」「先研究再做」「整理成 plan.md」「從頭做到上線」「幫我排開發步驟」「某某專案要加…」），或提出未指明範圍的「部署前／上線前檢查」時觸發——後者一律走雙閘，只跑 UI/UX 會漏掉安全與個資驗證。明確只要 UI/UX、只要安全審查、或只要分析連動禁區時，改用對應的單一 skill。

- Skill: `goingli0324/agentic-dev-loop` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add goingli0324/agentic-dev-loop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/goingli0324/agentic-dev-loop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools, DevOps & Infra
- Author: goingli0324 (https://skillmd.com/u/goingli0324)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/goingli0324/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＋測驗結果的組合,且報告檔案通常長期留存。
>
> 🔴 的理由要寫得具體:若所屬機構曾發生個資事故、或負有法定通報義務，這一級的每一步都要把「萬一外洩」當成預設情境來設計，而不是事後補救。

## 開發迴圈:（前置）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 雙閘的適用判斷表。