從資深全端工程師轉型 Harness Engineering：完整教學指南

在台灣工程師薪資三層結構中，大多數全端工程師仍深陷 Commodity 層——靠 CRUD、接單與工時換取薪水，面對案源減少與薪資停滯的壓力。此時，Harness Engineering 提供了一條清晰且務實的升層路徑：把你從「寫程式的人」，轉變為「設計 AI 工作系統的人」，穩步從 Commodity 層走向 Product 層，乃至 Leverage 層。

什麼是 Harness Engineering？

Harness Engineering 是一種 AI-native 的工程方法論。它專注設計與管理 AI Agent 的執行環境，讓 AI 不再只是偶爾使用的聊天工具，而是能被結構化控制的系統性生產力單位。

它的核心不在 Prompt，而在於打造一個讓 AI 穩定運作、可觀測、可自動修正的工作系統——這就是 Harness。 工程師的角色也因此完成本質轉變：從 Execution（執行者）進化為 System Design（系統設計者）。

這正是全端工程師最自然的轉型優勢。你過去寫 API、管狀態、規劃架構、處理錯誤的經驗，幾乎可以直接對應到 AI Agent 的系統設計。

核心觀念轉移：從「實作」到「設計規則」

傳統全端工程師每天在寫 API、管狀態、修 Bug。這些能力在 AI 時代並沒有消失，而是被重新抽象到更高層次：

傳統能力	Harness 對應能力	價值層級提升
寫 API	Tool Schema 與能力接口設計	Commodity → Product
狀態管理	Agent Memory 與狀態機	Product → Leverage
系統設計 / CI/CD	Workflow 控制與 Evaluation Loop	Leverage 核心
Logging / Monitoring	Agent Observability	決定系統成敗

關鍵轉變在於：工程不再是「我來把功能做出來」，而是「我來設計 AI 如何可靠地完成工作」。

Harness 系統的三大核心模組

一個成熟的 Harness，通常建立在三個相互協作的層級上：

1. Memory（狀態層） 讓 AI 擁有持續性與長期上下文能力，包括短期 Context、向量資料庫長期記憶，以及任務狀態機。 重點不在記住多少，而在如何有效使用記憶。
2. Tools（能力層） 讓 AI 能安全地與真實世界互動——API 调用、程式執行、資料庫查詢等。 關鍵是把外部能力轉化為精心設計的接口，避免誤用。
3. Workflow（控制層） 定義 AI 的思考與行動規則，常見模式包含 ReAct、Plan-and-Execute、Reflection 與 Multi-Agent 協作。 這裡決定了系統的智商與穩定度。

Harness Engineer 的四項核心能力

真正區分高低階的，不是會不會用 LangGraph，而是能否設計好以下四件事：

• 狀態設計：如何避免上下文污染？如何從中斷中恢復？
• 工具抽象：如何讓 API 成為 AI 可安全使用的能力？
• 流程控制：何時該反思、何時該修正？如何防止錯誤擴散？
• 可觀測性：你必須清楚看見 AI 每一步在想什麼、為什麼這麼決定。

沒有可觀測性，就沒有 Harness。這句話幾乎是這個方法論的底線。

三階段轉型路徑（8–12 週可見成效）

Phase 1：Agent Awareness 先理解 AI 的行為模式，熟悉 ReAct、Plan、Reflection 等基本模式。每天用 Cursor + Claude 完成工作，並拆解失敗點。

Phase 2：System Construction 用 LangGraph 搭建完整 Harness，包含 Memory、Tool、Evaluator Loop。這階段你會開始感受到「機制大於提示」的威力。

Phase 3：Multi-Agent System Design 進入 Planner + Executor + Critic 的多 Agent 架構，處理更複雜、長期性的任務。這時你已真正站在 Leverage 層。

核心心法：決定你能走多遠

1. 機制優於提示：AI 出錯時，別急著改 Prompt，而是問：「我要設計什麼機制，讓這個錯誤永遠不再發生？」
2. 系統要薄：越簡潔、可控、可替換的 Harness，越可靠。過度工程化往往適得其反。
3. Human-in-the-Loop：人類永遠要在關鍵決策點上，逐步把自動化程度拉高。
4. 可觀測性至上：看不見的系統，就不是系統，只是黑盒。

