在 Vibe Coding 的時代，開發速度已經不再是主要瓶頸，「正確率」與「可維護性」才是決定成敗的關鍵。當你的專案使用 Astro 5 + Vue 3 + Laravel 12 + Filament v3 這樣的複雜全端技術棧時，AI Agent 很容易因為上下文過長而出現「記憶漂移」，進而虛構 API 格式、破壞商業邏輯，或使用錯誤的套件寫法。單靠 Prompt 工程已無法有效解決此問題。你需要將系統知識結構化與顯性化，建立一套系統開發協議（System Development Protocol），讓 AI 從「容易幻覺的助手」轉變為「遵守協議的可靠執行官」。
一、建立 AI 的「數位大腦」：.antigravity/rules 目錄解決幻覺的根本方法，是讓 AI 不再需要「猜測」你的專案慣例。在專案根目錄建立以下結構：1. 鎖定技術棧（01_TECH_STACK.md）2. 定義 API 鐵律（02_API_CONTRACT.md）錯誤處理規範建議在文件中適當加入 Mermaid 流程圖，AI 對視覺化流程的理解效果通常更好。
三、實戰工作流：三段式防幻覺指令第一步：現狀探查（Reference Discovery）第二步：執行計畫審核（Plan First）第三步：自動化校對（/verify）在 Antigravity 中設定 Slash Command /verify，讓 Reviewer Agent 比對變更是否符合規則文件，並輸出防幻覺評分報告。
四、進階技巧
結語：從「聊天」轉向「協議」在中大型專案中，AI 不應該是一個隨時可能幻覺的問答機器人，而應該是一個遵守明確協議的執行官。透過 .antigravity/rules 的結構化規範，你把原本隱藏在腦海或分散在程式碼中的知識，轉化為 AI 可以可靠遵循的邊界條件。當 Agent 開始出現幻覺時，不要急著在對話中糾正它，而是去完善你的規則文件——這才是規模化 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 # 防幻覺評分規則（可選）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：前端執行期驗證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 並格式化三、實戰工作流：三段式防幻覺指令第一步：現狀探查（Reference Discovery）
markdown
在開始撰寫任何程式碼前，請先：
1. 閱讀 .antigravity/rules/ 下的所有規則文件
2. 搜尋 app/Services/ 目錄，找出 2 個最相似的既有 Service 作為風格與邏輯參考markdown
請先輸出詳細執行計畫，包括：
- 將修改哪些檔案
- 會呼叫哪些現有 Service / Composable
- 預計使用的套件與方法
確認無誤後我才會讓你開始撰寫程式碼。四、進階技巧
- 型別自動化：導入 spatie/laravel-typescript-transformer，讓後端變更自動產生前端 TypeScript 定義，從根源減少幻覺空間。
- 單一真理來源：在規則文件中加入「若程式碼與規則衝突，以規則文件為準」。
- 上下文精簡：開發特定領域時，只 Pin 相關規則文件與核心檔案，降低 Token 消耗。
- 定期迭代規則：每完成一個較大功能後，檢視並更新規則文件。
結語：從「聊天」轉向「協議」在中大型專案中，AI 不應該是一個隨時可能幻覺的問答機器人，而應該是一個遵守明確協議的執行官。透過 .antigravity/rules 的結構化規範，你把原本隱藏在腦海或分散在程式碼中的知識，轉化為 AI 可以可靠遵循的邊界條件。當 Agent 開始出現幻覺時，不要急著在對話中糾正它，而是去完善你的規則文件——這才是規模化 AI 輔助開發的正確心法。立即行動清單：
- 建立 .antigravity/rules/ 並填入上述三個核心文件
- 設定 Antigravity Custom Instructions
- 挑選專案中最容易出錯的模組，先為它撰寫詳細的 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 更嚴格：2. 手動精準釘選（Pinning）
「幫我改一下登入邏輯。」正確示範：
「參考
二、規則層：結構化與模組化規則文件規則文件若太冗長，每次 Agent 讀取都會重複消耗 Token。優化原則：
「我們強烈建議開發者在呼叫 API 的時候，務必要記得加上 Loading 狀態以提升使用者體驗。」高效寫法：
「所有 API 呼叫必須處理 Loading 狀態。」
三、指令層：提升輸入/輸出比減少「對話糾正」的次數，是省 Token 最有效的方法。實戰技巧：
四、策略層：模型分級與重置機制1. 定期 Clear History
Token 優化矩陣總結
我的務實建議在中大型網站開發中，最省 Token 的根本方法是維護好你的型別定義。當你使用 spatie/laravel-typescript-transformer 讓後端自動產生精準的前端 TypeScript 型別後，AI 只需要讀取型別定義就能寫出正確程式碼，大幅減少反覆閱讀實作細節的 Token 消耗。立即可執行的 3 步驟：
一、環境層：精準的上下文過濾AI 不需要讀取它不該知道的東西。每一行不必要的程式碼都是 Token 浪費。1. 配置 .antigravityignore在專案根目錄建立 .antigravityignore，內容比 .gitignore 更嚴格：
ignore
node_modules/
vendor/
dist/
build/
public/build/
storage/framework/
*.log
*.sqlite
*.png
*.jpg
*.jpeg
*.webp- 避免使用「全專案索引」模式提問
- 改用 @ 符號或 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 最有效的方法。實戰技巧：
- 預先提供介面定義
直接貼上 Method Signature 或 TypeScript Interface，而非讓 Agent 讀完整個實作檔案。 - 使用 One-Shot Prompt
給一個簡短且正確的程式碼範例，效果遠優於長篇文字說明。 - 要求局部更新（Diff 模式）
指令 Agent 只輸出修改的部分程式碼片段，而非整個檔案：「僅輸出修改後的 diff 片段，不需要重複輸出完整檔案。」
四、策略層：模型分級與重置機制1. 定期 Clear History
- 採用「一個功能，一個對話視窗」原則
- 功能開發完成後立即清除歷史，重置 Context
「在執行任何程式碼修改前，請先輸出簡短執行計畫（包含將修改的檔案與預期變更），等待我確認後再繼續。」
這一步通常只需消耗 30~80 Token，卻能避免後續數千 Token 的無效產出。Token 優化矩陣總結
我的務實建議在中大型網站開發中，最省 Token 的根本方法是維護好你的型別定義。當你使用 spatie/laravel-typescript-transformer 讓後端自動產生精準的前端 TypeScript 型別後，AI 只需要讀取型別定義就能寫出正確程式碼，大幅減少反覆閱讀實作細節的 Token 消耗。立即可執行的 3 步驟：
- 今天建立並完善 .antigravityignore
- 把規則文件拆分成模組化版本
- 在常用 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？
二、快速安裝安裝完成後，建議同時安裝 TypeScript 轉換工具（推薦）：
三、實戰範例：建立 OrderData1. 建立 Data 類別2. Controller 使用方式（極簡）
四、針對 Antigravity 的 AI 防幻覺攻略Step 1：在後端建立規則文件建立 .antigravity/rules/API_CONTRACT.md：Step 2：前端開發時的 Prompt 模板當你在前端（Astro + Vue）開發時，可使用以下指令引導 Agent：
五、進階技巧：Token 優化與開發效率
總結：架構師的建議在中大型 Astro + Vue 3 + Laravel 12 專案中，「規範大於自由」。雖然導入 spatie/laravel-data 一開始需要多建立一個 Data 類別，但長期回報非常高：
一、為什麼在中大型專案強烈建議使用 laravel-data？
- 單一真理來源（SSOT）：資料結構只定義一次
- 強型別約束：解決 PHP 弱型別帶來的 API 不確定性
- 大幅降低 AI 幻覺：Agent 只要讀一個 OrderData.php，就能清楚知道 API 該回傳什麼
- 提升開發效率：Controller 常常只要一行，程式碼更乾淨
- 完美搭配 TypeScript：可輕鬆與 spatie/laravel-typescript-transformer 結合
二、快速安裝
bash
composer require spatie/laravel-databash
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),
);
}
}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 中手動拼裝陣列回傳「我要實作訂單詳情頁面。請參考後端 @backend/app/Data/OrderData.php 的屬性結構。
在前端建立對應的 TypeScript 型別，並使用 useApi<OrderData> 呼叫 API。
嚴禁使用 OrderData 中不存在的欄位。」
在前端建立對應的 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：幻覺率顯著下降，開發更順暢
- 團隊協作：前後端溝通成本大幅降低
