Dev Roadmap Planner

開發架構規劃路線圖產生器（SDD 方法論）

🆕 v3.5（2026-09-06）變更摘要：一個倉儲平台「五線同日並行」實戰三週的整包回寫。 ① 新增〈多 AI 同時施工〉一節（階段 5 地基的進階層，兩個以上視窗同時寫程式時加開）： 共用序號一律「佔號＝立刻開檔」＋撞號守門測試（附兩支樣板）；交班板分艙（卷首只留交班三行） ＋收官打掃；commit 逐檔點名＋共用帳本整份走＋收 commit 前覆寫本線現況（覆寫不追加， 掛在 commit 這個不會忘的儀式上）；全套測試只在交班前／審查時、一律分樹跑、 分樹被占就另開一棵；審查佇列一進一出。 由來：migration 三連撞、偏離編號四起雙胞躺十天沒人發現、全套測試被半成品污染兩次、 兩線共用分樹撞車一次；守門測試上線首日三發三中（含抓到立規矩的人自己連撞兩次）。 ② 守則模板新增第 9 條「代理節奏」：單輪代理總數 ≤4（工作流扇出全計入）、 禁「每條發現各派一個」的自我繁殖結構、審查編制固定兩人——同一條規矩被繞過四次的血淚。 ③ 審查制度補「派審查子代理兩坑」：報告全文回覆回傳（主線代存）；突變一律前景一次一發。 ④ 🔴 修正〈對話介面〉深色模式規則：原「一律用變數不寫死色碼」在深色模式害色塊卡 深底配深字（兩週兩次被使用者糾正「字看不到」）——改為色塊卡與狀態 chip 底色文字 一律寫死（深底＋白字），一般卡片才用環境變數。 ⑤ 守則模板的禁用詞條升級成「禁用行話登記表」（被糾正當場入表；名詞精度的糾正也算）。

🆕 v3.4（2026-08-11）變更摘要：對話介面全面改用內嵌視覺元件（show_widget 之類）。 由來：一個倉儲專案的散件總撿訪談全程用這個做法跑完二十餘題拍板，證實三件事—— ①選項的代價變成一眼可比，拍板速度與品質明顯提升；②偏離回報、認錯、追問也可以進卡片 （使用者拍板），但必須用專屬警示樣式＋四段式全文展開，防止被當一般資訊卡略過； ③元件會隨對話消失，「落檔才算記錄」的規矩因此更嚴。 新增：〈對話介面〉一節（執行總則第 9 條）、原型章節的「兩種畫給使用者看的東西」分工 （對話元件拍板用、獨立 HTML 原型驗收用，後者產出後 AI 要自己先點一遍每個分支）、 CLAUDE.md 模板第 6 條同步更新。

🆕 v3.3（2026-08-09）變更摘要：又一種文件腐化——這次爛掉的不是登記簿，是規格書本身。 由來（跨兩個專案的同一起事故）：一份「供他處開發」的流程規格早上寫完，當天晚上儲存層就換底 （JSON→SQLite、計時由前端回報改伺服器牆鐘），文件沒跟著改、也一直沒進版控 ⇒ 躺了一個多月後 被另一個專案照抄，做出開主控台就能灌時間的第一代計時設計；靠對方派的研究代理讀出 「規格停在第一代、程式早走到第二代」才攔下。回頭改寫規格的人當輪又寫錯 3 條， 靠獨立代理逐條對程式才抓回——文件的作者盲點與程式一模一樣。五條回寫： ① ⑨a 加「反向敘述掃描」：行為變更（不只拍板）同輪拿舊做法的關鍵詞 grep 全部文件與註解 （含未進版控的檔案——它們不在 diff 裡，最容易漏），講舊行為的句子當場改掉或標過期。 ② 新增「衍生規格」文件類別（頂層文件分工）：供他處開發的輸出型規格必進版控、 卷首標對齊戳記（最後對齊日期＋版本＋仲裁句），行為變更同輪升版或標「⚠ 本節落後」。 ③ ⑨c 檢查單四格擴成五格：新增「文件對時」。 ④ ①訪談與③原型的消費端但書：引用別的專案的規格文件＝一種外部假設—— 不可只讀規格文件，一律以該專案實際上線的程式碼為標準；規格文件只能當導讀。 ⑤ 心法 14：文件改完也要被獨立驗證（改寫的人檢查不出自己的錯）。

🆕 v3.2（2026-08-08）變更摘要：同一個真實專案又栽進同一個坑第四次，補上游那一半。 ① 🔴 ⑨ 新增第五則「清償要當場劃掉」（原本只有半句話夾在「基本回寫」裡，四個缺口全被實戰打穿）： 涵蓋全部登記處（排程表／交班板／欠帳表／偏離索引）、必附完成證據、 「已拍板（要做）」不算狀態（只能三選一：✅ 已清償附證據／◐ 餘 N 項／已具名轉掛含看守人與時點）、 程式與 migration 註解裡的自首句同樣要改。 由來：一批工作當天做完、通過獨立審查、入庫，但排程表那格只寫「已拍板：現在就補」、從未標「已做完」 ⇒ 9 天後另一個 AI 照那張過期單子又排了一次工，還讓使用者做了一個前提不成立的「改期」拍板。 事後全庫重驗 15 項欠帳：功能面一項都不能劃掉，但登記文字過期率約 25%（重複登記、 一開一劃並存、描述的做法已被撤回卻仍標完成）。 ② 四格檢查②改雙向：原只查「新欠帳有沒有進表」，加查「已完成的有沒有出表」。 ③ 過期的自首註解比過期的表格更害人：實戰中誤導判斷的是程式與 migration 註解裡的 「未釘死」「另案再修」「已知缺口」——那是實作者最常看的地方，表格他不一定會翻。 ④ 稽核／盤點類報告寫完沒進排程表＝等於沒寫：實戰一份 460 行、18 項建議的併發盤查報告， 六本簿子零命中，18 天後重驗發現只有 1 項被真正領走施工，而報告自己標記的「最弱一環」 （某類狀態今天造不出來）早已被後續施工推翻、無人回頭複查 ⇒ 兩條會算錯數字的洞就此變成現行。 ⇒ 大型稽核產出交付當輪必須逐項登記進排程表（找不到格就進暫存區並點名），否則報告只是存證。

🆕 v3.1（2026-07-30）變更摘要：同一個真實專案再三天的實戰回寫（拍板治理與多 AI 紀律為主）。 ① ⑨ 擴成「回寫四則」：欠帳同輪進排程表（別處記了不算）＋拍板當場三件事 （含新增第四份工作檔「拍板索引」）＋里程碑標 ✅ 前四格檢查單＋回寫文件。 由來：一筆拍板被後續審查修復推翻無人察覺14 天；140 筆欠帳中 38 筆有負責人卻無排程格接。 ② 「肯定性登記同樣會過期」：清償任何登記在案的事之前，照來源重驗現況——兩次實測抽驗， 過期率都在四成上下。連帶：大盤點類產出必附可信度誠實聲明（哪些驗過、哪些沒驗）。 ③ 多 AI 編號紀律：偏離編號全專案單一序列（動筆前查全檔最大號）；新編號系統啟用前 查撞名、帶可辨識前綴；專案內部代號也算術語，對話中禁裸用。 ④ 「見對話回報」禁令：清單、表格裡每一項的內容必須自足落檔——對話會消失， 實戰中 16 個拍板題只剩編號、題目全文永久佚失。 ⑤ 審查時序：correctness-critical 批次先送審、通過才 commit；權限預設開放的地基設施 （如資料庫函式）建立時同步顯式收權，改版不依賴「會保留權限」。 ⑥ 訪談技巧：規則問不出來時改問 2~3 個實例，由 AI 反推模型再驗證； 對外部系統的假設（鍵值格式、條碼覆蓋率）以實拉真資料樣本驗證，不憑 API 文件。

