Astro + Vue 3 串接 Laravel API 的 Vibecode 防錯誤完整指南

 

前言

2025～2026 年，AI Coding 已經從新奇工具逐漸變成開發團隊的標準配備。

無論是 Gemini、Claude Code、Codex、Cursor、Antigravity 或其他 Agent 工具，都能在數分鐘內完成過去需要數小時甚至數天的開發工作。

然而，許多團隊在導入 AI 後很快發現另一個問題：

AI 寫得很快，但不一定寫得對。

常見情況包括：

• 幻想不存在的 API
• 使用錯誤版本的框架語法
• 忽略既有架構規範
• 重複建立已存在的功能
• 任意重構大量程式碼
• 產生無法通過測試的程式碼
• 建立與專案風格完全不同的新模組

這些問題通常被統稱為：

Hallucination（幻覺）

但實際上，大型專案中的 AI 問題遠遠不只是幻覺而已。

本文將以：

• Laravel 12
• PHP 8.3+
• Filament 4
• Astro 5
• Vue 3.5
• TypeScript
• Sanctum

為例，介紹如何建立一套真正適用於中大型專案的 AI 開發治理體系（AI Engineering Governance）。

---

為什麼單靠 Prompt 無法解決問題？

許多人導入 AI 的第一步是：

請遵守以下規則...

然後貼上數千字 Prompt。

一開始效果很好。

但隨著專案成長：

100 個檔案
↓
500 個檔案
↓
2000 個檔案
↓
5000 個檔案

問題開始出現。

因為 AI 並不知道：

• 哪些規則最重要
• 哪些模式是專案標準
• 哪些檔案不能修改
• 哪些功能已經存在

於是開始出現：

• API 幻覺
• 架構幻覺
• 命名混亂
• 重複實作
• Context Rot（上下文腐化）

因此真正需要建立的不是 Prompt。

而是：

完整的 AI 開發流程。

---

AI 問題的四個層級

Level 1：API 幻覺

最常見。

例如：

AI 猜測：

POST /api/user/profile/update

實際路由：

PUT /api/profile

或者：

AI 假設：

{
  "success": true,
  "data": {}
}

實際回傳：

{
  "status": "ok",
  "result": {}
}

結果前後端完全無法溝通。

---

Level 2：架構幻覺

例如：

專案使用：

Controller
↓
Service
↓
Model

但 AI 突然建立：

Repository
DTO
Action
CQRS

導致整個架構風格被破壞。

---

Level 3：專案知識幻覺

AI 不知道：

• 哪些 Service 已存在
• 哪些 Component 已存在
• 哪些 Composable 已存在

於是重複造輪子。

---

Level 4：失控重構

最危險。

為了完成一個小功能：

AI 順手修改：

config/
bootstrap/
providers/
database/

最後影響整個系統。

---

建立 AI Governance

不要只建立 Prompt。

建立規則中心：

.antigravity/
├── rules/
├── contracts/
├── golden/
└── reports/

---

第一部分：規則管理（Rules）

PROJECT_CONTEXT.md

定義專案全貌。

Backend:
- Laravel 12
- PHP 8.3+

Frontend:
- Astro 5
- Vue 3.5
- TypeScript

Authentication:
- Sanctum

這份文件保持精簡。

不要超過 200 行。

---

TECH_STACK_SCHEMA.md

鎖定技術規範。

例如：

Vue

允許：

✓ Composition API
✓ script setup
✓ TypeScript

禁止：

✗ Options API
✗ this
✗ export default

---

ARCHITECTURE_DECISION_RECORD.md

這份文件極為重要。

明確定義：

使用：

✓ Service Pattern
✓ Form Request
✓ Resource

不使用：

✗ Repository Pattern
✗ DTO
✗ CQRS
✗ Event Sourcing

並要求：

未經批准不得新增架構模式。

---

第二部分：API Contract

不要手寫 API 文件

很多團隊：

Laravel
↓
人工更新 OpenAPI

