# Dev Roadmap Planner

> 引導使用者用「規格驅動開發（Spec-Driven Development, SDD）」方法論，從零規劃一個軟體系統的完整開發路線圖，並產出四份可直接落地的工作檔模板（AI 工作守則、交班板、作業筆記、拍板索引）與獨立對抗審查制度。只要使用者提到「新專案」「想開發一個系統/工具/平台」「幫我規劃開發流程」「架構規劃」「開發路線圖」「從頭開始一個專案」，或帶著一個模糊的產品想法來討論怎麼動工，就啟動這個 skill——即使他們沒有明確說出「路線圖」或「規劃」這些詞。本 skill 特別為「單人（或極小團隊）+ 多 AI 協作開發」情境設計，並內建多視窗同時施工的互撞防護（佔號即開檔、交班板分艙、撞號守門測試、審查佇列一進一出）。

- Skill: `alanpai/dev-roadmap-planner` (Agent Skill)
- Install (CLI): `npx skillmds@latest add alanpai/dev-roadmap-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/alanpai/dev-roadmap-planner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: AlanPai (https://skillmd.com/u/alanpai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/alanpai/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 之後，使用者的拍板速度與品質明顯提升——
> 因為**選項的代價變成一眼可比**，而不是埋在三段文字裡。
> 但同一輪也證實了三件事會被視覺化害到（見下方「留在文字裡的三類」）。

### 為什麼要這樣做

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

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

| 類型 | 放哪 | 為什麼 |
|---|---|---|
| **拍板題的選項卡** | 元件 | 代價要能平行比較 |
| **數字、分佈、比例、清單** | 元件 | 表格與長條圖一眼看完 |
| **流程、狀態機、階段進度** | 元件（內嵌 SVG） | 「現在走到哪」用圖比用字快 |
| **現況盤點、交接摘要** | 元件 | 結構化的東西用結構化呈現 |
| 🔴 **偏離回報**（四段式） | 元件可、純文字也可 | 進元件時必須是**獨立的警示卡**（紅框）＋四段式**全文展開**——那是使用者唯一能實質審核你的選擇的時機，不得壓縮成摘要、不得與其他內容同卡 |
| 🔴 **認錯與更正** | 元件可、純文字也可 | 同上：專屬警示樣式，講清楚錯了什麼、對使用者的影響 |
| **一句話結論／追問** | 元件可、純文字也可 | 進元件時放卡片最顯眼處；卡片外仍建議留一兩句純文字收尾——那是使用者視線的落點 |

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

### 拍板題的標準形狀

```
元件裡：
  ┌ 題目（一句話，問號結尾）
  ├ 情境說明（三到五行，講清楚為什麼要問）
  └ 選項按鈕 ×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 訪談 |
| 未知的已知 | 使用者理所當然到不會寫下來、但一看到錯就會糾正的事（現場限制、既有習慣、隱性標準） | 每模組前置訪談 + 介面原型 |
| 未知的未知 | 使用者壓根沒想過的事 | 盲點檢視（兩輪） |

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

| 文件 | 職責 | 生命週期 |
|---|---|---|
| 規格書 | How——系統怎麼運作。**可分卷**：全鏈路作業規格＋最貴核心模組（帳務、金流、庫存一致性之類）的獨立規格。各卷卷首標明分工。🆕v3 每份模組規格設**〈欠帳表〉**章節（見九步⑥c） | 迭代升版 |
| 架構決策紀錄（ADR） | Why——為什麼長這個形狀，含否決理由 | 決策不可修改、只可被新決策取代 |
| 盲點檢核表 | What's left——還剩什麼風險與功課 | 項目解決即打勾，越來越短 |
| 🆕v3.3 衍生規格 | How 的**外借版**——「供他處開發／對外參考」的輸出型文件。讀者在專案外面，看不到你的程式與對話，**文件過期他不會知道** | **必進版控**；卷首標**對齊戳記**：初版日期＋**最後對齊日期與對齊版本（commit）**＋仲裁句「與程式不符以程式為準，並回頭修本文」。行為變更動到它描述的範圍 → 同輪升版，最少也要標「⚠ 本節落後」 |

規則：實作與規格矛盾時以 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` 或同等物） | 這個專案**應該怎麼工作** | 八條準則＋循環規則，讓紀律變成自動行為、不靠人記得 |
| 交班板（`progress.md`） | 現在**做到哪、下一步是什麼** | 維持 1~2 頁的櫃台交班板，不是歷史檔 |
| 作業筆記（`WORK-NOTE.md`） | 偏離與轉向的**存證** | 偏離事項四段式白話＋重大轉向記錄 |
| 🆕v3.1 拍板索引（`docs/decisions.md`） | 每一筆決議的**登記簿** | 只往下加不改舊行；實作期第一筆拍板時建立（模板見〈模板 4〉） |

⚠ 多 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-<線名>`、用完刪**
   （實戰：兩線共用一棵，一輪審查作廢重跑）。審查各開各的分樹、彼此可平行；
   **審查佇列一進一出**——開新線寫程式前先關一筆審查欠帳。審查是序列的，
   這是並行開發唯一會隨時間累積的欠帳，不設閘門就等一次大爆發。

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

