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

 Harness Engineering 的核心是「為 AI Agent 設計穩定、可控、高效的運行環境」。這與全端工程師日常做的系統設計、狀態管理、架構規劃、錯誤處理等工作高度重疊。

轉型優勢：

• 你已經具備狀態管理、API 設計、測試流程、監控等經驗，能快速對應到 Agent 系統設計。
• 產業正從「寫程式」轉向「設計 AI 工作系統」，這正是全端工程師的優勢領域。

二、轉型前的心態準備

1. 從「我來實作」轉變為「我來設計規則與環境」。
2. 接受「Agent 會犯錯是常態，關鍵在於如何讓系統自動修正」。
3. 重點不再是 Prompt，而是機制設計（Mechanism Design）。

三、階段性學習路徑（建議 8–12 週）

階段 1：基礎認知（第 1–2 週）

• 理解 Harness 的定義：Harness = Agent 的作業系統，包含記憶、工具、流程、安全、驗證等模組。
• 熟悉核心 Agent Pattern：
  • ReAct（Reason + Act）
  • Plan-and-Execute
  • Reflection / Self-Critique
  • Multi-Agent Collaboration
• 每天練習純用 AI 完成工作，記錄失敗點。

建議作業：用 Claude 或 Cursor 獨立完成一個小專案（例如自動生成 API 文件），並分析它失敗的原因。

階段 2：核心技能對應與補強（第 3–6 週）

利用你既有的全端經驗加速學習：

原全端技能	Harness 對應能力	建議練習重點
Redux / Zustand	Agent Memory & State Machine	LangGraph 狀態圖
RESTful API 設計	Tool Calling + Function Schema	自訂工具開發
單元測試 / CI/CD	Evaluator Agent + Verification Loop	自動評估機制
Docker / 部署	Sandbox Execution Environment	安全執行沙箱
Logging + Monitoring	Agent Observability & Tracing	完整思考追蹤

必學工具與技術：

• LangGraph（推薦優先）：用來建構可靠的 Agent 工作流
• 向量資料庫（Pinecone / Chroma / PGVector）
• 沙箱執行環境（E2B、Docker、Sandbox）
• Guardrails 框架（防止 Agent 越界）

階段 3：實戰專案練習（第 7 週起）

按難度由易到難練習：

1. 入門專案：自動化 Code Review Agent
2. 中階專案：全自動技術文章生成系統（研究 → 撰寫 → 校對 → 格式化）
3. 進階專案：個人第二大腦 Agent（支援長期記憶與跨任務協作）
4. 挑戰專案：多 Agent 協作系統（Planner + Executor + Critic）

每個專案都必須包含以下 Harness 組件：

• AGENTS.md（角色定義）
• 持久化記憶模組
• 工具與沙箱
• Evaluator 驗證機制
• Guardrails 安全規則
• 完整 observability 追蹤

四、實戰教學重點心法

1. 機制優先於提示 當 Agent 出錯時，問自己：「我要如何設計一個機制，讓這個錯誤永遠不再發生？」
2. 保持簡約 優秀的 Harness 通常很薄。避免過度工程化（Over-Engineering）。
3. 人類始終在迴路中 先做好 Human-in-the-Loop 設計，再逐步提高自動化程度。
4. 可觀測性決定一切 必須能清楚看到 Agent 的每一步思考、決策與 Token 使用。

五、推薦學習資源（2026 年最新）

• 框架：LangGraph（最推薦）、CrewAI、AutoGen
• 工具：Cursor + Claude 3.5/Opus 作為主要開發環境
• 社群與文章：搜尋「Harness Engineering」中文教學、Mitchell Hashimoto 相關討論
• 實作參考：GitHub 上搜尋 LangGraph 範例專案

六、下一步行動清單

• 建立第一個 LangGraph 專案
• 完成一個包含 Evaluator 的完整 Agent
• 把專案放到 GitHub，並詳細寫 README（重點描述 Harness 設計）
• 每週至少完成一個小型 Agent 任務

---

結語