🆕 v3.0（2026-07-28）變更摘要：全部來自一個真實專案（倉儲管理系統，里程碑 M1~M5、 審查制度跑滿 11 輪校準）的實戰回寫。 ① ⑦ 拆成兩半：作者自測（先紅後綠）＋獨立對抗審查——新增〈獨立對抗審查制度〉一節 （異質驗證、直接執行證據、審查資料夾、修復交接六狀態）。由來：作者測試全綠仍帶 2 個致命洞， 因為同一人寫程式也寫測試，盲點會同時複製到兩邊。 ② 階段 5 擴寫「多 AI 協作地基」：交班板（progress.md）、三層交接、唯讀接手檢查。 由來：多個 AI 共用一個工作區時，真正的風險是踩到別人尚未 commit 的檔案。 ③ 新增〈三份工作檔模板〉：AI 工作守則八條、交班板、作業筆記（偏離四段式白話）—— 開新專案第一天照抄再客製。 ④ 「原型即棄」改寫為「版面定案即棄、程式殼漸進轉正」＋真假混排過渡紀律。 由來：原型從來不會真的被丟掉，它會逐頁接上真後端；過渡期的真假混排孵出了整個專案最難纏的缺陷。 ⑤ 完工判準加「消費者驗收」（審查通過≠能用——19 支端點過了三輪審查，一接前端當天就發現 兩個「設得進去、讀不回來」的洞）；OpenAPI 檢核加「回應 schema 與請求 schema 同等必要」。 ⑥ 心法新增：否定性主張三面查證、同質代理投票不算驗證、全域常數陷阱、還債插播是常態、 欠帳表制度（先關掉的東西要綁「誰補回」）。

🆕 v2.0（2026-07-08）變更摘要：收編《對外介面層建議計畫書 v0.2》的通用方法論部分—— ① 階段 3 必答題新增「對外介面深度」；② 含對外存取的模組，規格必含〈介面定義〉固定章節； ③ 九步循環 ④⑦⑨ 增補介面條款；④ 階段 6／8／9 增補垂直切片打穿介面、放量次序、呼叫紀錄與 AI 巡檢； ⑤「三份頂層文件」改為「頂層文件分工（三種職責，份數可長）」；⑥ 工作筆記固定檔名 WORK-NOTE.md。

這個 skill 做什麼

引導使用者走一遍規格驅動開發（SDD）的規劃流程，最終產出一份客製化的開發路線圖、一組頂層文件骨架， 與三份第一天就建立的工作檔（守則／交班板／筆記）。核心理念：工作品質的瓶頸不在 AI 的能力， 在使用者澄清「未知」的能力——所以整個流程的本質是在代價便宜的階段，用最低成本把未知變成已知。

執行總則（先讀）

1. 一次只問一個問題。 優先問「答案不同、架構就不同」的問題。等使用者回答才問下一題。

2. 用白話，不用術語。 必須用術語時，先用一句話加一個比喻解釋。使用者聽了會混淆的詞 （含任何縮寫），登記成禁用詞、全程用全稱。 🆕v3.1 專案內部代號也算術語：流程條號、題號、問題單編號（⑨-b、PD-A4、INV-xxx 之類） 在對話中禁止單獨出現——一定同時講白話意思，代號只能放括號備查。實戰教訓：主導者用 自己發明的代號當簡寫，使用者當場看不懂＝「用新的黑話取代舊的黑話」，白話規則被自己架空。 文件裡可以留代號（給 AI 與日後查證用），對話裡不行。

3. 每個階段結束必須落地成文件，不留「只存在於對話中」的共識。

4. 先判斷使用者在哪個階段。 不要機械地從階段 0 開始——若使用者已有部分成果，先盤點現況， 從缺的地方接手。開場先問：「你這個專案目前進行到哪裡了？有沒有已經寫好的文件或做過的決定？」

5. 產出路線圖時依專案規模裁剪。 小工具可以合併階段；涉及金錢、庫存、他人資料的系統 不可省略帳務核心與驗收判準。

6. 🆕v3 拍板題不過夜。 需要使用者決定的題目當輪問完；真要延後，必須寫明觸發點 （什麼時候必須回來問）再登記進交班板的待拍板表——不准裸寫「待訪談」歸檔。 🆕v3.1 觸發點必須配看守人：「誰、在什麼時點、負責回來檢查」三項俱全才算登記； 「等某某觸發」這種無主句一律禁止——實戰盤點發現，無看守人的觸發點沒有一個自己醒過來。

7. 🆕v3.1 「見對話回報」禁令。 清單、表格、登記簿裡每一項的內容必須自足落檔； 禁止「詳見當輪對話」這種寫法——對話會消失。實戰事故：一張 25 題的待拍板表， 16 題只寫編號＋「見對話回報」，那場對話結束後題目全文永久佚失，只能靠使用者回憶或判死。

8. 🆕v3.1 新編號系統啟用前先查撞名。 專案裡的編號空間（檢核表編號、問題單編號、 偏離編號、題號）會越來越多套；開新一套之前 grep 既有編號、掛可辨識前綴（如 PD-）， 並在名詞表消歧條登記——兩套編號長得一樣時，查錯的人不會知道自己查錯。

9. 🆕v3.4 對話一律用視覺元件呈現，不用純文字堆。 要使用者過目、比較、拍板的東西 （選項、數字、流程、清單、進度），一律以對話內嵌的 HTML 元件渲染 （Claude Code 環境為 show_widget）。詳細做法見〈對話介面〉一節。 偏離回報、認錯與更正、追問也可以進卡片（2026-08-11 使用者拍板），但有兩條硬規矩： ①專屬警示樣式（紅／黃警示卡，與一般資訊卡明顯區隔）②全文展開（偏離回報四段式 一字不減，不得壓縮成一行摘要）。理由：那三類要被「完整讀到」——醒目與完整是底線， 形式不拘。

🆕v3.4 對話介面：用視覺元件跟使用者互動

由來：一個專案全程改用對話內嵌 HTML 之後，使用者的拍板速度與品質明顯提升—— 因為選項的代價變成一眼可比，而不是埋在三段文字裡。 但同一輪也證實了三件事會被視覺化害到（見下方「留在文字裡的三類」）。

為什麼要這樣做

拍板題的本質是比較：三個選項各自的好處與代價，使用者要放在一起秤。 純文字沒辦法平行呈現——他讀到第三個選項時已經忘記第一個的代價是什麼。 數字（覆蓋率、分佈、比例）也一樣：一段文字裡的四個百分比，讀完不會留下印象； 一張三列的表格會。

什麼放進元件、什麼留在文字

節奏：每一輪＝一個元件（視覺）＋幾句文字（結論與偏離）。不要一輪丟三個元件。

拍板題的標準形狀

元件裡：
  ┌ 題目（一句話，問號結尾）
  ├ 情境說明（三到五行，講清楚為什麼要問）
  └ 選項按鈕 ×3～4，每顆按鈕內含：
       · 選項名稱（1～5 字），建議者標「（建議）」並排第一
       · 白話後果 2～3 行——🔴 **好處與代價都要寫**
文字裡：
  · 一句話講你為什麼推薦那個
  · 偏離回報（若有）

🔴 每個選項都必須有代價。 只寫好處的選項不是選項，是誘導。 實戰：一個選項寫「最安全」卻沒寫「拿到全部時要按滿 N 下」，使用者選了才發現要多按十幾下。

🔴 按鈕文字要寫成「使用者會說的話」，不是指令。按鈕送出的內容會變成使用者的發言， 所以寫「我選：照庫位編號排」而不是「設定排序＝庫位編號」。

呈現規則（跟著環境的設計系統走）

• 用工具提供的設計系統（顏色變數、字級、圓角），不要自己刻一套——目的是讓元件看起來 像對話的一部分，不像一個外掛廣告。
• 顏色要有意義：綠＝已完成／安全，黃＝要注意，紅＝會出錯或需要決定。不要彩虹配色。
• 深色模式，分兩種（🆕v3.5 修正——舊寫法「一律用變數」兩週內兩次害色塊卡在深色模式 變成深底配深字、使用者兩度糾正「字根本看不到」）：一般卡片（淺底）用環境變數沒問題； 色塊卡與狀態 chip（有色底）底色與文字一律寫死——深底＋白字： 藍 #14385c／橘 #5c3f14／紅 #5c1a1a／綠 #14452f， 標題 #ffffff、內文 rgba(255,255,255,0.88)、次要 rgba(255,255,255,0.7)。
• 數字用等寬字、要有分母（「已撿 3／應撿 5」勝過「已撿 3」）。
• 圖只在有機制可畫時才畫：流程、狀態轉移、走位順序。純粹裝飾的圖不要放。

🔴 元件會消失——所以「落檔」的規矩比以前更嚴