從個人轉型到公司求生

對個人而言，Harness 可直接應用在 Code Review Agent、技術文章生成系統、個人第二大腦等實戰專案。

對接案公司來說，這更是翻身武器。傳統「賣時間」的 Commodity 模式已失效。Harness 能幫助你：

• 內部降本 50% 以上（1–2 人支撐原本 4 人工作）
• 快速產品化：打包「一鍵後台 Agent」「電商資料清洗 Agent」「SEO 內容生成 Agent」等模板對外販售
• 服務升級：以「自有 Harness 縮短 60% 開發時間」作為差異化賣點，重新吸引願意付費的中小企業客戶

起步建議：先花 7 天建立公司內部最小可用 Harness（Company-Survival-Harness），跑通真實任務後再對外推廣。

結語：AI 時代的結構性升層

Harness Engineering 的本質，是把 AI 從「工具」變成「可控的生產系統」。

它完美呼應了台灣工程師的薪資三層結構： 把 Commodity 層的線性工作交給 AI， 在 Product 層實現 ROI 導向的交付， 在 Leverage 層打造可重複、具乘數效應的系統。

AI 並未壓縮工程師的整體價值，而是壓縮了線性、可被商品化工作的空間。真正稀缺的，永遠是系統設計、流程控制與可觀測性設計的能力。

3 個月內，如果你能打造出屬於自己的 Harness 模板，就能在 AI 時代握有更強的議價力與收入主動權。

現在，就從你的第一個 LangGraph 專案開始。 把 AI 真正變成可信任的工作系統。

台灣低薪工程師的惡性循環：AI 如何加速「乖乖接單」文化下的困境

台灣工程師薪資分層：AI 時代的結構性重構

台灣科技業低薪現象早已不是新聞，但在 AI 時代卻變得更加清晰且刺眼。許多工程師月薪卡在 5-7 萬甚至更低，工作量與壓力未減，薪資成長卻近乎停滯。這不是單純的「個人不夠努力」，而是產業結構長期定價的結果。AI 並非造成低薪的元兇，而是加速了薪資市場的三層分化。

三層市場結構與判定標準

台灣工程師的薪資分布，本質上是一種三層市場結構。三個層級的差異，不在職稱或公司，而在於「價值是否與輸出綁定」以及價值計算單位的不同。

以下是簡單的判定表：

層級	價值來源	薪資決定因素	典型特徵
Commodity	工時 / 任務完成	市場供給價格	CRUD、外包、接單型、高度標準化
Product	產品成果 / ROI	業務成長貢獻	產品設計、系統規劃、用戶價值交付
Leverage	系統影響力 / multiplier	決策與槓桿效應	AI Infra、架構師、Domain Expert、跨域整合

判定方式：

• 如果你的工作主要被衡量「完成了多少 ticket / 工時」，且容易被其他人或工具替換，你多半處在 Commodity 層。
• 如果工作成果直接影響產品指標（留存、營收、效率提升），則進入 Product 層。
• 如果你的決策或設計能放大整個系統的效能、降低大規模成本，或開創新可能性，即屬 Leverage 層。

一個人可以跨層（例如同時處理 Commodity 任務但主導 Leverage 專案），但長期薪資主要由你主要價值貢獻的層級決定。

AI 改變價值密度分布

AI 不是單純的「壓低薪資工具」，而是改變價值密度分布的結構性力量。

• 過去：1 位工程師 ≈ 1 單位線性產出。
• 現在：1 位工程師 + AI ≈ N 倍 Commodity 產出（boilerplate、測試、簡單功能）。

AI 並未壓縮工程師整體價值，而是壓縮「線性價值工作」的存在空間。它讓可標準化任務的邊際成本大幅下降，導致 Commodity 層需求減少、競爭加劇；同時，Product 層的迭代速度加快，Leverage 層的乘數效應則被大幅放大。高階人才搭配 AI 後，一個人的影響範圍能從原本的幾倍擴大到數十倍。

這解釋了為何我們同時看到「初階職缺遇缺不補」與「AI 相關高階人才薪資持續上漲」的並存現象。