最終一定失敗。

因為文件會漂移。

正確流程：

Route
↓
Form Request
↓
Resource
↓
OpenAPI 自動生成

例如：

• Scramble
• Scribe

讓 Contract 從程式碼生成。

而不是反過來。

---

TypeScript First

所有 API 開發遵守：

API Contract
↓
TypeScript Interface
↓
Composable
↓
Component
↓
Page

禁止：

先寫畫面
再猜 API

---

第三部分：Reference Discovery

很多團隊要求：

先找相似檔案

但這還不夠。

應該建立固定格式：

# Discovery Report

## Similar Files

1. UserService.php
2. ProfileService.php
3. UserController.php

## Patterns Found

- Service Layer
- Form Request
- Resource Response

## Reuse Strategy

- Follow naming conventions
- Reuse validation pattern

未完成 Discovery。

禁止開始開發。

---

第四部分：Golden Path

大型專案一定要建立。

例如：

.antigravity/golden/

內容：

Service.example.php
Controller.example.php
Request.example.php
Resource.example.php
useApi.example.ts
Page.example.vue
FeatureTest.example.php

這些檔案代表：

團隊認可的最佳實踐。

Reference Discovery 優先參考 Golden Path。

而不是整個專案亂掃。

---

第五部分：Domain Glossary

這是許多團隊忽略的重點。

例如：

Customer = 客戶

Member = 前台會員

User = 後台管理員

Admin = 系統管理員

避免 AI 混用名詞。

---

第六部分：Protected Areas

建立：

PROTECTED_AREAS.md

分成兩級。

Hard Protect

禁止修改：

bootstrap/
config/
database/migrations/

---

Soft Protect

需經批准：

app/Providers/
app/Policies/

避免 AI 任意修改核心系統。

---

第七部分：Context Rot 管理

這是大型專案最大的隱形問題。

當專案超過數千個檔案後：

AI 不可能理解全部內容。

因此：

建立 Component Registry

docs/components.md

建立 Service Registry

docs/services.md

建立 API Registry

docs/apis.md

讓 AI 能快速定位既有資源。

---

第八部分：AI Reviewer 不是第一道防線

很多人設計：

Coder Agent
↓
Reviewer Agent

其實不夠。

正確流程應該是：

Coder
↓
Static Analysis
↓
Tests
↓
Reviewer
↓
Human Review

因為：

編譯器比 AI 更不會幻想。

---

第九部分：建立品質閘門（Quality Gate）

Laravel：

php artisan test
./vendor/bin/pest
./vendor/bin/phpstan
./vendor/bin/pint

前端：

npm run lint
npm run type-check
npm run test

全部通過後：

才允許進入 Review。

---

第十部分：推薦的 AI 開發流水線

如果使用 Antigravity、Claude Code 或 Gemini：

建議流程：

Planner
↓
Discovery
↓
Coder
↓
Static Analysis
↓
Tests
↓
Reviewer
↓
Human Approval

每個階段都有明確責任：

Planner
負責規劃

Discovery
負責理解專案

Coder
負責實作

Static Analysis
負責規則檢查

Tests
負責驗證功能

Reviewer
負責架構一致性

Human
負責最終決策

---

結語

AI Coding 的真正價值，不是讓 AI 寫更多程式碼。

而是讓 AI 在既有架構中持續產出正確的程式碼。

當專案具備：

• Architecture Decision Record
• OpenAPI Contract
• TypeScript First
• Discovery Report
• Golden Path
• Domain Glossary
• Protected Areas
• Static Analysis
• Automated Testing
• Human Review

AI 就不再只是會生成程式碼的工具。

而是一位能夠遵守團隊規範、融入工程流程、協助長期維護的大型專案開發夥伴。

真正成熟的 AI 開發，不是追求更長的 Prompt。

而是把 AI 納入既有的軟體工程體系，讓規範、測試、工具與人共同約束它。

這也是從 Vibe Coding 走向 Engineering Coding 的關鍵一步。