本 skill 的〈執行總則〉第 7 條禁止「詳見當輪對話」。對話內嵌元件同樣是對話的一部分， 一樣會消失，而且更危險：它看起來很正式、很像文件，讓人以為「已經記下來了」。

硬規矩：元件裡出現的每一項拍板、數字、清單，同輪必須落進檔案 （拍板索引／規格／證據資料夾）。元件是呈現，落檔才算記錄。

環境相依與退路

這類工具不是每個環境都有。開場先確認能不能用；不能用時降級成 Markdown 表格＋編號選項， 並在交班板記一筆「本環境無視覺元件，改用文字」——讓下一個接手的人知道為什麼風格不一樣。

底層語言：未知四象限

全程用這套語言描述「還沒搞定的事」，並讓使用者學會這套語言：

頂層文件分工（三種職責，份數可長）

規則：實作與規格矛盾時以 ADR 為準；檢核表項目討論完的產出物不一定回到規格書（合規類長成合約與 SOP， 維運類長成 runbook）。每新增一份頂層文件，所有頂層文件卷首的分工宣告同步更新。 🆕v3.3 衍生規格的對齊戳記是 ⑨a 反向敘述掃描與 ⑨c「文件對時」的錨點——沒有戳記， 讀的人無從判斷這份文件新不新鮮，掃的人也不知道該從哪個版本查起。實戰：一份外借規格 與程式脫節一個多月無人察覺，因為它既沒進版控（不在任何 diff 裡）、也沒有任何日期戳記。 🆕v3 頂層文件不只一本時，引用條號必連書名（「儲位規格 §10.1」而非「規格 §10.1」）， 首次出現附檔案路徑——否則接手者（含 AI）會查錯文件。此規範同樣適用程式註解與 migration。

規劃流程（十個階段）

引導使用者依序走完。每階段先解釋目的，再開始訪談，結束時產出對應文件。

階段 0：定錨（產出：一頁目標書）

問三個問題：這系統為誰做？做到什麼程度算第一版成功（要可驗證）？明確不做什麼？ 超過一頁 = 還沒想清楚。這一頁是之後所有「要不要加功能」的仲裁依據。

階段 1：領域盤點（產出：流程白描、名詞表、事件清單）

完全不碰技術。引導使用者：

• 按實際作業順序把現況流程寫下來，含「檔案上沒有、但大家都這樣做」的習慣。
• 建名詞表：一個概念只准一個名字（越早統一越省）。🆕v3 名詞表是用詞的唯一依據： 寫規格、程式、畫面文案前先查表；表上沒有的新詞先登記再使用；同詞異義照「消歧速查」加限定詞， 禁止裸用——多人（含多 AI）協作時，大家講同一種話是唯一的黏著劑。
• 列出所有會改變核心資料的「事件」，並標出「看起來像動作但不動帳」的操作。
• 盤點例外流程：正常流程誰都會設計，系統的成敗全在例外。

階段 2：盲點檢視（產出：盲點檢核表）

挖「未知的未知」。做法：

• 以「做過十套同類系統的顧問」身分，列出使用者完全沒提到但一定會踩的坑。
• 建議使用者換一個全新對話再做一輪，把兩輪合併去重。
• 分四級：A 區（擋開發路的）、B 區（合規合約的）、C 區（上線後維運的）、D 區（觸發式的）。

階段 3：架構決策訪談（產出：ADR 文件）

挖「已知的未知」中的架構級題目。做法：

• 列出所有「答案不同、之後改的成本以週計」的問題。
• 一次一題，每題攤開選項與各自代價，讓使用者選。
• 每條決策記錄：問題、選項、選了哪個、為什麼否決其他選項。
• 常見必答題（依專案調整）：單用戶還是多租戶／資料的最小單位與粒度／帳怎麼記（事件流 vs 直接改狀態 ——涉及金錢庫存者建議事件流，帳壞了能重放）／一致性標準多嚴／身分與權限模型／部署與合規／ 技術選型（🆕v3 含可搬遷性：優先可自託管的開源方案，雲商專屬服務採用前須使用者明確同意， 目的是整包可搬遷）／對外介面深度——系統只給人用 UI，還是同時給機器（API）、AI（MCP tool）、 終端機（CLI）用？若要，架構級決斷有四：單一 Service 入口、OpenAPI 為單一事實來源、 認證權限沿用既有身分、對外版本承諾。
• 🆕v3 全域常數陷阱：哪些「現在只有一個」的東西（倉庫、門市、租戶、幣別、語言）未來會變多個？ 它們的代號若寫死在程式常數裡，變多個的那天會炸在哪？——實戰中一個寫死的倉別代號連耗三輪審查 才收斂，因為它同時滲進了資料請求、畫面顯示、標籤列印與掃碼解析四層。識別碼建議雙軌： 內碼＝永不重用的身分（歷史記錄掛它）；顯示碼＝可重用的地址（現場貼標掃碼用它）。
• 答完檢查決策自洽，並回寫檢核表。

階段 4：規格書（產出：分卷規格 + 核心模組獨立規格）

• 按易變度排序，不按流程順序：資料模型、型別介面、面向使用者的畫面在前；業務流程在中； 機械式演算法在後。介面定義同理：參數與回傳結構屬低波動放前段。
• 最貴、錯了最痛的核心模組獨立成篇：狀態機、併發語義、關鍵時點。
• 每章附驗收判準（不變量）：例如「任何時刻各狀態加總 = 總量」「事件流重放得到相同結果」。 這是單人開發補 QA 的關鍵，之後直接變成自動化測試。
• 含對外存取的模組：規格內設〈介面定義〉固定章節（模板見下），與 UI 章節平行； OpenAPI 片段為必要產出。🆕v3 回應結構與請求結構同等必要——只寫「送什麼進去」不寫 「回什麼出來」的 OpenAPI 是半份契約，接前端的人只能去翻後端程式碼（實戰中 96 個操作 只有 2 個寫了回應格式，代價在接線期全數償還）。若選擇以後端型別為回應權威，必須在規格明寫指路。
• 面向使用者的章節：先原型、後規格——定案才落規格。產原型前先問使用者有沒有參考資料 （詳見〈介面原型的四種資料來源〉）。
• 定稿後建議使用者開全新對話做零上下文外部審查。

階段 5：地基工程 🆕v3 大幅擴寫

repo、環境分離（開發/測試/生產）、自動備份第一天開。

測試框架比第一個功能先立——前後端都算。 後端把不變量寫成測試骨架；前端若走「原型轉正」 路線（見〈介面原型〉節），轉正的那一刻就是前端測試框架該立的時刻——不立可以， 但要明白代價：之後每一輪審查的前端問題都只能靠人工開瀏覽器逐條驗，沒有自動回歸網。

前三份工作檔第一天建立、第四份（拍板索引）於實作期第一筆拍板時建立 （完整模板見〈四份工作檔模板〉一節，照抄後依領域客製）：

⚠ 多 AI 協作時，守則檔通常要兩份同內容（如 CLAUDE.md＋AGENTS.md，各家 AI 讀各自的檔名）—— 改任何一份必同步另一份並驗證指紋相同，否則兩個 AI 各守各的規矩。

多 AI 協作地基（兩個以上 AI 共用一個工作區時必立）：

• 認清風險本質：新視窗看不到舊對話，但看得到同一份工作區、包括尚未 commit 的檔案。 真正的風險不是「忘記對話」，是不知道未提交的檔案是誰做的、做到哪，直接動手就會踩到別人施工中的東西。
• 三層交接（照順序讀）：①守則檔＝怎麼工作 ②交班板＝做到哪 ③git status＝實際有哪些修改。 三者衝突以 Git 與程式實際輸出為準，但不得自行覆蓋他人未提交的修改——先回報，由使用者裁示。
• 接手檢查全程唯讀（建議做成專案 skill）：讀完三層 → 白話回報接手摘要（HEAD／里程碑／已完成／ 未提交檔案及推定負責者／下一步／待拍板／哪些檔案不能碰）→ 等使用者確認才施工。
• 收工時更新交班板（含「未提交檔案與負責者」表），使下一個視窗接得住。

🆕v3.5 多 AI 同時施工（兩個以上視窗同時寫程式時，在上面那組地基之上加開這一層）

上面那組管的是「接力」（一次一個視窗）；多線同時動工，靠自覺必撞——以下四條 全是同一個專案三週內真實撞出來的，每條都配「不靠人記得」的機械保險：