```python
# 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——守住「草稿絕不會被套用」這條命根子。
```

```python
# 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 兩種「畫給使用者看」的東西，分工不同

| | 對話內嵌元件（show_widget 之類） | 獨立 HTML 原型檔 |
|---|---|---|
| 用途 | **當下這一輪**的拍板、比較、進度 | **九步③的介面原型**——會被反覆開、給別人看、當驗收依據 |
| 生命週期 | 對話結束就消失 | 進版控，放 `docs/<模組>/prototype/<里程碑>/` |
| 適合 | 選項卡、數字表、流程圖、交接摘要 | 完整可點的畫面流程、模擬掃描、假資料展示 |
| 🔴 不可以 | 拿來當原型——使用者無法回頭開它 | 拿來問拍板題——他不會在檔案裡回答你 |

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

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

#### 介面原型的四種資料來源

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

| 來源 | 做法 | 注意事項 |
|---|---|---|
| **1. 網頁前端** | 使用者提供網址，AI 用瀏覽器工具實際訪問並讀取其底層程式碼，據此產出原型 | 讀到的是「它怎麼做到的」；產出時明講「取了哪些、捨了哪些」 |
| **2. 畫面截圖** | AI 從視覺上還原版面配置、密度、層級關係 | 截圖只有外觀沒有結構，互動行為要另外問清楚 |
| **3. 原始碼** | AI 讀取既有專案的邏輯語義後在本專案技術棧中重現 | 後端原始碼的價值在資料形狀與流程邏輯 |
| **4. 完全沒有資料** | AI 直接生成 3～4 種**截然不同**的設計方向讓使用者挑選 | 方向之間差異要夠大 |

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

🆕v3 **「原型即棄」的誠實版本：版面定案即棄，但程式殼多半會漸進轉正。**
原型定案後，實務上不會整個丟掉重寫——它會**逐頁接上真後端**，變成實際的前端。
這個過渡期（同一頁上有真資料也有假資料）是整個開發週期**最容易產生誤導性缺陷**的階段，
必須立四條過渡紀律：
1. **真假標示**：每一塊畫面標明資料來源——「正式系統資料」或「原型示範（未接正式系統）」，
   不許有「其實是假的但沒標」的區塊。
2. **fail-loud**：查不到真資料就大聲報錯，**絕不靜默退回假資料**——靜默退回會讓使用者以為
   自己在操作真系統。
3. **mock 出口封死**：一頁轉正完成，就把它讀假資料的出口移除（全專案搜尋確認零命中），
   防止日後誰又接回去。
4. **全域常數盤點**：假資料裡的全域常數（預設倉別、廠商清單、站點代號）是轉正時的地雷——
   逐一盤點哪些要改成「由呼叫端明講」，並讓型別系統逼呼叫端傳（必填參數勝過預設值）。

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

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

**七條設計原則：**

| # | 原則 | 說明 |
|---|------|------|
| P1 | **單一事實來源** | API / MCP / CLI / UI 全部呼叫同一層 Service，不允許任何介面繞過業務邏輯 |
| P2 | **沿用既有權限** | 每個呼叫者 = 一個既有身分帳號，權限完全繼承，不另建體系 |
| P3 | **Full logging 先行** | 每一次呼叫記錄：誰、何時、哪個端點、參數、結果。log 本身也可查詢 |
| P4 | **讀寫分級** | 查詢類低門檻；異動類需明確權限；高風險操作需二次確認（參數複誦＋人工確認） |
| P5 | **規格即文件** | API 以 OpenAPI 描述，同一份規格產生人類文件、MCP tool 定義、參數驗證。🆕v3 **請求與回應兩端都要**——只寫 requestBody 的規格是半份契約 |
| P6 | **不鎖定供應商** | MCP 遵循開放標準、API 遵循 REST 慣例 |
| P7 | **版本承諾** | 破壞性變更開新版並行——這是對串接方的契約 |

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

**每個介面的定義模板：**

```markdown
## 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` 或同等物）——八條準則

```markdown
# <專案名> — 專案準則

> 🔴 最高優先：偏離紀錄三步走——①選保守選項 ②當下記入 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`）

```markdown
# <專案名> — 進度交接（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`）

```markdown
# WORK-NOTE.md — 作業筆記

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

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

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

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

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

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

```markdown
# 拍板索引（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），只是文件連測試都沒有，更需要外部眼睛。
    連帶：**程式不會說謊，文件會**——兩者對不上時，永遠先懷疑文件。