單元 8：Agent 任務設計——從美感直覺到可執行規格

課程首頁：Learning/ai first frontend foundations

AI Agent 能讓實作速度大幅提升，但它也會放大模糊需求。當你只說「做得高級一點」、「參考這個網站」或「幫我補完整」，Agent 必須自行猜測內容、元件、狀態與技術範圍。它可能很快交出一個漂亮畫面，同時加入不存在的文案、改寫不相關架構或漏掉失敗狀態。

Agent 任務設計不是學習一段萬用 prompt。它是把你腦中的產品與美感判斷，轉成可執行、可觀察、可驗收的契約。你仍然可以保留直覺，但要學會指出直覺背後的關係。

本單元完成條件

完成後，你應該能夠：

1. 將模糊需求收斂成目標、必做、non-goals 與檔案範圍。
2. 把視覺 reference 拆成可借鑑特徵，避免機械複製。
3. 提供真實內容、component、state、route 與 responsive 規格。
4. 寫出可由人或工具判斷通過／失敗的 acceptance criteria。
5. 讓 Agent 先讀規則與現況，再提出計畫與假設。
6. 用 diff 與證據控制變更，不靠完成摘要判斷。

一個完整任務有六層

1. 產品層：為誰解決什麼

先說明主要使用者、使用情境與希望改善的結果。不是寫品牌宣言，而是建立決策依據。例如「讓使用者在手機上能快速找到並開啟一篇筆記」比「打造高效知識體驗」更能判斷導覽、密度與載入狀態。

2. 內容層：畫面真正要承載什麼

提供實際標題、欄位、圖片與資料來源。Placeholder 會讓版面在假內容下看似成立，換成真實長標題、缺圖或空資料就崩壞。若內容尚未確定，應明確列為未知，不要授權 Agent 自行生成推廣文字填滿空間。

3. 互動層：使用者做什麼，系統如何回應

列出觸發、狀態變化、畫面回饋與失敗恢復。主要流程之外，還要涵蓋 loading、empty、error、disabled、重複操作與返回／重新整理。

4. 視覺層：關係與規則，不只是形容詞

把「乾淨」拆成留白級距、內容密度、色彩角色、字體層級與邊界處理；把「有質感」拆成較少但一致的陰影、克制色彩、清楚層級與真實內容。視覺規格應能在多種畫面與狀態重現。

5. 技術層：邊界與限制

列出現有框架、可改範圍、不可動的 API／品牌／共用元件、server／client、secret、相容性與部署條件。這不是替 Agent 指定所有實作細節，而是防止它越過產品與安全邊界。

6. 證據層：怎樣才叫完成

每個重要要求都應對應驗證方法。畫面用指定 viewport 與真實內容；互動用重現步驟；網路用 Network；結構用 Elements 與鍵盤；程式品質用 diff、typecheck、test 與 build；部署用 preview 與 production smoke test。

先定義 Non-goals，避免 Agent 順手擴張

Non-goals 不是消極清單，而是保護任務焦點。例如：

• 不改資訊架構。
• 不重寫既有 component library。
• 不新增登入或資料庫。
• 不自行生成品牌文案。
• 不升級 dependencies。
• 不改指定資料夾以外檔案，除非先提出必要證據。

Agent 常基於「順便整理」擴大 diff。若某項額外修改真的必要，它應先說明與核心目標的因果關係，而不是完成後才在摘要出現。

Reference：學習特徵，不複製成品

提供 reference 時，先拆成四類：

1. 保留：你自己產品已有且不可失去的品牌、內容與操作。
2. 借鑑：reference 中希望理解的具體特徵，例如留白節奏、卡片密度、導覽收合或排版層級。
3. 不借鑑：不適合你的內容、商業模式、文案、圖像與互動。
4. 重新設計：把借鑑特徵如何轉成自己需求，而不是換色複製。

「參考整體感覺」太模糊；「借鑑內容區較窄、標題與內文有明顯節奏、次要操作收進選單，但保留自己的導覽與品牌字型」則可審查。

把美感語言翻成規格

模糊感受	可執行描述
太擠	同組元素維持小間距，段落與區塊增加一級間距；窄畫面不壓縮主要文字行高
沒層級	每頁一個主標題；標題、摘要、metadata 與操作用字級、重量、色彩角色區分
太像模板	移除無功能副標與裝飾卡片；使用真實內容與產品特有操作決定版面
不夠精緻	統一 tokens、邊界與狀態；減少互相競爭的陰影、色彩與字重
手機很亂	指定重排順序、最小可讀寬度、操作固定與否、文字換行及 overflow 行為

這些描述不必包含每一個 pixel，但要說出關係與失效條件。