1. 共用序號一律「佔號＝立刻開檔」＋撞號守門測試。 migration 取號唯一依據＝資料夾現況（.sql 與 .sql.draft 都算）取最大號＋1， 決定用某號的當下就建 NNN_名稱.sql.draft 佔住（檔頭註明哪條線、做什麼）； 程式只套用 .sql，草稿隱形——寫到一半的改版檔絕不會被別的視窗誤套用； 定稿才轉正，轉正或套用後不得編輯、不得改名（程式按檔名記帳）；廢線刪草稿、號碼不回收。 沒建佔位檔，任何規劃書不得寫死號碼（實戰：規劃書寫死的號碼一天被搶兩次）。 作業筆記的偏離編號同理：動筆前查全檔最大號；先存檔者得號，撞了晚者讓號。 兩者都配守門測試（樣板見下）：大家改完必跑測試，任何撞號最慢十幾分鐘全場亮紅 ——不靠誰眼尖。實戰：守門上線首日三發三中，包括抓到立這條規矩的人自己連撞兩次。
2. 交班板分艙＋收官打掃。 卷首共用區只留「交班三行」（版本到哪／正式環境在哪／一句話現況，誰最後收工誰更新）； 各線敘事只寫分工表自己那一列；動共用帳本前必先重讀檔案現況（腦中版本是開工快照， 可能已過期）；別人的字一律不動；兩線要動同一支程式檔，先在分工表「觸及檔案」欄登記、 後到的排隊。線的名字取「現場講得出口的白話」（如「廠商登入補洞」）， 禁止拿字母或里程碑編號當名字。收官打掃：線結案且已推遠端後，自己那列縮成 一句話＋卷宗指路、細節搬歷史檔——誰收工誰打掃（實戰：不掃，板子兩天從 480 行 胖到 628 行，過期敘事開始互相打架）。
3. commit 點名制＋收 commit 前覆寫本線現況。 git add 一律逐檔點名，禁 git add -A（實戰掃走過別線檔案）； 例外＝交班板與作業筆記是共用帳本，整份走（收的是各線登記文字）。 收 commit 前，把交班板自己那列的現況「覆寫」成 commit 之後的真話——覆寫不追加 （固定一格長不成流水帳；狀態沒變＝覆寫出來一樣＝等於沒改）。commit 是唯一不會忘的 儀式，交班板掛在它上面，「換視窗忘了更新」就從靠記性變成有鬧鐘。
4. 測試與審查的隔離。 平時與收 commit 前只跑動到的那一塊（全套很大時，收 commit 硬跑全套現場等不起）； 全套只在交班前／審查時，且一律在分樹（git worktree 開的乾淨分身，只含已 commit 的東西）跑——共用工作區跑全套會被別線半成品污染出假紅（實戰兩次，每次都得先花力氣 自證清白）。交班前那一跑不得省，紅了當場修完再交班。 分樹被占用（停在別人的 commit、或正在跑）→ 自己另開一棵 check-<線名>、用完刪 （實戰：兩線共用一棵，一輪審查作廢重跑）。審查各開各的分樹、彼此可平行； 審查佇列一進一出——開新線寫程式前先關一筆審查欠帳。審查是序列的， 這是並行開發唯一會隨時間累積的欠帳，不設閘門就等一次大爆發。

撞號守門測試樣板（照抄改路徑即可；鑑別力驗法＝故意放一個撞號檔／撞號條目進去，必須紅）：

# tests/test_migration_numbering.py —— 改號單（migration）撞號守門
import re
from app.db import MIGRATIONS_DIR              # ← 換成你專案的 migrations 資料夾常數
_RE = re.compile(r"^(\d{3})_[^.]+\.sql(\.draft)?$")

def _files():
    return sorted(MIGRATIONS_DIR.glob("*.sql")) + sorted(MIGRATIONS_DIR.glob("*.sql.draft"))

def test_filenames_follow_scheme():
    for f in _files():
        assert _RE.match(f.name), f"檔名不合 NNN_名稱.sql（或 .sql.draft 草稿）：{f.name}"

def test_no_duplicate_numbers_even_in_drafts():
    seen = {}
    for f in _files():
        m = _RE.match(f.name)
        if m:
            assert m.group(1) not in seen, f"撞號：{seen[m.group(1)]} 與 {f.name}——晚開檔的改號"
            seen[m.group(1)] = f.name
# 第三條建議：monkeypatch 改號單資料夾塞一個 .sql＋一個 .sql.draft，呼叫 migrate()，
# 斷言只套用 .sql——守住「草稿絕不會被套用」這條命根子。

# tests/test_worknote_numbering.py —— 作業筆記偏離編號撞號守門
import re
from pathlib import Path
WORK_NOTE = Path(__file__).resolve().parent.parent / "WORK-NOTE.md"
_RE = re.compile(r"^\*\*第 (\d+) 筆｜", re.MULTILINE)   # 只認條目標題；內文按號引用不算
_FROZEN = set()   # 歷史撞號凍結名單（回頭改舊號會斷別處引用；掃出舊雙胞就登記在這）

def test_no_duplicate_entry_numbers():
    seen, dups = set(), []
    for m in _RE.finditer(WORK_NOTE.read_text(encoding="utf-8")):
        n = int(m.group(1))
        if n in seen and n not in _FROZEN:
            dups.append(n)
        seen.add(n)
    assert dups == [], f"作業筆記撞號：{dups}——晚寫的讓號改號（查全檔最大號再往下接）"

階段 6：垂直切片

不做完整功能，做一條最薄但打穿全部技術層的流程。在真實使用環境用真實設備測，不在辦公室模擬。 若系統含對外介面，垂直切片建議含一條讀取介面打穿：OpenAPI 規格 → API 端點 → 衍生 MCP tool， 驗證兩路徑對同一查詢結果一致。規格的報酬遞減——寫到某個程度後，只有真實世界能繼續教你。

階段 7：模組迭代（九步循環，順序不可跳）

① 前置訪談：AI 先列出它對本模組假設的現實條件，一次一題向使用者確認。
   🆕v3.1 兩個實戰技巧：a. **規則問不出來就改問實例**——使用者答「三個因素都有、
   沒有單一主因」這類複合答案時，別再逼他抽象化，改請他舉 2~3 個實際例子
   （「Ａ廠商×全通路」這種），由 AI 反推規則模型、下一題驗證——抽象化是 AI 的工作，
   不是領域專家的。b. **對外部系統的假設以實拉樣本驗證**——要串接的平台，訪談期就實際
   拉一批真資料存樣本（探勘 spike），別憑 API 文件想像：實戰一次探勘推翻了「自動對碼靠
   國際條碼」的整條規劃假設，還揪出規劃時沒人想過的資料形狀。
   🆕v3.3 c. **「別的專案的規格文件」也是一種外部假設**，照 b 的紀律辦理：引用前先驗它與
   該專案**實際上線的程式碼**同步（拿文件對程式，或請該專案主人確認），不憑文件想像。
   由來：一份外借規格與程式脫節一個多月，照抄的一方做出已被淘汰、開主控台就能灌時間的
   第一代設計——文件寫得越完整，讀的人越不會起疑。
② 規格對齊：讀對應章節，使用者交代自己想到哪裡、哪裡還模糊。
③ 介面原型（含 UI 的模組）：先問使用者有沒有參考資料，
   依〈介面原型的四種資料來源〉產出假資料原型，挑完定案。
   🆕v3.3 但書：參考對象是別的系統時，**不可只讀它的規格文件**——一律以
   **實際上線的程式碼（或實際運行中的系統）為標準**，規格文件只能當導讀
   （規格會過期，而且過期了不會告訴你；程式不會說謊）。
④ 規格章節定稿（含本模組驗收判準；含對外存取的模組另含〈介面定義〉
   章節與 OpenAPI 片段——請求與回應結構都要）。