結構決定上限，行為決定位置

產業結構（代工型態、內需導向、供給過剩）決定了整體價格上限，尤其是 Commodity 層。工程師的風險規避行為（接受低薪、不敢跳槽），主要是維持了這個結構，而非根本造成它。市場上仍有外商進入、技術變遷等力量，但對高度商品化的工作而言，這些力量目前還不足以徹底改變定價邏輯。

不是「乖乖文化」，而是「風險結構問題」

低流動性的真正原因在於現實的風險結構：

• 高房貸與生活成本
• 跳槽失敗的非線性損失（家庭、年資、保險）
• 缺乏完善的安全網
• 薪資資訊不透明

這是理性選擇，而非性格缺陷。它讓 Commodity 層的供給持續充沛，進一步穩固了該層的定價區間。

如何在結構中升層？

關鍵不在努力程度，而在於你目前的工作是否仍具有不可商品化的價值。

具體路徑：

• 把 AI 當杠杆：用它快速處理 Commodity 任務，釋放時間投資 Product/Leverage 能力。
• 累積可量化的 Impact（ROI、成本節省、產品指標），而非僅描述工時。
• 提升流動性與透明度：定期評估市場、參與社群。
• 朝 Leverage 轉型：深化 AI 整合、系統架構、領域知識，或將專業變現（課程、SaaS、顧問）。

結語：結構定價的核心命題

台灣工程師的薪資分化，不是個人努力差異，而是產業結構對「可替代性工作」的重新定價結果。

AI 的出現沒有改變這個結構，只是加速了價值分布的極化：

• 可標準化工作被快速商品化
• 產品導向工作與 ROI 緊密綁定
• 槓桿型能力持續放大影響力

因此，薪資差距的本質不再是「薪水談判問題」，而是你所處價值層級的問題。

當你清楚自己在哪一層，並有意識地往上移動，AI 就會從威脅轉為強大的杠杆。市場不會主動拯救任何人，但結構性的理解，能幫助我們做出更精準的選擇。

你目前的工作，主要貢獻在哪一層？又準備如何移動？

🚀 AI 在軟體開發中的真實角色：把「寫 code 的問題」變成「審 code 的問題」

近年媒體不斷高喊「AI 即將取代程式員」，彷彿只要會用 Claude 或 Cursor，就能大幅提升生產力甚至完全取代人類開發者。但作為第一線開發者，我們必須保有清醒認知：AI 並沒有讓軟體工程變簡單，它只是把「寫 code 的問題」變成「審 code 的問題」。

AI 是強大的生產力工具，但遠非全能。它最擅長產生「看起來正確」的程式碼，卻在隱藏錯誤、系統性思考與長期維護上暴露出明顯局限。本文從 AI 本質限制出發，分析錯誤根源，最後說明頂尖開發者如何重新定位自己，打造有效的 AI 協作系統。

I. AI 的本質限制（Why it fails）

AI 在實際開發中存在幾個結構性弱點，這些限制不會因為模型參數增加而輕易消失：

1. 嚴重的上下文與記憶限制 AI 難以完整掌握大型專案的檔案依賴、歷史決策與團隊慣例，極易產生幻覺或前後矛盾。
2. 邊界條件與複雜邏輯處理薄弱 在並發、複雜業務規則、效能優化與邊緣案例上，錯誤率顯著上升。
3. 缺乏真正的商業理解與判斷力 AI 無法真正理解使用者痛點、公司戰略、長期維護成本與業務影響。
4. 大型系統整合與架構能力不足 跨模組、跨系統的整合仍是 AI 的明顯弱點。
5. 沒有責任感與最終把關能力 AI 不會為結果負責，最終的穩定性、安全性與可維護性，永遠落在開發者身上。

這些限制意味著：AI 目前最適合處理 Commodity 層的線性任務，而在 Product 與 Leverage 層的系統性工作上，仍高度依賴人類。

II. 為什麼這些錯誤這麼常發生？（Root Causes）

這些錯誤並非偶然，而是由 AI 的運作機制所必然導致：