Acceptance criteria 必須可判斷

「看起來好看」「效能良好」「支援響應式」都無法直接判斷。改成：

• 在 320px、768px、1280px 寬度下，主要流程無水平捲動、遮擋或不可點擊區域。
• 長標題能自然換行，不截斷主要資訊。
• 鍵盤能依閱讀順序到達所有主要操作，焦點可見。
• API loading、empty、error、success 都有明確且可恢復的畫面。
• Console 無未解釋錯誤，相關 request status 與 response 符合契約。
• 指定 lint、typecheck、test、build 通過。
• Git diff 僅包含已同意範圍。

不是所有任務都要用相同條件。選擇能證明這次目標的最小充分集合。

讓 Agent 先理解，再改檔

好的開始順序：

1. 讀最深層專案規則、README 與直接相關檔案。
2. 回報目前架構與可驗證事實。
3. 指出未知、假設與需求衝突。
4. 提出最小修改範圍與驗證方法。
5. 確認後實作。

這不是要求 Agent 寫冗長計畫，而是防止它根據框架慣例猜錯 repository。小任務可以很短，但仍要說清楚會改什麼和怎麼確認。

Diff 是合作介面

你不需要逐字理解所有程式，仍可從 diff 問出重要問題：

• 改動檔案是否都和任務有直接關係？
• 是否出現大量重新格式化，掩蓋真正邏輯？
• 是否新增 dependency、環境變數或公開 endpoint？
• 是否刪除原有錯誤處理、測試或可及性屬性？
• 是否出現 placeholder、秘密、any、大量 as 或 !important？
• 是否修改 lockfile，原因可否解釋？

Diff 不告訴你 runtime 一定正確，但能確認變更邊界，並決定下一步要看哪些測試與 browser 證據。

迭代時一次只修一個可驗證問題

Agent 第一版不理想時，不要只說「再更好一點」。指出一個可觀察差距，例如：「桌面版資訊層級成立，但 375px 時標題、metadata 與操作擠在同一列；請只調整 header 的窄畫面重排，不改文字與桌面版。」

小迭代讓你知道是哪個改動造成改善或退步，也保留 rollback 能力。一次把視覺、資料、路由與 dependency 全改掉，會失去因果。

可直接使用的任務骨架

背景與使用者：
本次可觀察目標：

必須做：
非目標：
允許修改範圍：
不可修改內容：

真實內容與資料：
頁面／route：
component 與重用邊界：
狀態與互動：
server／client／secret：

視覺規則：
responsive 行為：
鍵盤與可及性：

驗收條件：
必須執行的測試：
完成後要提供的證據：

開始前請先讀專案規則與現況，回報假設、衝突、最小修改方案與驗證方法。未知處標成未知，不要自行補內容或擴大範圍。

更多可重用欄位：Learning/ai first frontend foundations/toolkit

操作練習：重寫「做得高級一點」

1. 選一個你真的想改善的頁面。
2. 寫下最主要使用者與要完成的任務。
3. 將你的三個美感感受各翻成可觀察關係。
4. 提供真實內容，標出未知而不請 Agent 自行補文案。
5. 列出 initial、loading、empty、error、success 與 disabled。
6. 設定 3–7 個 must-have 和至少 3 個 non-goals。
7. 為每個 must-have 配一項驗證證據。
8. 讓 Agent 先回報理解，再只實作最小版本。
9. 審查 diff、browser 與自動化證據，記錄下一個小迭代。

常見誤判

• 「Prompt 越長越準」：長度不等於資訊品質，重複與矛盾反而造成漂移。
• 「給 reference 就不用寫規格」：Agent 不知道你要借鑑哪個特徵，也可能造成過度相似。
• 「Agent 會自動補完整狀態」：沒有明確狀態矩陣，它只能猜。
• 「先做出來再看比較快」：若資料、路由或安全邊界錯誤，後續視覺調整都是浪費。
• 「測試通過就不用看 diff」：測試可能沒有覆蓋擴張範圍、秘密與文案變更。
• 「一次改多一點比較有效率」：失敗後無法知道哪個變更造成問題。

Teach-back 題目

1. 為什麼 Agent 速度越快，模糊需求的風險反而越大？
2. 產品、內容、互動、視覺、技術與證據六層各解決什麼問題？
3. 如何使用 reference 而不讓成果變成機械複製？
4. 什麼樣的 acceptance criterion 才能真正判斷通過或失敗？
5. 你不熟悉全部程式時，仍能從 diff 審查哪些風險？

上一課：Learning/ai first frontend foundations/07 nextjs server client boundaries

下一課：Learning/ai first frontend foundations/09 debugging release and rollback