從全端工程師轉型 Harness Engineering，是把你的系統設計能力提升到 AI 原生時代的自然進化。這個領域目前還在快速發展，具備良好工程思維的人擁有巨大優勢。

只要跟著上述步驟穩步練習，3 個月內你就能建立起屬於自己的 Harness 模板，並開始應用在實際工作中。

如果你在轉型過程中遇到具體問題（例如 LangGraph 如何建構狀態機、Evaluator 如何設計等），歡迎提出，我可以提供更細部的教學與程式碼範例。

開始行動吧！把 AI 從「聊天工具」真正變成「可信任的工作系統」。

接案公司案源斷絕的問題分析、解決方案與實作教學

以下內容針對「連案子都接不到」的接案公司，採用問題分析 → 解決方案 → 實作步驟的結構，提供務實且可立即執行的轉型指南。

一、問題分析

核心問題：

• 傳統全端接案模式（人力密集開發）已經嚴重過時。客戶能以更低價格在 Upwork、Fiverr 或用 AI 工具（如 Cursor、Claude）自行解決部分需求。
• 市場供給過剩：大量工程師與小型團隊競爭，價格被持續壓低。
• 公司競爭力不足：缺乏明顯差異化，交付速度慢、成本高、可重用性低。
• 結果：案源快速枯竭，現金流斷裂，人力成本成為沉重負擔。

深層原因：

• 客戶真正想要的不再是「寫程式的人」，而是快速、穩定、低維護成本的解決方案。
• 傳統接案公司仍在「賣時間」，但市場已經轉向「賣效率與系統」。
• Harness Engineering 的出現，正好能解決這個斷層：把 AI 變成可規模化的生產力工具。

如果不轉型，繼續用舊模式，只會加速公司倒閉。轉型 Harness 則能把「人力成本」轉為「系統優勢」。

二、解決方案

整體策略： 用 Harness Engineering 達成 降本 50%以上 + 創造新收入來源 + 建立差異化。

三大解決方向：

1. 內部降本求生：大幅降低人力需求，讓少數人維持公司運作。
2. 產品化變現：把 Harness 打包成可販售的 Agent 模板或小型工具，創造被動/半被動收入。
3. 服務升級：從「接案寫程式」轉為「提供 AI 加速交付 + 可持續 Agent 系統」，重新吸引客戶。

預期效果：

• 1 個月內：把內部運作成本壓低，產生第一筆新收入。
• 3 個月內：建立可重複銷售的產品，穩定現金流。
• 6 個月內：重新回到接案市場，但以更高毛利、更有競爭力的方式。

三、實作步驟（立即可執行）

Step 1：建立最小可用 Harness（第 1–7 天）

目標：用最少資源打造公司內部求生工具。

實作內容：

• 使用 LangGraph + Claude 3.5 / Cursor 快速搭建。
• 建立以下最小結構：

Markdown

Company-Survival-Harness/
├── AGENTS.md                  # 定義 4 個核心 Agent
│   - Researcher（研究需求）
│   - Developer（寫程式）
│   - Reviewer（檢查品質）
│   - Documenter（產出文件）
├── WORKFLOWS/                 # 3 個主要流程
│   - web-feature-dev.json
│   - api-integration.json
│   - refactoring.json
├── TOOLS/                     # 連接 Git、終端機、瀏覽器
├── EVALUATOR/                 # 自動檢查程式碼、Bug、安全問題
├── MEMORY/                    # 向量資料庫（用 Chroma 或 PGVector）
└── GUARDRAILS/                # 基本安全與風格規範

每日實作重點：

• Day 1-3：搭建 LangGraph 基本工作流。
• Day 4-5：加入 Evaluator Agent（讓另一個 AI 檢查輸出）。
• Day 6-7：測試在真實小任務上運行（例如重構一段舊程式碼）。

Step 2：內部全面 Agent 化（第 2 週）

• 把提案書撰寫、需求分析、程式碼審核、文件產出全交給 Harness。
• 團隊每天只做「設計 Harness + 最終決策」的工作。
• 目標：原本需要 4 人的工作，現在 1–2 人即可支撐。

