AI 前端任務與發布工具包

課程首頁：Learning/ai first frontend foundations

這兩張表用於每一次真實前端任務。Brief 在開始前縮小模糊空間，證據表在完成後阻止「看起來可以」直接變成發布。

AI 前端任務 Brief

把中括號替換成這次任務內容。這份 brief 的用途是讓 Agent 先理解問題與驗收方式，再開始改檔案。

1. 背景與目標

• 產品／頁面：[名稱與目前狀態]
• 主要使用者：[誰、在什麼情境使用]
• 這次要改善的結果：[可觀察的使用者結果]
• 成功指標：[例如完成率、錯誤率、載入體驗或明確功能]

2. 範圍

• 必須做：[3–7 個具體項目]
• 不要做：[明確非目標]
• 可改檔案／區域：[若已知就列出]
• 不可改內容：[品牌、資料、既有 API、共用元件等]

3. 視覺與內容

• 要保留的視覺特徵：[字級、留白、色彩、節奏、密度]
• 參考來源：[連結或截圖，以及只借鑑哪些特徵]
• Design tokens：[顏色、字體、間距、圓角、陰影]
• 真實內容：[不要用 lorem ipsum；列出文案與資產來源]

4. 頁面與元件

• 路由／頁面：[URL 與用途]
• 元件樹：[Page > Section > Component]
• 重用規則：[哪些是共用、哪些只屬於本頁]

5. 資料、狀態與互動

觸發	資料／狀態變化	使用者看見	失敗時
[點擊／輸入／載入]	[變化]	[回饋]	[錯誤與重試]

至少涵蓋 initial、loading、empty、error、success、disabled；不適用時寫明原因。

6. 技術與安全邊界

• 執行位置：[server／client 與理由]
• 資料來源：[API、檔案、資料庫]
• secret：[只能留在 server 的內容]
• 現有技術限制：[框架、版本、部署平台]

7. 響應式與可及性

• 小／中／大畫面行為：[版面怎麼重排，不只列裝置名稱]
• 鍵盤路徑：[Tab 順序、Enter／Space、Escape]
• 可及名稱與錯誤提示：[按鈕、輸入、圖片、動態訊息]
• 動畫／動態偏好：[reduced motion 或不適用]

8. 驗收條件

• 功能 happy path 通過。
• loading／empty／error／success 狀態可見且可恢復。
• 指定寬度沒有水平捲動、遮擋或文字截斷。
• 鍵盤可完成主要流程，焦點清楚。
• Console 沒有未解釋錯誤；Network 請求與狀態碼符合預期。
• typecheck／test／build 通過，或清楚列出原有失敗。
• Git diff 只包含本任務必要改動。

9. Agent 工作協議

開始前先：

1. 閱讀專案規則與相關檔案。
2. 回報你理解的現況、假設、預計修改範圍與驗證方法。
3. 若需求與現有架構衝突，先指出證據與取捨。

完成後提供：

1. 改了什麼與為什麼。
2. 逐項驗收結果與使用的證據。
3. 未驗證項目、風險與最小下一步。
4. 相關檔案連結；不要用「應該可以」代替測試結果。

前端驗收與發布證據表

第一層：變更範圍

• git status -sb 能解釋每個變更與未追蹤檔。
• git diff --stat 的範圍符合任務。
• git diff 沒有秘密、除錯殘留、無關重寫或意外刪除。

第二層：畫面與互動

• 主要流程可從頭到尾完成。
• initial、loading、empty、error、success、disabled 都已測或註明不適用。
• 重複點擊、重新整理、返回、直接開深層 URL 不會造成未處理狀態。
• 文案、連結、圖片、日期與資料不是 placeholder。

第三層：響應式與可及性

• 至少測窄手機、寬手機／平板、桌面，不只縮放截圖。
• 無意外水平捲動、重疊、裁切或不可點擊區域。
• 鍵盤可到達並操作主要功能；焦點樣式可見。
• 表單有 label、錯誤可理解；圖像有合適替代文字。
• 色彩不是唯一訊號，文字對比與點擊目標合理。

第四層：瀏覽器證據

• Elements／Styles 確認實際 DOM 與套用樣式。
• Console 無未解釋錯誤、warning 或 hydration 問題。
• Network 的 document、asset、API 都有合理狀態碼、回應與載入順序。
• 慢速網路或失敗回應下仍有可理解的使用者回饋。

第五層：自動化證據

• lint 通過或列出原有失敗。
• typecheck 通過或列出原有失敗。
• tests 通過或說明未覆蓋範圍。
• production build 通過，並確認輸出與部署設定。

第六層：部署與回復

• 先驗收 preview URL，再進 production。
• client bundle 不含 secret；環境變數設在正確環境。
• production URL 完成 smoke test，版本／commit 可追溯。
• 已寫出 rollback 觸發條件、回復方式與回復後驗證。

最終判斷

只能使用以下三種結論：

• 通過：必要條件與證據完整。
• 有條件通過：不阻擋發布的已知限制已列出負責人與處理時間。
• 不通過：列出阻擋項、重現方式與下一個最小修正。