建置並非在程式碼能執行時完成,而是在程式碼正確時才算完成。
AI 發展迅速。迅速意味著許多事物被建置出來,表面上看起來能運作,但卻偏離了架構、違反了設計系統,或是遺漏了重要的邊界案例。此技能能在這些問題惡化成更大的問題之前,加以捕捉。
請在每個功能完成後執行此技能。在繼續前進之前。
此技能不做的事
它不會修正任何東西。它只會回報所發現的問題,並讓開發者決定哪些事項重要、該如何處理。在不了解的情況下就進行修正,只會讓問題被埋藏起來,而非真正解決。
步驟 1 — 了解應該建置什麼
在開始審查之前,先建立評判基準。
依下列順序閱讀:
- 來自
/architect的實作計畫(如果存在的話) - 所提供功能描述或任務
- 任何相關的上下文檔案 — 架構邊界、程式碼標準、設計規則
如果沒有計畫存在,在審查之前,請要求開發者描述該功能預期要做什麼。如果不了解什麼是正確的,就無法驗證正確性。
步驟 2 — 從三個層面審查
層面 1 — 是否符合計畫?
將實際建置的結果與計畫進行比較。
檢查:
- 功能描述的每個部分 — 是否都已實作?
- 規劃期間所做的決策 — 是否反映在程式碼中?
- 範圍 — 實作是否在範圍內,還是添加了未要求的東西?
標記任何已規劃但遺漏的部分。標記任何未經規劃卻被建置的部分。
層面 2 — 是否尊重系統?
這是 AI 最常發生偏移的地方。功能可以運作,但卻違反了專案依賴的規則。
檢查:
- 架構邊界 — 程式碼是否在正確的位置擁有正確的責任?API 路由中不應有 UI 邏輯。元件中不應有資料庫呼叫。無論專案的邊界為何 — 它們是否被尊重?
- 設計系統 — 是否使用了正確的 token、類別和模式?是否有應為變數的硬編碼值?是否有應使用設計系統的原始顏色類別?
- 程式碼標準 — 命名慣例、檔案組織、TypeScript 嚴格模式、錯誤處理模式 — 它們是否符合專案的設定?
- 現有模式 — 此功能是否引入了新模式,而應該使用既有的模式?
層面 3 — 是否具備生產就緒性?
檢查:
- 錯誤處理 — 當事情出錯時會發生什麼?錯誤是否被捕捉並處理,還是功能會默默失敗?
- 邊界情況 — 空狀態、載入狀態、資料遺失 — 這些情況是否被處理?
- 主控台錯誤 — 瀏覽器或終端機中是否有任何錯誤或警告?
- 明顯的錯誤 — 是否有任何會明顯導致真實使用者無法使用的問題?
步驟 3 — 回報所發現的問題
在完成所有三個層面後,產出一份清晰的報告。不要隱藏問題。不要淡化它們。誠實地回報,以便開發者能做出明智的決定。
## 審查 — [功能名稱]
### 層面 1 — 計畫一致性
[通過 / 發現問題]
[列出計畫與實作之間的差距]
### 層面 2 — 系統完整性
[通過 / 發現問題]
[列出任何架構、設計或程式碼標準的違規]
### 層面 3 — 生產就緒性
[通過 / 發現問題]
[列出任何錯誤處理的缺口、邊界情況或明顯的錯誤]
### 總結
在 [Y] 個層面中發現了 [X] 個問題。
[如果沒有問題:"未發現問題。此功能已可發布。"]
[如果有問題:"請在繼續下一個功能之前,解決上述問題。"]
步驟 4 — 讓開發者決定
呈現報告後,請停下來。不要開始修正。除非開發者要求,否則不要建議修正。
等待開發者:
- 要求您修正特定問題
- 告知某個問題是有意為之,可以忽略
- 確認所有問題都已解決,可以繼續前進
開發者擁有品質決策權。您負責提供資訊。
嚴重性指南
並非所有問題都同等重要。使用此指南協助開發者設定優先順序:
重大 — 在繼續前進前必須修正
- 會破壞未來功能的架構邊界違規
- 導致靜默失敗的遺漏錯誤處理
- 已規劃但完全遺漏的功能
重要 — 應盡快修正
- 將導致 UI 不一致的設計系統偏移
- 會在程式碼庫中累積的程式碼標準違規
- 真實使用者會遇到的邊界情況
次要 — 在方便時修正
- 不影響行為的命名不一致
- 遺漏的最佳化
- 不影響設計系統的風格問題
為每個問題標記其嚴重性,以便開發者能快速進行分類。
標準
此技能所要回答的問題並非「它能運作嗎?」
問題是「它是正確的嗎?」
運作與正確並非同一回事。一個功能今天能運作,明天卻可能破壞整個專案。審查的存在就是為了捕捉這種差異。