Step 3：快速產品化與變現（第 3–6 週）

可立即販售的產品：

1. 「一鍵後台管理系統 Agent」（售價 NT$8,000–18,000）
2. 「電商資料清洗 + 報表自動化 Agent」
3. 「網站 SEO 優化 + 內容生成 Agent」
4. 「舊程式碼遷移到新框架 Harness」

販售管道：

• Facebook 社團（程式開發、創業、電商）
• PTT Soft_Job、Mobile01
• 小紅書、Threads
• 蝦皮 / 自建 Gumroad

定價與包裝：

• 包含：Harness 模板 + 安裝教學 + 1 週技術支援

Step 4：重建案源（第 6 週起）

• 在提案時強調「使用自有 Harness，可縮短 60% 開發時間」。
• 提供「先付低訂金，驗證成果再付尾款」的模式，降低客戶風險。
• 目標客戶：有預算但想省時間的中小企業（非最便宜路線）。

四、執行注意事項與風險控管

• 從小開始：先在公司內部用，不要一開始就賣給客戶。
• 品質把關：永遠保留 Human Review 最後一步。
• 資料安全：嚴格隔離客戶資料，避免 Agent 記憶混用。
• 每週檢討：紀錄「Agent 省下的人力時數」與「新收入金額」。

---

結語與下一步

問題核心是商業模式過時；解決方案是把 Harness Engineering 當成求生與翻身的核心武器；實作必須從最小可用版本開始，快速迭代。

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

 在台灣科技業，「低薪工程師」早已不是新聞，卻在 AI 時代變得更加刺眼。許多工程師月薪卡在 5-7 萬，甚至更低，工作量不減、壓力不減，薪資成長卻近乎停滯。這不是單純的「工程師不夠努力」，而是一套由產業結構、文化習慣、個人選擇與 AI 共同構成的惡性循環。其中，最核心也最難打破的一環，就是大量工程師「乖乖接單」、怕失業、不敢談薪、不敢跳槽的行為模式。

怕失業 → 接受低薪 → 市場行情被鎖死

台灣工程師普遍供給充足，尤其在前端、網頁、後端 CRUD、App 開發等領域，人數遠多於優質職缺。當公司開出低薪時，許多人選擇「先求有、再求好」： 「至少有份工作」「怕面試失敗」「外面行情也差不多」「轉職風險太高」……

於是他們乖乖接單、加班趕工、默默忍受。一次接受，就形成預期。企業發現「這個價碼就有人做」，便把低薪視為市場常態。下一次招人時，預算不會提高；談薪時，也更有底氣壓價。

這種「低薪 → 接受 → 老闆視為常態」的循環，已經持續多年。它不是陰謀，而是集體恐懼與資訊不對稱的結果。工程師之間很少公開討論真實薪資，怕被貼上「獅子大開口」的標籤；跳槽意願低，又讓企業缺少外部市場壓力。久而久之，行情就被鎖死在中低區間，難以自然上漲。

AI 成為這條惡性循環的強力加速器

2025-2026 年，AI 工具（Cursor、Copilot、Claude、Grok 等）已大幅改變遊戲規則。它直接放大了上述循環：

• 初階與執行型職缺被大量壓縮：一位資深工程師搭配 AI，能快速完成過去需要好幾位初階工程師的 boilerplate code、測試、簡單功能開發。企業「遇缺不補」的情況越來越普遍，初階招聘比例甚至大幅下滑。剩下來的職缺競爭更激烈，薪資談判空間更小。
• 可替代性大幅提高：純「執行者」——只會套框架、寫 CRUD、照需求接單的人——正是 AI 最容易取代的族群。當 AI 把生產力拉高，公司更沒有理由給予高薪。
• 老闆的算盤更精：對中低階職缺，老闆發現「用 AI + 少數願意低薪接單的工程師」就能滿足需求，何必主動加薪？高階人才（架構師、AI 整合、半導體跨域）確實難找、薪資高，但這跟大多數「乖乖接單」的工程師無關。K 型分化因此更加劇烈：少數高價值人才享受 AI 紅利，多數人卻被 AI 進一步壓低薪資天花板。