• 上下文窗口限制：即使是 2026 年的最新模型，處理超大型 codebase 時仍會遺漏關鍵資訊。
• 訓練資料偏誤：大多數訓練資料來自公開程式碼，對於特定產業、內部系統或最新實務的理解相對薄弱。
• 過度自信的回答風格：AI 傾向以確定語氣輸出，即便不確定也很少主動標註風險。
• 缺少真正責任感：AI 沒有後續維護壓力，因此不會主動考慮長期可維護性與技術債。

結果就是常見的程式碼錯誤類型：幻覺（Hallucination）、安全性漏洞、邊界條件缺失、效能問題、與專案不一致，以及隱形錯誤。

III. 工程師的重新定位：從執行者到系統審計師與 Harness 設計者

因此，問題的核心不在於 AI 能不能寫 code，而在於人類如何重新設計協作方式。

認清限制後，真正具競爭力的開發者不會與 AI 競爭「誰寫得快」，而是轉向更高價值的位置——系統審計師、架構把關者，以及 Harness Engineering 的設計者。我把 AI 視為「高效率但需要嚴格監督的資深工程師」，自己則負責最終把關與系統設計。

核心實戰框架：AI Engineering Workflow

以下是我在實務中長期驗證的 AI 協作系統，而非單純的個人 SOP：

1. Context Engineering：給予充足、結構化的上下文（專案背景、既有程式碼、業務規則、非功能需求）。
2. 分步生成與迭代：不一次要求完整實作，而是逐步拆解任務。
3. Cross-model Validation：將相同需求丟給 Claude、GPT-4o、Gemini、Grok 等不同模型，比較輸出差異，找出各自盲點。
4. 嚴格 Code Review + 測試：人工審核、撰寫單元測試與整合測試。
5. 逐步整合與持續觀測：在真實環境中驗證，並建立可觀測機制。
6. Harness 機制設計：對於重複性任務，逐步打造包含 Memory、Tools 與 Workflow 的 Harness，讓 AI 能在受控環境中穩定運作。

這套框架把 AI 的速度優勢與人類的判斷力結合，既能快速原型與實驗，也能確保最終交付的穩定性、可維護性與商業價值。

結論：AI 時代真正的競爭力

AI 大幅降低了產生程式碼的門檻，但「做出正確、穩定、有商業價值且可長期維護的軟體」的難度並沒有降低。它反而對工程師的審核能力、系統思維與工具駕馭能力提出了更高要求。

在 AI 時代，真正的競爭力不在於「產出能力」，而在於「驗證與控制能力」。能夠設計 AI 協作系統的人，才真正具備從 Commodity 層走向 Leverage 層的結構性優勢。

保持理性認知，建立嚴謹的 AI Engineering Workflow，並持續精進 Harness Engineering 能力，這才是開發者在這個時代最堅固的護城河。

馴服 AI Agent：在中大型專案中建立「永不幻覺」的開發協議

在 AI Agent 已全面進入 production workflow 的開發環境中（如 Antigravity、Cursor Agent mode），真正的瓶頸不再是生成能力，而是上下文污染與系統一致性。AI-native 開發的核心，不是提升 AI 能力，而是設計 AI 的認知邊界（cognitive boundaries）。當專案使用 Astro 5 + Vue 3 + Laravel 12 + Filament v3 這樣複雜的全端技術棧時，AI 極易因記憶漂移而虛構 API 格式、破壞商業邏輯或使用錯誤套件語法。

Prompt Engineering 的時代已經結束。解決方案是建立一套結構化的 AI System Design Stack，讓 AI 從「容易幻覺的助手」轉變為「遵守明確邊界的可靠執行官」。

AI System Design Stack：三層控制架構

1. Execution Boundary Layer（行為控制層）—— Agent Runtime Governance

這一層定義「AI 能知道什麼、不能做什麼」，是防幻覺的基礎。

建立 AI Execution Control Plane（原 .antigravity 升級版）：

text

.ai-control-plane/
├── core/                  # 技術邊界
│   └── TECH_STACK.md
├── contracts/             # 介面合約
│   └── API_CONTRACT.md
├── domain/                # 商業規則
│   └── BUSINESS_LOGIC.md
├── guardrails/            # 禁止與防護
│   └── FORBIDDEN_PATTERNS.md
└── scoring/               # 評分機制
    └── SCORING_SYSTEM.md

