laravel-11-12-app-guidelines

本技能為在 Laravel 11 與 12 生態系統中工作的開發者與 AI 代理提供了一個全面的操作框架。其設計目的是確保在各種專案配置中保持一致性，範圍涵蓋從僅提供 API 的後端到利用 Inertia.js、Livewire 與 Tailwind CSS v4 等現代前端工具的複雜全端應用程式。此技能指示代理程式優先參考專案文件（特別是 AGENTS.md），並利用智慧堆疊偵測來調整 Docker/Sail 或原生環境的指令。

• 自動偵測 composer.json、package.json 與容器配置，以防止指令錯誤。

• 強制執行嚴格的 Laravel 11/12 結構慣例，包含 bootstrap 目錄下的路由、中介軟體與服務提供者管理。

• 整合 Laravel Boost MCP 工具，用於進階文件搜尋、Artisan 指令檢查與資料庫除錯。

• 推廣最佳實踐，例如使用 Form Request 進行驗證、使用 Eloquent 關聯取代原生查詢，以及維護乾淨的遷移檔。

• 支援包含 Inertia + React、Vue 與 Blade 在內的多種前端架構，並強調狀態管理與資源處理的特定模式。

• 透過 PHPUnit 與 Pint 在完成功能實作或錯誤修復前進行自動化程式碼品質檢查。

• 務必先檢查 AGENTS.md 中的專案特定指引，以確保符合現有的專案模式。

• 在執行寫入操作前，使用 Laravel Boost MCP 工具（search-docs、list-routes、tinker）收集情境資訊。

• 使用 Tailwind v4 時，嚴格遵循說明中提供的基於主題的工具類別模式。

• 在執行最小化、情境相關的單元或功能測試後，務必提供執行完整測試套件的選項。

• 在僅提供 API 的專案中，應避免對前端內容做出假設，以維持關注點分離。