AI 沒有解決台灣代工、外包、內需導向的產業結構，反而讓「低薪常態」更有正當性。企業利潤沒增加多少，卻能用更低人力成本維持產出，工程師的議價力則被進一步削弱。

文化慣性與個人定位的雙重枷鎖

台灣工程師的「乖乖文化」有其歷史背景：從小被教育要聽話、穩定、別冒險，加上房貸、家庭壓力，讓很多人寧願接受可預期的低薪，也不願面對跳槽的不確定性。這種心態讓市場長期失靈——供給方不敢發聲，需求方自然樂於維持現狀。

更根本的是角色定位。如果只把自己當成「寫 code 的執行者」，AI 時代就會加速你的商品化。反之，若能成為「解決方案設計者」、懂產品、懂商業、懂 AI 整合、甚至能知識變現（做課程、SaaS、顧問），價值就完全不同。AI 放大了這道差距：會用 AI 只是基本門檻，「AI + 不可被 AI 取代的複雜價值」才是稀缺能力。

如何打破循環？

改變必須從個人開始，逐漸擴散到集體：

1. 停止乖乖接單：積極累積可量化的成果，準備數據談薪。市場上高階與特定領域（AI 應用、硬軟整合、半導體）仍有不錯機會。
2. 提升跳槽意願：每 1-2 年評估一次市場，不要害怕面試。資訊透明（多參與社群、分享合理行情）能慢慢鬆動鎖死的薪資。
3. 轉型價值創造者：學會高效使用 AI 作為杠杆，結合跨域能力。不要只問「AI 會不會取代我」，而要問「我能用 AI 創造什麼 AI 做不到的價值」。
4. 知識變現：把專業轉成產品、課程、內容或企業解決方案，脫離純工時換薪水的模式。

結語

台灣低薪工程師現象的根源，從來不是單一問題，而是代工型產業結構 + 怕失業的乖乖文化 + 執行者定位的綜合結果。AI 的到來，沒有打破這個循環，反而像強力催化劑，讓不願改變的人更難翻身，也讓願意轉型的工程師更快看到差距。

最終，市場不會主動拯救你。當越來越多工程師拒絕「乖乖接受低薪」、勇於定位自己為價值創造者時，行情才有可能被推升。AI 是威脅，更是歷史上難得的杠杆——用得好，它能幫助你跳出惡性循環；用不好，它只會讓低薪的枷鎖更緊。

現在，是時候問自己：你是繼續在循環裡乖乖接單，還是準備把 AI 變成自己加薪的工具？

AI 時代的程式開發者：看清 AI 的真實限制與正確使用之道

 

前言

近年媒體與產業不斷強調「AI 即將取代程式員」，彷彿只要會使用 ChatGPT 或 Claude，就能大幅提升生產力甚至完全取代人類開發者。然而，作為第一線開發者，我們必須對 AI 有理性且務實的認知：AI 是強大的生產力工具，但遠沒有媒體宣傳的那麼全能與可靠。

本文將清楚說明 AI 在實際開發中的常見限制、常遇到的錯誤類型，以及頂尖開發者如何在認清這些限制的前提下，有效駕馭 AI 創造真正價值。

AI 真正的限制

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

AI 常遇到的程式碼錯誤類型（2026 年第一線經驗）

（包含幻覺、安全性漏洞、邊界條件缺失、效能問題、與專案不一致、隱形錯誤等六大類，內容與前版一致）

為什麼這些錯誤這麼常發生？

• 上下文窗口限制
• 訓練資料偏誤
• 過度自信的回答風格
• 缺少真正責任感

真正的競爭力：認清限制後的駕馭能力

AI 目前最強的是產生「看起來正確」的程式碼，但大量隱藏的錯誤需要人類開發者扮演「審計師」的角色。

我個人把 AI 視為「高效率但需要嚴格監督的資深工程師」，而自己則扮演 系統審計師與架構把關者 的角色。

我特別重視以下兩種 AI 的高價值應用：