核心文件範例：

• TECH_STACK.md：嚴格鎖定版本與禁止語法
• BUSINESS_LOGIC.md：使用字典 + Mermaid 流程圖定義訂單狀態機、權限規則等

實戰指令模板：

• Reference Discovery：要求 AI 先閱讀所有規則文件並找出相似參考
• Plan First：強制先輸出執行計畫，確認後才產生程式碼

2. Efficiency Layer（效率控制層）—— AI Development Efficiency Model (AIDEM)

AIDEM 定義了如何在 Context、Contract、Execution、Model 四個層面控制 AI 系統，最大化輸入/輸出比（I/O Ratio）。

Layer	Purpose	核心機制	預估節省
Context	輸入控制	.ai-control-planeignore + 精準 Pinning	20-40%
Contract	規則控制	模組化 Markdown + 精煉指令	10-25%
Execution	行為控制	Plan First + Diff Mode + One-Shot	15-30%
Model	算力分配	模型路由 + Clear History	30-50%

綜合應用可降低 40%~70% Token 消耗，讓中大型專案的 AI 開發從「燒錢」變成「可控」。

3. Schema Layer（資料控制層）—— Contract-first Architecture

AI 系統最大問題不是邏輯錯誤，而是 schema ambiguity（結構不確定性）。

spatie/laravel-data 正是 Schema Layer 的實戰參考實現。它提供單一真理來源（SSOT），讓 Model → DTO → API → 前端 TypeScript 形成嚴格一致的合約鏈。

PHP

#[TypeScript]
class OrderData extends Data
{
    public function __construct(
        public string $order_no,
        public int $amount_cents,  // 分為單位
        // ...
    ) {}
}

Controller 簡化為一行，AI 只需閱讀一個檔案即可完全理解輸出結構。搭配 laravel-typescript-transformer，前後端型別自動同步，大幅壓縮幻覺空間。

這是 Schema-level Control 的具體落地：AI 需要的是確定性，而不是模型自由度。

從 Prompt-Driven 到 Boundary-Driven

在 AI-native 開發時代，系統的穩定性不再主要來自 code quality，而是來自schema consistency（資料一致性） 與 execution boundary design（執行邊界設計）。

• Execution Boundary Layer 解決行為一致性
• Schema Layer 解決資料一致性
• Efficiency Layer 確保可規模化

三層結合，構成真正可控、可觀測、可維護的 AI 開發系統。這也正是全端工程師從 Commodity 層 升級到 Leverage 層 的結構性路徑。

立即行動：

1. 建立 .ai-control-plane/ 並填入核心規則文件
2. 導入 spatie/laravel-data + TypeScript Transformer
3. 在最容易出錯的模組先建立 BUSINESS_LOGIC.md，並套用 AIDEM 流程

Prompt 時代已過，Boundary-Driven 時代才剛開始。當 AI 再次出現幻覺時，別急著在聊天視窗糾正它——去完善你的認知邊界設計。這才是生產級、規模化 AI 輔助開發的正確心法。

在 Google Antigravity 中大幅降低 Token 消耗的實戰指南

 在 Google Antigravity 中大幅降低 Token 消耗的實戰指南

—— Agent-First IDE 的上下文與成本優化技巧使用 Google Antigravity 這類 Agent-First IDE 時，Agent 會頻繁讀取專案上下文以維持邏輯連貫，因此 Token 消耗速度遠高於傳統 Chat 模式。一個不小心，複雜任務就可能燒掉數十萬 Token。本文整理出一套系統化的省 Token 策略，幫助你在 Astro + Vue 3 + Laravel 等全端專案中，既保持開發效率，又有效控制成本。

---

一、核心思維：精確的上下文控制（Context Control）Agent 不需要每次都看到整個專案。過大的上下文不僅貴，還容易造成記憶漂移和幻覺。1. 使用 .antigravityignore 精準排除無用檔案在專案根目錄建立 .antigravityignore 檔案，內容比 .gitignore 更嚴格：

ignore