⑤ 高判斷力部分逐項確認：schema、型別、狀態轉換，點頭才動。
⑥ 機械式部分放手批次做，遵守三條紀律：
   a. 🆕v3 偏離紀錄三步走：被迫偏離計畫或規格未明定而必須自行選擇時——
      選保守選項 → **當下**記入 WORK-NOTE（禁止事後補記）→
      **即時在對話中回報使用者**（禁止只寫檔案不回報）。
      描述一律白話四段式（見〈作業筆記模板〉）。
   b. 參考資料提醒（不強制）：遇到成熟領域的難題，提醒使用者
      「有成熟開源實作可查證，要查嗎」。
   c. 🆕v3 欠帳登記：任何「先關掉／先用假資料／先不做」的決定，
      登記進該模組規格的〈欠帳表〉：現況／**哪一批工作負責補回**／補回判準。
      只記在 WORK-NOTE（依日期的流水帳）不夠——開工前沒人會翻流水帳，
      被關掉的功能就永遠躺著。
      🆕v3.1 **且同一輪必須在路線圖（排程表）對應格補一行**（白話一句＋來源檔名:行號）；
      找不到對應格就寫進路線圖表末的「未歸格欠帳（暫存區）」列並在交付總結點名。
      理由：五個地方都能「記下」欠帳，**只有路線圖決定實際會做什麼**——實戰全庫盤點，
      140 筆欠帳中 38 筆「有負責人、排程表卻無任何一格接得住」。
      ⚠ 專案若同時存在兩套工作座標系（如「刀×階段」與「里程碑 M×」），欠帳**兩種都標**，
      否則等於沒登記。
⑦ 驗證，🆕v3 拆成三層：
   a. 作者自測：不變量測試＋本模組驗收判準，關鍵修復走**先紅後綠**
      （先寫會失敗的測試證明缺口存在，修完轉綠才算數）。
      含對外介面的模組：各路徑（API／MCP／CLI／UI）對同一查詢結果一致。
   b. 獨立對抗審查：correctness-critical 模組必過（詳見
      〈獨立對抗審查制度〉一節——何時必做、派工、證據等級、關單標準）。
   c. 消費者驗收：後端模組要有**至少一個真實消費者**（UI 或串接方）
      用它拼出完整流程才算關。審查通過≠能用——審查問「這段程式對不對」，
      接線問「這些零件湊起來夠不夠拼出一個能用的畫面」，是兩個問題。
⑧ 隨堂測驗（硬規則）：AI 針對變更出測驗——設計理由、行為變更、
   受影響路徑、邊界處理。全對才算完工。答錯先講解再重測。
⑨ 回寫文件，🆕v3.2 擴成「回寫五則」：
   a. 基本回寫：規格升版、筆記歸檔、檢核表打勾、必要時新增 ADR；
      Service 行為變更同步檢查 OpenAPI 與 changelog。
      🆕v3.3 🔴 **行為變更加做「反向敘述掃描」**（不等拍板才掃——換底層、改做法都算）：
      拿**舊做法的關鍵詞**（舊檔名／舊欄位名／舊流程的名詞）grep 全 repo——
      規格各卷、**衍生規格**、README、程式與 migration 註解，**含未進版控的檔案**
      （它們不在任何 diff 裡，是掃描的天然死角）——講舊行為的句子當場改掉；
      改不動的（如已套用的 migration）標「⚠ 已過期，以〈書名＋條號〉為準」。
      由來：一次儲存層換底當天改了主規格，卻漏了一份三週前寫的衍生規格與兩處程式註解；
      一個多月後那份規格被另一個專案照抄，做出已被淘汰、可灌時間的第一代設計。
      （欠帳的登記與劃掉自 v3.2 起獨立成 ⑨d，不再夾在本則裡——夾著就會被跳過。）
   b. 🔴 拍板當場三件事（每一筆使用者拍板都做）：
      ①在**拍板索引**（`docs/decisions.md`，見〈第四份工作檔〉）補一行——只往下加、不改舊行；
      ②架構級的（答案不同會改變系統形狀）另立 ADR；
      ③**單一講法**：把所有講相反話的規格、程式註解**同輪改掉**——同一件事存在兩種講法，
        查到不同本的人會做出相反的事，誰都沒錯但系統錯了。**能寫成測試的拍板優先寫成測試**
        （測試會擋住未來任何人不小心推翻它；文字不會）。
        🆕v3.3 掃描範圍明列：規格各卷、**衍生規格**、README、程式註解，
        **含未進版控的檔案**——untracked 檔案不會出現在 diff 裡，最容易漏。
      由來：一筆拍板被後續一輪審查修復依另一份規格的相反句推翻，**無人察覺 14 天**，
      直到全庫盤點才翻出來。
   c. 🔴 里程碑標 ✅ 前過五格檢查單（🆕v3.3 由四格擴為五格）：
      ①格子清空——沒做完的**具名轉掛**（禁無看守人觸發點）；
      ②欠帳歸位，🆕v3.2 **改雙向**——新欠帳逐筆核對「有沒有進表」，
        **已完成的逐筆核對「有沒有出表」**（單向只會讓表越來越假，見 ⑨d 由來）；
      ③拍板活著——期間拍板逐筆核對：進了拍板索引沒？規格與程式**現在還照著它嗎**？
      ④**端到端實跑一次主流程**——測試綠證明「寫過的檢查都過」，不證明「流程真的走得通」
        （實戰：一條「建立成功路徑」因缺一個預設值而**從未**端到端通過，測試卻一直是綠的）。
      ⑤🆕v3.3 **文件對時**——本里程碑改過行為的部分，反查「還有哪些文件在描述它」：
        衍生規格的**對齊戳記**升了沒？README 與部署檔的敘述還對嗎？程式註解裡還有沒有
        講舊行為的句子？（③查的是「決議」還活著，本格查的是「敘述」還正確——兩回事。）
      五格全過才標 ✅；否則標「◐（餘 N 項）」。
   d. 🆕v3.2 🔴 **清償／改期／改歸屬＝當輪回頭劃掉來源登記**（⑥c 的另一半）：
      ①改**全部**登記處，不只一處——排程表／交班板／模組規格〈欠帳表〉／偏離索引都要一致；
      ②**必附完成證據**：commit／migration 號／測試名／審查資料夾，至少一項；
      ③🔴 **「已拍板（要做）」不算狀態**——那句話會讓下一個人以為還沒做。只能三選一：
        **✅ 已清償（附證據）** ／ **◐（餘 N 項）** ／ **已具名轉掛（含看守人與時點）**；
      ④🔴 **程式與 migration 註解裡的自首句同樣要改**（「未釘死」「另案再修」「已知缺口」
        「待某某」）——那是實作者最常看的地方，**過期的自首註解比過期的表格更害人**；
        已套用的 migration 不得編輯時，改在對應程式註解並註明「該檔某段已過期、以本註解為準」。
      由來：⑥c 管「欠帳產生要進表」，卻沒有人管「欠帳消失要出表」——**只有一半的規矩＝
      表格必然越來越假**。實戰：一批工作當天做完、通過獨立審查、入庫，排程表那格卻只寫
      「已拍板：現在就補」⇒ 9 天後另一個 AI 照那張過期單子又排一次工，並讓使用者做了一個
      前提不成立的拍板；同型事故**第四次**，該次全庫重驗登記文字過期率約 25%。
   e. 🆕v3.2 **稽核／盤點類報告：交付當輪逐項進排程表**——大型體檢報告（併發盤查、全庫欠帳
      盤點、安全稽核）**寫完不進排程表就只是存證**。實戰：一份 460 行、18 項處置建議的報告，
      六本簿子零命中，18 天後重驗只有 1 項被真正領走施工；更糟的是報告**自己標記的「最弱一環」**
      （「某類狀態今天造不出來，所以那幾條只是潛伏」）早被後續施工推翻而無人回頭複查
      ⇒ 兩條會算錯數字的洞就此從潛伏變成現行。**報告的前提假設要當成欠帳登記，附看守人與複查時點。**

發版紀律：低風險時段發版、migration 先過測試環境、發版前快照、回退步驟先寫好。 🆕v3 多租戶系統：每張新表建立時同步建隔離規則（RLS 或等價機制），寫進開發 checklist。 已套用的 migration 一律不得再編輯——改註解也不行，指紋一樣會變。 🆕v3.1 修正一律發新號檔（含只改文字的修正——資料庫裡看得到的說明文字可用新檔覆寫， 舊檔當歷史封存）。預設開放的權限要顯式收權：有些地基設施「沒說禁止＝全部開放」 （如 PostgreSQL 函式預設 PUBLIC 可執行，只寫 GRANT 等於沒鎖），每支建立時同步顯式收權 並寫進 checklist；改版不得依賴「會保留權限」——每次改版重下一次收權語句， 讓每支檔案自己看得出鎖到底鎖了沒（實戰：一支總開關函式漏收權，破口留了 50 支 migration 才被抓到）。 憑證不落 repo：token／金鑰只存對話與暫存區；commit 前 grep 驗證無殘留。