• 快速接手他人專案：AI 能幫助我快速理解 legacy code 的整體架構、核心流程與技術債，讓我大幅縮短從「看不懂」到「能有效修改」的時間。
• 加速學習不同程式語言與技術棧：當需要快速上手新語言（如 Rust、Go）或新框架時，AI 是極佳的學習夥伴，能提供對比寫法、最佳實踐與常見陷阱。

此外，我還會使用不同的 AI 模型進行交叉驗證（Cross-Validation）： 我不會只依賴單一模型（如只用 Claude 或只用 GPT），而是會將相同的需求分別丟給 Claude 3.5/4、GPT-4o、Gemini 2.5、Grok 等不同模型，比較它們的輸出差異。這樣可以有效發現單一模型的盲點、幻覺或不一致之處，大幅提升最終方案的可靠度。

我的 AI 協作流程

1. 給予充足上下文
2. 分步生成
3. 多模型交叉驗證（使用不同 AI 互相檢查）
4. 嚴格 Code Review
5. 撰寫單元測試與整合測試
6. 逐步整合與驗證

透過這套系統化流程，我能充分發揮 AI 的速度優勢，同時有效確保系統的穩定性、安全性、可維護性與長期擴展性。AI 適合用來快速實驗、原型開發、專案交接與學習，但最終對品質負責的永遠是身為工程師的我。

結論：AI 是工具，而非魔法

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

真正有價值的開發者，不是最會複製 AI 程式碼的人，而是最清楚 AI 的限制、最懂得善用多模型驗證、加速學習與專案交接，並能有效彌補 AI 缺口的人。

在 AI 時代，保持理性認知並建立嚴謹的工作方法，才是開發者真正的護城河。

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

在 Vibe Coding 的時代，開發速度已經不再是主要瓶頸，「正確率」與「可維護性」才是決定成敗的關鍵。當你的專案使用 Astro 5 + Vue 3 + Laravel 12 + Filament v3 這樣的複雜全端技術棧時，AI Agent 很容易因為上下文過長而出現「記憶漂移」，進而虛構 API 格式、破壞商業邏輯，或使用錯誤的套件寫法。單靠 Prompt 工程已無法有效解決此問題。你需要將系統知識結構化與顯性化，建立一套系統開發協議（System Development Protocol），讓 AI 從「容易幻覺的助手」轉變為「遵守協議的可靠執行官」。

---

一、建立 AI 的「數位大腦」：.antigravity/rules 目錄解決幻覺的根本方法，是讓 AI 不再需要「猜測」你的專案慣例。在專案根目錄建立以下結構：

bash

.antigravity/rules/
├── 01_TECH_STACK.md          # 技術棧與套件鎖定
├── 02_API_CONTRACT.md        # API 合約與回應標準
├── 03_BUSINESS_LOGIC.md      # 商業邏輯字典
├── FORBIDDEN_PATTERNS.md     # 禁止的反模式
└── SCORING_SYSTEM.md         # 防幻覺評分規則（可選）

1. 鎖定技術棧（01_TECH_STACK.md）

markdown

# 系統技術清單 (Technology Manifest)

## 核心框架與版本
- Backend: Laravel 12 (PHP 8.3+)
- Frontend: Astro 5.0 + Vue 3.5（Composition API + <script setup>）
- Admin Panel: Filament v3（嚴禁使用 v2 語法）
- 狀態管理: Nano Stores（跨 Island）、Pinia（單一 Island 內）
- UI: Tailwind CSS + Headless UI
- API Client: 自定義 `useApi` composable

## 重要套件
- spatie/laravel-permission：權限系統
- spatie/laravel-medialibrary：媒體檔案管理
- zod：前端執行期驗證

2. 定義 API 鐵律（02_API_CONTRACT.md）

markdown

# API 合約標準