# Antigravity 專用忽略清單
node_modules/
vendor/
dist/
build/
.git/
*.log
*.sqlite
*.png
*.jpg
*.jpeg
*.gif
*.webp
public/build/
storage/framework/cache/
storage/framework/sessions/

效果：避免 Agent 讀取大型依賴套件、編譯後檔案與圖片，大幅減少索引 Token。2. 精準選擇檔案（Targeted File Selection）

• 不要對整個專案提問
• 使用 Antigravity 的 @檔案路徑 或 Pin 功能，只選取當前任務相關檔案
  • 例如：同時 Pin app/Services/UserService.php + src/composables/useUser.ts + resources/views/filament/pages/user-settings.blade.php
• 任務結束後，立即清除對話歷史 或重置 Context，避免舊對話變成永久負擔

---

二、規則文件優化（Rule Compaction）規則文件雖然重要，但太長會每次都被讀取，造成嚴重 Token 浪費。最佳實踐：

1. 模組化拆分規則
   • LARAVEL_RULES.md（後端專用）
   • VUE_RULES.md（前端 Vue 專用）
   • ASTRO_RULES.md（Island 與 Client 指令專用）
   • FILAMENT_V3_RULES.md（Admin 面板專用）
   • 只在對應任務時才掛載相關規則
2. 精煉 Markdown 寫法
   • 減少敘述性段落，多使用結構化清單與表格
   • 使用粗體關鍵字突出重點
   • 每個規則控制在 1~2 行以內
   • 優先使用「禁止事項」與「強制做法」格式

---

三、流程優化：減少無效思考循環1. 強制「Plan & Approve」機制在重要任務的 Prompt 中加入：

「Before writing any code, first show me your execution plan in detail, including which files you will modify and why. Wait for my approval before proceeding.」

這一步能大幅減少 Agent 盲目嘗試所浪費的 Token，通常可省下 30%~50% 的無效消耗。2. 智慧模型切換策略

任務類型	推薦模型	理由
簡單修改、補註解、格式化	Gemini 1.5 Flash	速度快、價格極低
中等任務、單檔案調整	Gemini 1.5 Flash / Pro	平衡成本與能力
複雜重構、多檔案協作	Claude 3.5 Sonnet / Gemini 1.5 Pro	推理能力強
架構設計與審核	Claude 3.5 Sonnet	長上下文理解佳

---

四、減少幻覺糾正的 Token 浪費「跟 Agent 吵架修正錯誤」是最燒 Token 的行為之一。有效做法：

1. 提供精確片段
   直接貼上相關的 interface、function signature 或既有程式碼片段，讓 Agent 參考，而不是讓它自己掃描目錄。