🆕v3.4 兩種「畫給使用者看」的東西，分工不同

判斷句：這個畫面「以後還要再開」嗎？要 → 獨立 HTML；只是這一輪要決定 → 對話元件。 兩者可以接力：先用對話元件把版面方向拍板，再產獨立 HTML 原型讓使用者實際點。

🔴 獨立原型產出後，AI 要自己先開起來把每個分支點一遍（瀏覽器工具實測）， 不是寫完就交——實戰抓到過：規格裡的例外（某區不查對照表）在原型第一版寫反了， 點一遍才發現。之後再交給使用者點。

介面原型的四種資料來源

每次要產介面原型之前，先問使用者一題：「這個畫面你有沒有想參考的東西？網頁、截圖、或原始碼都可以。」

🆕v3.3 但書：規格文件不是第五種來源。 對方交來的若是規格書／設計文件，只能當導讀， 不可據以實作——一律回到來源 1 或 3，以**實際上線的程式碼（或運行中的系統）**為標準； 文件與程式對不上時以程式為準，並回報給該文件的主人。由來：一個專案照別人外借的規格 實作計時系統，做出來才發現規格停在已被淘汰的第一代（前端回報秒數＝開主控台就能灌）， 程式其實早改成第二代（伺服器牆鐘）——那份規格寫得非常完整，完整到沒有人想過要懷疑它。

🆕v3 「原型即棄」的誠實版本：版面定案即棄，但程式殼多半會漸進轉正。 原型定案後，實務上不會整個丟掉重寫——它會逐頁接上真後端，變成實際的前端。 這個過渡期（同一頁上有真資料也有假資料）是整個開發週期最容易產生誤導性缺陷的階段， 必須立四條過渡紀律：

1. 真假標示：每一塊畫面標明資料來源——「正式系統資料」或「原型示範（未接正式系統）」， 不許有「其實是假的但沒標」的區塊。
2. fail-loud：查不到真資料就大聲報錯，絕不靜默退回假資料——靜默退回會讓使用者以為 自己在操作真系統。
3. mock 出口封死：一頁轉正完成，就把它讀假資料的出口移除（全專案搜尋確認零命中）， 防止日後誰又接回去。
4. 全域常數盤點：假資料裡的全域常數（預設倉別、廠商清單、站點代號）是轉正時的地雷—— 逐一盤點哪些要改成「由呼叫端明講」，並讓型別系統逼呼叫端傳（必填參數勝過預設值）。

介面定義模板（API／MCP tool／CLI 共用）

適用時機：模組要開放給機器（API）、AI（MCP tool）或終端機（CLI）存取時，規格內與 UI 章節平行設置本模板章節。

七條設計原則：

架構形狀（一段話）：API 是地基，MCP 和 CLI 是它的兩種殼。介面層要薄，只做四件事： 認證轉譯、參數驗證、rate limit、寫呼叫紀錄；業務邏輯全部留在 Service 層。

每個介面的定義模板：

## N. 介面定義（API / Tool）
### N.1 介面清單
| 名稱 | API 端點 | MCP tool | 類型（讀/寫） | 風險 | 對應 Service | 最低角色 | 對外開放 |
### N.2 各介面詳細定義
#### {名稱}
- 描述（同時作為 API 文件摘要與 MCP help）：
- 參數：名稱 / 型別 / 必填 / 說明 / 範例值
- 回傳：結構 + 範例 JSON（🆕v3 必填，不得留空）
- 前置條件 / 副作用 / 錯誤碼 / 稽核欄位 / 冪等性
### N.3 權限矩陣
### N.4 使用情境範例

通用 API 規範檢核清單：REST 資源導向、版本進 URL；Bearer token 綁帳號、自動限定資料範圍； cursor-based 分頁；寫入端點支援 Idempotency-Key；錯誤格式統一含 trace_id；rate limit 回應帶 剩餘額度；時間一律 ISO 8601 帶時區；Webhook 配套（HMAC 簽章、指數退避、可查可重推）； 版本與棄用政策白紙黑字；外部寫入採申請制優先；沙盒與正式同一套程式碼不同資料庫。

🆕v3 獨立對抗審查制度（⑦b 詳則）

由來（一手教訓）：帳務引擎的快樂路徑測試全綠、連作者另寫的 19 條對抗測試也全綠， 仍帶 2 個致命洞——同一人寫 code 也寫測試，系統性盲點會同時複製到兩邊。 獨立審查的價值＝打破作者盲點，不是「多一層測試」。

何時必做（模組中任一條即觸發）：①帳務/不變量正確性（錯＝資料損毀或賠錢） ②狀態機／併發／多來源事件 ③地基性（後面全建在它上、bug 會擴散）。 不必做：UI／設定／純機械 CRUD／拋棄式原型。

派工原則（防止燒錢買假安心）：

• 預設＝主審（可為實作者親手查證）＋一位「用不同方法」的獨立驗證者。
• 同模型、同提示、同讀法的多數同意不算獨立驗證——對每筆候選派 N 個同質反駁者投票， 燒的 token 是實質驗證的十倍、換到的信心是假的（實戰教訓：82 個代理、607 萬 token 的一輪， 效果不如一位換方法的驗證者）。
• 驗證者必須新增至少一項實質證據：獨立來源、可重現步驟、反例、嚴重度修正——不得只回「同意」。
• 高風險類型（數量/金額/併發/冪等/權限/租戶隔離/migration）必須在隔離環境取得直接執行證據， 不得以讀碼論證代替。

審查資料夾（每次審查必建，與產品程式分開理解）：

docs/reviews/<年>/<YYYY-MM-DD>-<主題>/
├─ README.md    ← 範圍、政策版本、基準 commit、狀態
├─ report.md    ← 問題單（編號/嚴重度/重現/白話後果/關單標準）
├─ metrics.json ← 統計（候選數/確認數/token）
└─ evidence/    ← 原始輸出（先紅證據、實測記錄）

修復與交接（六狀態，AI 之間直接交接、使用者只管拍板）： 修復中 → 待複驗 → 複驗中 → 待修復（或通過）→ …

• 修復方：直接讀上一輪 report 與證據，不要求使用者轉貼；每次修復建新的 -recheckN/ 資料夾， 不覆蓋上一輪；附先紅後綠證據（退回修復→紅→還原後與修復版逐字元相同→綠）； 逐條對照關單標準。
• 審查方：不修改產品程式；只寫該輪 report／metrics／evidence。
• 只有四種情況找使用者：規格沒有答案且兩種做法業務結果不同／修復要擴大到未授權範圍／ 要接受或放棄一項已確認風險／雙方對規格有證據解不了的分歧。
• ⚠ 範圍認定是修復輪最常見的失敗點：關單標準裡的範圍詞（「所有」「相關」「整頁」） 要先展開成可打勾的清單再動手——實戰中一筆問題連耗三輪，就是把「所有寫入」讀成了 「我這輪新增的元件」。
• 修不完不能修一次就宣布乾淨；通過條件＝問題全關或使用者明確接受風險，不以代理同意票數代替證據。
• 🆕v3.1 時序：必審批次「先審後 commit」——觸發強制審查的批次，通過審查才 commit； 先 commit 才想起送審＝流程事故，補救方式是「保留 commit 不改寫歷史＋補送審＋自首記偏離， 審出問題用追加 commit 修」。修復方式規則：未 commit 的檔案直接改；已 commit 的一律追加新 commit（migration 則發新號檔），不改寫歷史。
• 🆕v3.1 修復方對審查建議可以說不——當審查者的建議與專案既有紀律衝突（例如要求編輯 已套用的 migration），修復方選擇守紀律的替代路徑，把衝突明列在送審說明裡請審查方裁示， 不得沉默照做也不得沉默拒絕（實戰：審查方最終裁定守紀律的一方正確）。
• 🆕v3.5 派審查子代理的兩個實戰坑：①子代理寫審查報告檔可能被環境擋下——派工提示寫明 「報告全文一律在最後回覆原封回傳；能寫檔就順便寫，寫不成不算失敗」，主線代存並註明； ②拆防線突變一律前景、一次一發、跑完做位元組級還原驗證，禁背景並行——實戰兩份 突變腳本同時改同一支檔、互相蓋掉還原，差點把工作樹留在突變狀態。

階段 8：上線切換