## 成功回應格式
```json
{
  "success": true,
  "data": { ... },
  "message": "操作成功"
}

錯誤處理規範

• 422 驗證錯誤：必須返回 errors 物件
• 500 系統錯誤：正式環境統一返回「系統發生錯誤」

前端呼叫要求

• 必須使用 src/composables/useApi.ts
• 禁止自行 fetch 或直接存取 response.data
• 所有 TypeScript 介面必須引用 src/types/generated/

---

### 二、商業邏輯的地圖化（03_BUSINESS_LOGIC.md）

這是中大型專案防幻覺最關鍵的一環。

```markdown
# 核心商業邏輯字典

## 訂單狀態機
- 合法流程：Pending → Paid → Shipped → Completed
- 禁止跳過 Paid 狀態直接出貨
- 核心實作位置：`app/Services/OrderService.php`

## 權限規則
- 普通管理員只能操作自己建立的資料
- 所有權限判定必須使用 Laravel Policy
- 嚴禁在 Controller 中撰寫 `$user->id === $resource->user_id` 等硬判斷

## 金額處理規範
- 資料庫一律以「分」為單位儲存（Integer）
- 所有計算必須呼叫 `App\Utils\CurrencyCalculator`
- 前端顯示時需除以 100 並格式化

建議在文件中適當加入 Mermaid 流程圖，AI 對視覺化流程的理解效果通常更好。

---

三、實戰工作流：三段式防幻覺指令第一步：現狀探查（Reference Discovery）

markdown

在開始撰寫任何程式碼前，請先：
1. 閱讀 .antigravity/rules/ 下的所有規則文件
2. 搜尋 app/Services/ 目錄，找出 2 個最相似的既有 Service 作為風格與邏輯參考

第二步：執行計畫審核（Plan First）

markdown

請先輸出詳細執行計畫，包括：
- 將修改哪些檔案
- 會呼叫哪些現有 Service / Composable
- 預計使用的套件與方法
確認無誤後我才會讓你開始撰寫程式碼。

第三步：自動化校對（/verify）在 Antigravity 中設定 Slash Command /verify，讓 Reviewer Agent 比對變更是否符合規則文件，並輸出防幻覺評分報告。

---

四、進階技巧

• 型別自動化：導入 spatie/laravel-typescript-transformer，讓後端變更自動產生前端 TypeScript 定義，從根源減少幻覺空間。
• 單一真理來源：在規則文件中加入「若程式碼與規則衝突，以規則文件為準」。
• 上下文精簡：開發特定領域時，只 Pin 相關規則文件與核心檔案，降低 Token 消耗。
• 定期迭代規則：每完成一個較大功能後，檢視並更新規則文件。

---

結語：從「聊天」轉向「協議」在中大型專案中，AI 不應該是一個隨時可能幻覺的問答機器人，而應該是一個遵守明確協議的執行官。透過 .antigravity/rules 的結構化規範，你把原本隱藏在腦海或分散在程式碼中的知識，轉化為 AI 可以可靠遵循的邊界條件。當 Agent 開始出現幻覺時，不要急著在對話中糾正它，而是去完善你的規則文件——這才是規模化 AI 輔助開發的正確心法。立即行動清單：

1. 建立 .antigravity/rules/ 並填入上述三個核心文件
2. 設定 Antigravity Custom Instructions
3. 挑選專案中最容易出錯的模組，先為它撰寫詳細的 BUSINESS_LOGIC 規則

馴服 AI Agent 的 Token 優化實戰指南—— 在 Antigravity 中大幅降低成本的中大型專案經驗在使用 Google Antigravity 這類 Agent-First IDE 時，Token 消耗速度遠高於傳統 Chat 模式。一個中大型專案的複雜任務，很容易在幾輪對話後就燒掉數十萬 Token。真正的高手不會一味追求更強大的模型，而是透過精準的上下文控制、規則優化與流程設計，大幅提升「輸入/輸出比」（I/O Ratio），讓每一枚 Token 都花在刀口上。以下從環境、規則、指令、策略四個層面，分享在 Astro + Vue 3 + Laravel 12 專案中的實戰優化技巧。

---

一、環境層：精準的上下文過濾AI 不需要讀取它不該知道的東西。每一行不必要的程式碼都是 Token 浪費。1. 配置 .antigravityignore在專案根目錄建立 .antigravityignore，內容比 .gitignore 更嚴格：

