演示審查流程 是做什麼的?
測試與程式碼審查能夠證明機制的正確性,但它們無法告訴你選單位置不對、關閉按鈕閃爍或圖示低了 2 像素——只有使用者能看出這些問題。因此,任何外觀或操作變更的處理方式是:先做成一個可運作的演示,讓使用者按功能逐一核准,然後才撰寫產品程式碼;並且只有當使用者在實際應用程式中接受該功能時,才算真正關閉。一個審查板(Artifact 頁面搭配共享資料庫)會用六種狀態追蹤每個功能的進度。
專案設定檔: .claude/demo-board.md(包含板子 URL、各領域的參考應用程式、需要檢查的寬度、實際應用程式及是否包含真實資料、工作區複本的連接埠、閘道指令、規範檔案)。若缺少此檔案,請先建立板子:references/board-setup.md。
走哪條路徑
- 變更某個東西的外觀、位置或操作方式 → 走此流程。無論規模大小或期限壓力,沒有例外。
- 恢復規範或已核准的演示中已定義的行為(例如當機、資料錯誤、溢位、回歸問題)→ 直接以 TDD 方式修正,不做演示。請告訴使用者你判斷走的是哪條路徑。
- 針對已出貨的板子項目回報的錯誤 → 回到
porting,修正,現場檢查,再設為shipped。若修正會改變外觀,則進入新一輪的演示。
流程
- 先參考。 針對該領域,查閱使用者已知的應用程式(設定檔中有列出)。記錄控制項所在位置、每個按鍵、動作(包括退出方式)。只有在給出明確理由時才偏離參考。如果需要在選項間做抉擇,應對模擬使用者進行調查,且調查結果不能取代參考。
- 測量實際 UI。 截取受影響畫面的已出貨畫面(以使用者指定的寬度、唯讀模式),並測量間距、尺寸、對齊方式。在該佈局上進行設計。
- 建置演示 作為一個
feat()項目,必須實際可運作:支援點擊、按鍵、動作(含退出)、淺色與深色模式、窄寬度。詳細步驟 →references/add-feature.md - 記錄演示: 新增一行
changes記錄,並建立features/<id>→ 狀態設為review。 - 移交並停下。 提供連結並說明需要檢查的內容。在該項目被設為
approved之前,不得撰寫任何產品程式碼。「有意見嗎?沒有的話我就繼續」不算核准。如果核准無法在期限前完成,請提供使用者目前已出貨的內容——絕對不要超前建置。 - 每次 UI 工作階段開始時,以及當使用者表示已審查時,收取決策。 讀取
features。狀態為approved→ 進入步驟 7。狀態為changes→note欄位中的內容即為請求 → 回到步驟 3。若使用者說已核准但資料庫顯示不一致 → 表示點擊沒有儲存:告知使用者,並為他們設定。 - 立即移植——使用者不會審查你的計畫;他們的標準是第 9 步。將狀態設為
porting;簡要說明請參考references/port-brief.md。每個檔案領域只能指派一個移植代理。遷移腳本必須在工作區複本上執行;只有在獲得明確核准且有備份的情況下,才能在真實資料上執行。 - 出貨時必須附上現場證據(測量數據、逐幀動作、兩種主題、使用者指定的寬度):設定狀態為
shipped,新增一行changes記錄以及需要檢查的項目。 - 驗證與否由使用者決定——由使用者點擊「接受」,或是在對話中表示該項目已被接受(然後你設定狀態)。模糊的「看起來不錯」→ 詢問是哪個項目。絕對不要只憑自己的判斷。
狀態、設定者、資料庫結構、寫入方式 → references/lifecycle.md。與腦力激盪、撰寫計畫、子代理驅動開發、驗證及分支完成相關的交接工作 → references/superpowers-integration.md。
現場檢查安全
在包含真實資料的實際應用程式上:只能以唯讀模式瀏覽,點擊時只能點擊完全相符的標籤,絕不能在該處進行刪除/移除/編輯——任何會變更資料的檢查都必須在工作區複本上執行。
常見的合理化藉口
| 想法 | 現實 |
|---|---|
| 「這很小 / 很容易復原」 | 規模不是標準;關鍵在於這是外觀或操作變更。小型 UI 變更正是最容易出錯的地方。 |
| 「明天就是截止日了」 | 一輪演示只需要幾分鐘;一個錯誤放置的介面出貨後成本更高。請維持順序,說明時間線。 |
| 「我會給他們看螢幕截圖,如果沒人反對就繼續」 | 沉默不代表核准,而且完成的建置畫面截圖不能讓使用者實際操作。 |
| 「從第一原理來看,正確的位置很明顯」 | 請說出參考應用程式的名稱。「使用者會看哪裡」正是導致那個找不到的開關出貨的原因。 |
| 「測試、審查和建置都通過了,所以完成了」 | 那只是 porting 完成。shipped 需要現場證據,verified 需要使用者確認。 |
| 「『大概看起來可以』代表接受了」 | 接受是按項目逐一進行的。請問清楚是哪個項目。 |
| 「反正他們會核准,我先超前建置應付截止日」 | 未經核准的程式碼都是浪費。請引導他們查看今天出貨的內容;他們一核准就立即移植。 |
| 「我可以發明一個更清楚的狀態」 | 只有六種狀態;頁面和使用者都認得這些。 |
| 「為了節省時間,把移植和演示合併」 | 只有 approved 的項目才能獲得產品程式碼。 |
紅旗——立即停止
- 在演示展示設計之前就開啟產品元件。
- 設計沒有提到參考應用程式的名稱,或沒有測量實際 UI。
shipped沒有附上現場證據;verified沒有使用者對該項目的明確表示。- 在包含真實資料的應用程式中點擊「刪除/移除/儲存」。
- 兩個移植代理同時處理相同檔案;在真實資料上執行遷移腳本。