若取代既有作業：新舊並行、每日對帳、連續 N 天零差異才切換、切換選低量日。準備紙本/手動降級 SOP。 若是全新系統：小範圍試用 → 逐步放量。 對外介面的放量次序固定：讀取類先行 → 內部寫入（開發者自己當白老鼠）→ 高風險操作 → 對外開放； 每階段設驗收標準。

階段 9：維運制度化

目標一句話：讓使用者被叫醒的次數趨近於零。監控告警、自動備份、每季實際演練一次還原、 runbook 寫到半夜三點也能照做的粒度。含對外介面的系統：呼叫全紀錄納入常設監控； 可排程 AI 日巡檢（非法狀態轉移、卡單、異常呼叫模式），報告推送使用者慣用通道。 維護期 AI 分工：使用者描述問題、AI 動手、不變量測試把關。

🆕v3 四份工作檔模板（開新專案第一天照抄，再依領域客製；第四份於第一筆拍板時建立）

模板 1｜AI 工作守則檔（CLAUDE.md 或同等物）——八條準則

# <專案名> — 專案準則

> 🔴 最高優先：偏離紀錄三步走——①選保守選項 ②當下記入 WORK-NOTE.md ③即時在對話中回報。
> 禁止事後補記、禁止只寫檔案不回報。交付總結附本輪偏離筆數（含 0 筆），
> 且每筆「逐筆全文展開」四段式（遇到什麼／選了什麼／為什麼／對使用者的影響）——
> 使用者唯一能實質審核這些選擇的時機就是回報的當下，叫他自己翻檔案＝等於沒有回報。

1. **偏離紀錄**：見卷首最高優先準則。
2. **用詞以名詞表為唯一依據**：寫規格、程式、UI 文案前先查表；新詞先登記再使用；
   撞詞加限定詞、禁止裸用。🆕v3.5〈禁用行話登記表〉（被糾正**當場**入表；
   名詞精度的糾正——如「收工前」改「交班前」——也算）：
   ｜禁用詞｜改說｜出處日期｜——起手先登記使用者聽了會混淆的縮寫與行話。
3. **實作期每模組必走九步循環，順序不可跳**（①訪談→②對齊→③原型→④定稿→⑤逐項確認
   →⑥批次做→⑦自測+審查+消費者驗收→⑧隨堂測驗→⑨回寫）。
   🔴 **⑨ 的兩條硬規矩（兩條都是實戰栽出來的，缺一條就會反覆重演）**：
   - **欠帳產生要當場進排程表**：不論記在哪裡（模組規格欠帳表／作業筆記／交班板／程式註解裡的
     「那一刀再做」），同輪都必須在**排程表**對應格補一行（白話一句＋來源 `檔名:行號`）；
     找不到對應格就寫進表末「未歸格欠帳（暫存區）」並在交付總結點名。
     理由：五個地方都能「記下」，**只有排程表決定實際會做什麼**。
   - 🆕 **欠帳清償／改期／改歸屬要當場劃掉**：改**全部**登記處＋**必附完成證據**
     （commit／migration 號／測試名／審查資料夾）；**「已拍板（要做）」不算狀態**，
     只能三選一（✅ 已清償附證據／◐ 餘 N 項／已具名轉掛含看守人與時點）；
     **程式與 migration 註解裡的自首句同樣要改**（「未釘死」「另案再修」「已知缺口」）——
     那是實作者最常看的地方，過期的自首註解比過期的表格更害人。
     理由：只有前一條＝表格必然越來越假。實戰：一批工作當天做完並通過審查入庫，排程表卻只寫
     「已拍板：現在就補」⇒ 9 天後另一個 AI 照過期單子又排一次工，還讓使用者做了個
     前提不成立的拍板；同型事故第四次，該次重驗登記文字過期率約 25%。
4. **發版紀律**：低風險時段發版、migration 先過測試環境、發版前快照、回退步驟寫進 PR；
   <多租戶：每張新表同步建隔離規則>；已套用的 migration 不得再編輯。
5. **選型**：優先可自託管的開源方案；雲商專屬服務採用前須使用者同意（整包可搬遷）。
6. **對使用者一律白話**：要過目、拍板、確認的內容不得堆術語——術語首次出現先用
   <該領域的生活類比，如倉庫/表單/Excel> 解釋；提問附「白話後果」與建議選項；
   🆕v3.4 過目與拍板的內容用**對話內嵌視覺元件**呈現（環境有 show_widget 之類工具時）——
   選項卡每顆附白話後果**含代價**；偏離回報、認錯、追問可進卡片，但**專屬警示樣式＋全文展開**
   （偏離四段式一字不減、獨立成卡不與他物混排）；
   元件內容同輪落檔（元件是呈現，落檔才是記錄）；環境沒有此類工具時降級 Markdown 表格並記交班板；
   引用文件條號必連書名、首次附檔案路徑（文件多本時防查錯）；
   🆕v3.1 **專案內部代號（流程條號/題號/問題單編號）在對話中禁止單獨出現**——
   必附白話意思，代號只能放括號備查（文件裡可留代號，對話裡不行）。
7. 🔴 **「不存在」要拿證據**：任何否定性主張（「系統沒有Ｘ」「不支援」「規格沒定義」）
   寫進文件或回報之前，三面查證——①實作面（grep 路由/函式，且不只找同名，要找「能達成
   同一目的的既有組合」）②規格面（「已定義未實作」與「不存在」是兩回事，措辭必須分清）
   ③資料面（查 schema 或實測）。**子代理的回報一律視為待驗主張**：親手驗證後才轉述，
   否則明標「未驗」。🆕v3.1 **肯定性登記同樣會過期**：動手清償任何登記在案的欠帳／
   待拍板前，先照來源重驗現況——實測抽驗過期率約四成（早已做完、早已拍板不做、
   或情境已變）；照過期登記單施工＝重做已完成的事或做回被否決的事。
   ⚠ 本條是**下游補救**（動手前多花一輪重驗），上游那一半在準則 3「清償要當場劃掉」——
   兩條要一起用：沒有上游，你每次動工都得先付一輪重驗成本；沒有下游，第一次就做錯。
8. 🔴 **審查紀律**：依審查政策派工——主審＋一位異方法驗證者；同質代理投票不算驗證；
   高風險類型須隔離環境直接執行證據；每次審查建資料夾；修復輪逐條對照關單標準。
9. 🆕v3.5 🔴 **代理節奏**：單輪代理總數 ≤4——**工作流的扇出全部計入**（算的是這一輪
   會被開起來的總數，不是階段數、不是第一階段的數量）；**禁用「每條發現各派一個」的
   自我繁殖結構**（總數必須動筆前就寫得出來）；要超過先問使用者；被喊停＝立刻停手、
   自己接手做完，不換包裝重派；派出前一句話告知「派幾個、各做什麼、多久回來」。

## 交接協定（多 AI 共用工作區時）
接手第一步不得修改任何檔案：讀 ①本檔 ②progress.md 最上方 ③git status，
白話回報接手摘要，等使用者確認才施工。三者衝突以 Git 為準，但不得覆蓋他人未提交的修改。
收工時更新 progress.md 最上方（含未提交檔案與負責者表）。
🆕v3.5 多線**同時**施工時，加掛路線圖〈多 AI 同時施工〉那一節的四條
（佔號即開檔＋守門測試／分艙＋收官打掃／點名制＋覆寫現況／分樹測試與審查一進一出）。

## 怎麼跑
<啟動資料庫、跑測試、起服務的實際指令，含已知的環境雷>

模板 2｜交班板（progress.md）

# <專案名> — 進度交接（progress.md）

> **這是櫃台交班板，不是歷史檔。** 只放「現在有效」的資訊，維持 1~2 頁。
> 最後更新：<日期>（<誰>）。<一句話現況>。<下一步>。<有無待拍板>。
> 三層交接宣告：①守則檔＝怎麼工作 ②本檔＝做到哪 ③git status＝實際修改。
> 衝突以 Git 為準；不得覆蓋他人未提交的修改。歷史沉澱在 docs/progress-history/，接手不需要讀。