ignore

node_modules/
vendor/
dist/
build/
public/build/
storage/framework/
*.log
*.sqlite
*.png
*.jpg
*.jpeg
*.webp

2. 手動精準釘選（Pinning）

• 避免使用「全專案索引」模式提問
• 改用 @ 符號或 Pin 功能，只選取 3~5 個最相關檔案

錯誤示範：
「幫我改一下登入邏輯。」正確示範：
「參考

@auth

.ts、

@login

.vue 與

@useApi

.ts，修改登入邏輯。」

---

二、規則層：結構化與模組化規則文件規則文件若太冗長，每次 Agent 讀取都會重複消耗 Token。優化原則：

• Markdown 精煉化：刪除所有修飾語，只保留核心指令

低效寫法：
「我們強烈建議開發者在呼叫 API 的時候，務必要記得加上 Loading 狀態以提升使用者體驗。」高效寫法：
「所有 API 呼叫必須處理 Loading 狀態。」

• 模組化拆分：
  • BACKEND_RULES.md
  • FRONTEND_RULES.md
  • UI_RULES.md
  • FILAMENT_RULES.md
  僅在對應任務時載入相關規則，減少不必要的 Token 消耗。

---

三、指令層：提升輸入/輸出比減少「對話糾正」的次數，是省 Token 最有效的方法。實戰技巧：

1. 預先提供介面定義
   直接貼上 Method Signature 或 TypeScript Interface，而非讓 Agent 讀完整個實作檔案。
2. 使用 One-Shot Prompt
   給一個簡短且正確的程式碼範例，效果遠優於長篇文字說明。
3. 要求局部更新（Diff 模式）
   指令 Agent 只輸出修改的部分程式碼片段，而非整個檔案：
   「僅輸出修改後的 diff 片段，不需要重複輸出完整檔案。」

---

四、策略層：模型分級與重置機制1. 定期 Clear History

• 採用「一個功能，一個對話視窗」原則
• 功能開發完成後立即清除歷史，重置 Context

2. 模型精準投放

任務類型	推薦模型	理由
註解、格式化、簡單修正	Gemini 1.5 Flash	極低成本、高速
單檔案調整、中等邏輯	Gemini 1.5 Flash / Pro	性價比高
跨檔案重構、複雜 Debug	Claude 3.5 Sonnet / Gemini 1.5 Pro	強大推理能力

3. 執行前攔截（Plan First）在重要任務中強制加入：

「在執行任何程式碼修改前，請先輸出簡短執行計畫（包含將修改的檔案與預期變更），等待我確認後再繼續。」

這一步通常只需消耗 30~80 Token，卻能避免後續數千 Token 的無效產出。

---

Token 優化矩陣總結

階段	核心動作	預估節省比例
環境層	.antigravityignore + 精準 Pinning	20% ~ 40%
規則層	模組化 + Markdown 精煉	10% ~ 25%
指令層	One-Shot + 局部 Diff	15% ~ 30%
策略層	Clear History + Plan First	30% ~ 50%

---

我的務實建議在中大型網站開發中，最省 Token 的根本方法是維護好你的型別定義。當你使用 spatie/laravel-typescript-transformer 讓後端自動產生精準的前端 TypeScript 型別後，AI 只需要讀取型別定義就能寫出正確程式碼，大幅減少反覆閱讀實作細節的 Token 消耗。立即可執行的 3 步驟：

1. 今天建立並完善 .antigravityignore
2. 把規則文件拆分成模組化版本
3. 在常用 Prompt 中加入「Plan First」指令

Laravel 12 全端開發利器：使用 spatie/laravel-data 打造「零幻覺」系統在中大型專案中，後端資料從 Model 到前端的轉換路徑通常非常長：Model → Service → DTO → Resource → JSON。這不僅讓開發流程變慢，也讓 AI Agent（尤其是 Antigravity）極容易在中間環節產生幻覺，亂猜 API 欄位或回應結構。spatie/laravel-data 的核心價值就在於：用單一類別同時取代 DTO、Form Request、Resource 與部分 Validation，大幅簡化架構，同時成為前後端與 AI 的「單一真理來源」。