2. 使用 One-Shot Prompt
   在提示詞中直接給一個「正確示範」的小範例：
   markdown

   正確範例（請嚴格遵循此風格）：
   ```ts
   export const useApi = <T>(endpoint: string) => { ... }

3. Reference Discovery 結合精準參考
   要求 Agent 先參考特定檔案，而不是整個目錄。

---

五、工具層面省錢技巧總表

技巧	說明	節省潛力
Clear History	每個功能完成後清空對話
Manual Indexing	關閉自動全專案索引，只手動觸發
.antigravityignore	排除無用大型檔案與目錄
模型切換	小任務用 Flash，大任務用 Pro/Sonnet
Local LLM	簡單補全使用 Ollama 本地模型
Pinned Files	只 Pin 當前任務相關的 3~5 個檔案

---

總結：最省 Token 的正確使用心法在 Antigravity 中，最有效的省錢行為是**「先思考，再提問」**。

• 每次提問前先整理好相關檔案
• 重要任務先要求 Agent 輸出 Plan
• 善用模組化規則與精準上下文
• 任務結束立即清理歷史

實測下來，妥善使用以上策略，通常能節省 40%~60% 的 Token 消耗，同時還能降低幻覺發生率，讓開發流程更順暢。

跨專案防幻覺指南：利用 Laravel-Data 打造 AI 時代的「高感度」全端架構

在前後端分離（Decoupled）的架構中，最燒 Token 的行為莫過於讓 AI Agent 在兩個獨立目錄間反覆橫跳、搜尋 API 欄位。透過 spatie/laravel-data，我們可以建立一個強大的「資訊地圖」，讓 AI Agent 讀取最少的檔案，精準寫出 100% 正確的代碼。

---

為什麼這是 AI 開發的最佳實踐？

傳統開發中，後端 API 資訊散落在 Controller、Resource 和 Model。對 AI 來說，這意味著要讀取數千個 Token 才能拼湊出一個 API 格式。

使用 Laravel-Data 後：

• 高壓縮比： 一個 200 Tokens 的 Data 類別，包含了驗證、DTO 與回應格式。

• 零幻覺： 強型別約束讓 Agent 沒有猜測空間。

• 跨專案解耦： 前端 Agent 只需「投影」後端的 Data 類別，無需理解後端實作細節。

---

第一階段：後端架構 —— 建立單一真理來源 (SSOT)

在 Laravel 12 中，我們廢棄傳統的 Resource，改用 Data 類別。

1. 安裝套件

Bash

composer require spatie/laravel-data

2. 定義資料合約 (Contract)

建立 app/Data/ProductData.php。這就是 AI 唯一需要閱讀的「合約」。

PHP

<?php

namespace App\Data;

use Spatie\LaravelData\Data;

class ProductData extends Data
{
    public function __construct(
        public int $id,
        public string $title,
        public int $price_cents, // 以分為單位，防止 AI 算錯浮點數
        public ?string $description,
        public bool $is_published,
        /** @var string[] */
        public array $tags,
    ) {}

    public static function fromModel($product): self
    {
        return new self(
            id: $product->id,
            title: $product->name,
            price_cents: $product->price,
            description: $product->desc,
            is_published: $product->active,
            tags: $product->tags->pluck('name')->toArray(),
        );
    }
}

---

第二階段：Antigravity 配置 —— 建立 AI 存取協議

要在前端目錄開發時不產生幻覺，我們必須在專案根目錄建立規則。

1. 建立 .antigravity/rules/API_RULES.md

Markdown

# API 溝通協議
1. **參考對象**：前端開發時，必須優先讀取後端目錄 `@backend/app/Data/` 下的對應 Data 類別。
2. **禁止自創欄位**：嚴禁根據猜測撰寫 Vue 組件中的變數名，所有欄位必須與 Data 類別屬性 100% 匹配。
3. **回應結構**：API 成功回傳統一為 `{ "data": T }`。

---

第三階段：實戰工作流 —— 如何省下 70% Token？

這是最核心的操作技巧，避免讓 Agent 漫無目的地搜尋。

Step 1: 精準 Pin (釘選)

當你需要開發「產品列表」前端功能時，不要讓 Agent 掃描整個後端。

指令範例：

「我要實作產品列表 UI（Vue 3）。請參考後端的 @backend/app/Data/ProductData.php，幫我產生對應的 TypeScript Interface，並完成列表渲染邏輯。」

Step 2: 檔案投影 (Projecting)

Agent 讀取 ProductData.php（約 200 Tokens）後，會在前端生成：

TypeScript

interface Product {
  id: number;
  title: string;
  price_cents: number;
  description: string | null;
  is_published: boolean;
  tags: string[];
}

一旦 Interface 生成完成，立刻解除釘選 (Unpin) 後端檔案。接下來的 UI 調整，Agent 只需要看這份 Interface，不再需要回頭讀取後端。

---

第四階段：總結 —— 效益對比

指標	傳統全端開發	Laravel-Data + Antigravity 模式
Token 消耗	高 (需掃描 Route, Controller, Model)	極低 (精準讀取單一 Data 檔)
AI 幻覺率	高 (常猜錯欄位名、忘了 nullable)	接近 0 (屬性即合約)
維護成本	高 (修改後端要手動改三處)	低 (只需修改 Data 類別)

架構師建議

在中大型網站中，AI 的效率取決於你給它的「資訊密度」。laravel-data 將原本混亂的 API 結構壓縮成一份乾淨的「說明書」。

當你讓 Antigravity 的 Agent 習慣於「先讀 Data 檔，後寫前端碼」的節奏時，你不但省下了大筆的 Token 費用，更獲得了一個永遠不會寫錯 API 欄位的完美隊友。