## 1. 目前位置        ← 哪個里程碑、九步循環第幾步、這一輪做了什麼
## 2. 最新 HEAD       ← git log 前幾筆＋協作者辨識方式（標明「此為推定」）
## 3. 未提交檔案與負責者 ← 逐檔表格：檔案／誰做的／內容。🔴 他人寫的審查報告與證據勿改寫
## 4. 當前施工        ← 有沒有做到一半的東西；新視窗接手先做的三件事；⚠ 最容易踩的雷
## 5. 下一步          ← 按順序；含「可並行且不衝突的工作」
## 6. 待辦            ← 非拍板題，做到就劃掉；每筆註明「何時做」
## 7. 待拍板          ← 編號／題目／觸發點；已拍板的記結果與日期，不刪列
## 8. 最近驗證結果    ← 主導者親驗、非轉述：測試數字、實測輸出、dev 資料現況
## 9. 必讀文件        ← 哪份文件、什麼任務時才讀（防止接手者一次讀完所有歷史）

維護規則：只在最上方寫現況；過期段落搬進 docs/progress-history/<年月>.md； 數字（測試綠、HEAD、未提交數）寫之前先跑指令核對，不憑印象。 🆕v3.5 多線同時施工時：卷首共用區只留「交班三行」、各線敘事寫分工表自己那列（分艙）； 收 commit 前覆寫自己那列現況（覆寫不追加）；線結案即收官打掃（縮一句話＋搬歷史檔）。

模板 3｜作業筆記（WORK-NOTE.md）

# WORK-NOTE.md — 作業筆記

## 作業筆記準則
> 偏離計畫或規格未明定而自行選擇時：選保守選項 → 當下記錄 → 即時回報。
> 禁止事後補記（真的漏了要補，必須據實標明「非即時紀錄」）。
> 「錯了要改」（審查抓出的缺陷修復）不算偏離，不記這裡。

## 重大轉向記錄
### <日期>｜<轉向標題>（使用者拍板）
- 轉向內容 / 使用者理由 / 評估結論 / 連帶影響

## 偏離事項（依日期倒序）
> 🆕v3.1 偏離編號＝**全專案單一序列（所有 AI 協作者共用）**：動筆前先查**全檔最大號**再往下接續，
> 不是接自己上次的號——實戰撞號事故：兩個 AI 各編各的，同一個編號底下各有兩筆完全不同的內容，
> 之後查舊偏離都得連日期一起講才找得到對的那筆。

### <日期>（<任務>）｜<標題>
**第 N 筆｜<一句話標題，白話>**
- **遇到什麼狀況**：<邊界狀況，白話>
- **我選了什麼**：<保守選項>
- **為什麼這樣選**：<理由，含另一個選項的壞處>
- **對你有什麼影響**：<使用者視角的實際後果，含留下的技術債>
- **技術註記**：<一行，給工程讀者與未來的 AI>
- **✅ 結案（<日期>）**：<使用者核可／後續處理>   ← 有結果才加

🆕v3.1 模板 4｜拍板索引（docs/decisions.md）——實作期第一筆拍板時建立

為什麼需要第四份：拍板散落在對話、交班板、筆記、規格各處，會被後續工作不知不覺推翻 （實戰：一筆拍板被審查修復依另一份規格的相反句推翻，無人察覺 14 天）。 拍板索引＝決議登記簿：以後任何人問「這題到底怎麼定的」，翻這一本。

# 拍板索引（decisions.md）

> 規則：**只往下加、不改舊行**；被取代時在舊行尾加「⚠ 已被 <日期> 取代」再新增一行。
> 出處一律用**段落／條目錨點，不用行號**——行號隔天就腐化（實戰：建檔當天行號就偏移 21 行）。
> 檔頭誠實聲明回填程度（哪些是事後回填、哪些當場登記）。

| 日期 | 一句話題目 | 結論（含理由摘要與否決了什麼） | 全文出處（錨點） |

搭配用法＝九步 ⑨b「拍板當場三件事」的第①件；里程碑收尾 ⑨c 第③格拿它逐筆核對「拍板還活著嗎」。

🆕v3.1 大盤點類產出必附「可信度誠實聲明」

凡是批次產出的盤點／索引／清單（欠帳總帳、偏離索引、待拍板清單），檔頭固定聲明： 多少筆經過獨立查證、多少筆只有單一來源、抽驗結果如何——並指示讀者「動工前照準則 7 重驗」。 實戰：一份 88 筆的清單只有 32 筆經反證（其中 41% 被推翻）；因為檔頭誠實寫了， 後續使用者對未反證的部分保持警覺，逐題重查時又抓掉一半高估。誠實聲明不是免責，是導航。

最終產出：路線圖文件

走完訪談後（或使用者只想要快速版時，濃縮訪談後），產出一份客製化路線圖，包含：

1. 全局地圖（各階段、預估量級、產出物）——依專案規模裁剪過的版本。 🆕v3 量級旁註明：「還債插播」是常態不是計畫失敗——原型轉正、欠帳清償這類工作 會在實作期自然長出來，先給它們保留欄位（欠帳表→立案→分階段），別讓它們以「延期」的 面貌出現。
2. 該專案的頂層文件清單與骨架
3. 該專案的架構級必答題清單（階段 3 用）
4. 該專案的模組切分建議與依賴順序（P0/P1/P2…）
5. 可直接貼進 AI 工作守則檔的循環規則條款
6. 🆕v3 工作檔（守則／交班板／筆記，🆕v3.1 ＋實作期起的拍板索引），依模板客製後直接建檔

心法（適時傳達給使用者）

1. AI 是共筆者也是審稿者，但不能同時是——共筆用連續對話，審稿用全新對話（或另一個異質 AI）。
2. 引導 AI 是平衡的藝術：限制太死它死板執行到底，給太模糊它用通用做法填空。解法不是完美的 鬆緊度，是持續挖未知。
3. 長任務失敗通常不是 AI 不行，是未知定義不足，或缺一個允許 AI 遇到未知時應變的計畫。
4. 只做每天會用到的功能；「以後可能需要」= 沒人驗收的死程式碼。
5. 單人開發者本人是唯一的單點故障——文件、runbook、可重放的紀錄，都是在外部化腦中的智慧。
6. 🆕v3 作者盲點會同時複製到程式與測試兩邊——「自己測全綠」的信心上限就是作者自己的想像力， 所以 correctness-critical 的東西要過異質審查。
7. 🆕v3 同質代理投票不算驗證——十個一樣的人說「對」，不如一個人换個方法親手跑一次。
8. 🆕v3 否定性主張是最危險的一類結論——「系統沒有Ｘ」若是錯的，功能會被白白關掉， 而且那句話會留在文件或畫面上繼續騙下一個人。三面查證、區分「已定義未實作」與「不存在」。
9. 🆕v3 審查通過 ≠ 能用——完工的最後一關是「有真實消費者用它拼出完整流程」。
10. 🆕v3 修別人開的問題單，先把範圍詞展開成清單——「所有」「相關」這種詞， 審查者與實作者的理解會分岔，逐條可打勾才動手。
11. 🆕v3.1 登記不是記憶，是會腐化的快照——否定性主張要三面查證（心法 8）， 肯定性登記也會過期（實測四成）。唯一不腐化的登記是測試； 其次是有看守人的排程格；最差的是「等某某觸發」的無主句與「見對話回報」。
12. 🆕v3.1 兩邊各自都對，湊在一起就錯——最難抓的缺陷不是誰寫錯，而是兩段各自正確的 程式對同一欄位有不同假設（一邊寫「作廢原因＝更正才填」、另一邊為了別的目的也開始填）。 防法＝拍板當場的「單一講法」掃描：改任何語義前 grep 誰還依賴舊語義。
13. 🆕v3.1 刪東西不能安靜通過——刪除的守門要「警告＋列出受影響清單＋二次確認＋留痕」； 「沒有營運紀錄」不等於「可以刪」（剛建好還沒用的真資料就是反例）；範圍一律白名單明列， 不用「這個人名下全部」這種廣泛條件。同一週兩個現場（外部系統實測＋自家審查）都撞到這條。
14. 🆕v3.3 文件改完也要被獨立驗證——把過期規格改成「現況」的人，寫出來的新敘述一樣會錯 （實戰：改寫者當輪就被獨立代理抓出 3 條與程式不符——都是他「以為自己記得」的行為）。 大改規格後，請另一個代理（或全新對話）拿文件逐條對程式再收工。 文件的作者盲點與程式的一模一樣（心法 6），只是文件連測試都沒有，更需要外部眼睛。 連帶：程式不會說謊，文件會——兩者對不上時，永遠先懷疑文件。