---

一、為什麼在中大型專案強烈建議使用 laravel-data？

• 單一真理來源（SSOT）：資料結構只定義一次
• 強型別約束：解決 PHP 弱型別帶來的 API 不確定性
• 大幅降低 AI 幻覺：Agent 只要讀一個 OrderData.php，就能清楚知道 API 該回傳什麼
• 提升開發效率：Controller 常常只要一行，程式碼更乾淨
• 完美搭配 TypeScript：可輕鬆與 spatie/laravel-typescript-transformer 結合

---

二、快速安裝

bash

composer require spatie/laravel-data

安裝完成後，建議同時安裝 TypeScript 轉換工具（推薦）：

bash

composer require spatie/laravel-typescript-transformer
php artisan typescript:install

---

三、實戰範例：建立 OrderData1. 建立 Data 類別

php

// app/Data/OrderData.php
<?php

namespace App\Data;

use Spatie\LaravelData\Data;
use Spatie\LaravelData\Attributes\Computed;
use Spatie\TypeScriptTransformer\Attributes\TypeScript;

#[TypeScript]
class OrderData extends Data
{
    public function __construct(
        public string $order_no,
        public string $customer_name,
        public int $amount_cents,           // 以「分」為單位，避免浮點誤差
        public string $status,

        /** @var array<array-key, mixed> */
        public array $items,

        public ?string $paid_at = null,

        #[Computed]
        public string $formatted_amount,
    ) {}

    public static function fromModel($order): self
    {
        return new self(
            order_no: $order->order_no,
            customer_name: $order->user?->name ?? '訪客',
            amount_cents: $order->total_amount,
            status: $order->status->value,
            items: $order->items->toArray(),
            paid_at: $order->paid_at?->toDateTimeString(),
            formatted_amount: '$' . number_format($order->total_amount / 100, 2),
        );
    }
}

2. Controller 使用方式（極簡）

php

public function show(Order $order)
{
    return OrderData::fromModel($order);   // 自動轉 JSON
    // 或 return OrderData::from($order); // 如果有定義 casts
}

---

四、針對 Antigravity 的 AI 防幻覺攻略Step 1：在後端建立規則文件建立 .antigravity/rules/API_CONTRACT.md：

markdown

# API 通訊協議

1. 所有 API 回應必須對應 `app/Data/` 目錄下的 XXXData 類別
2. 成功回應格式統一使用 `{ "data": T, "message": string }`
3. 所有商業邏輯與格式化應優先在 Data 類別的 `fromModel()` 中處理
4. 禁止在 Controller 中手動拼裝陣列回傳

Step 2：前端開發時的 Prompt 模板當你在前端（Astro + Vue）開發時，可使用以下指令引導 Agent：

「我要實作訂單詳情頁面。請參考後端 @backend/app/Data/OrderData.php 的屬性結構。
在前端建立對應的 TypeScript 型別，並使用 useApi<OrderData> 呼叫 API。
嚴禁使用 OrderData 中不存在的欄位。」

---

五、進階技巧：Token 優化與開發效率

• 減少 AI 上下文負擔：只 Pin 住對應的 *Data.php，不要讓它掃描整個 Model 目錄
• 自動產生 TypeScript：搭配 typescript-transformer 後，前端永遠擁有最新型別
• 局部更新原則：告訴 Agent 「只需輸出修改部分，型別若已存在則不需重複產生」

---

總結：架構師的建議在中大型 Astro + Vue 3 + Laravel 12 專案中，「規範大於自由」。雖然導入 spatie/laravel-data 一開始需要多建立一個 Data 類別，但長期回報非常高：

• 後端：Controller 極簡，程式碼易讀易維護
• 前端：TypeScript 型別精準，開發體驗大幅提升
• AI Agent：幻覺率顯著下降，開發更順暢
• 團隊協作：前後端溝通成本大幅降低

這正是目前最推薦的「全端一致性」開發方式。