隨著 Codex CLI、Claude Code、Gemini CLI、Cursor、Windsurf、Cline 等 AI 開發工具逐漸普及，每個工具都有自己的「規範檔」格式或預設讀取的文件。這些檔案的目的都相同：
讓 AI 理解專案結構、遵守程式規範，並清楚知道可做與不可做的事。

 

各家工具的預設規範檔

  • Codex CLI（OpenAI） → AGENTS.md

  • Claude Code（Anthropic） → CLAUDE.md（或 .clauderules）

  • Gemini CLI（Google） → gemini.md，但官方也建議可直接共用 AGENTS.md

  • Cursor → .cursorrules

  • Windsurf → .windsurfrules

  • Cline → .clinerules

可以發現：

  • 大多數工具都有專屬的檔案名，以便自動讀取。

 

規範檔內容設計建議

1. 專案概覽

簡述技術棧與專案目標。

# Project Overview
本專案使用 Laravel 12 + Vue 3 + Tailwind + PostgreSQL，提供勞動相關的試算工具。

 

2. 專案結構

列出主要目錄用途，幫助 AI 理解程式碼位置。

## 專案結構
- app/         → Controllers, Models, Jobs
- routes/      → web.php, api.php
- resources/   → Blade 與 Vue 元件
- public/      → 編譯後前端資源
- database/    → migrations, seeders

 

3. 程式碼規範

統一定義程式風格與命名慣例。

## 程式碼規範
- PHP 遵循 PSR-12（4 空格縮排）
- Blade 檔案使用 snake_case 命名
- Vue/JS 採 camelCase 命名
- 前端僅使用 Tailwind

 

4. 操作允許與限制

告訴 AI 哪些能動，哪些必須保護。

## 操作限制
- 可以新增 migration 檔案
- 可以修改 Vue 元件
- 不得修改 .env 或金鑰檔案
- 不得刪除現有 migrations

 

5. 常見任務範例

提供具體範例，幫助 AI 模仿正確模式。

## 任務範例
- 新增 overtime_calculator 的 migration
- 撰寫 overtime_calculator.vue 的使用說明
- 解釋 salary_calculator.blade.php 的程式邏輯

 

6. 測試與檢查流程

提醒 AI 在產生程式碼後應檢查品質。

## 測試流程
- 所有修改需通過 `composer test`
- PHP 程式碼需經過 `./vendor/bin/pint` 格式化
- 前端修改後需執行 `npm run build`

 

最佳實務

  1. 優先共用 AGENTS.md

    • Codex CLI 預設讀取。

    • Gemini CLI 也支援並建議共用。

    • 其他工具雖有專屬檔，但仍可在 AGENTS.md 作為核心規範，然後用各家專屬檔引用或轉載。

  2. 核心規範模組化

    • 在 /docs/ai/ 建立細分文件，例如：

      • CODING.md → 程式規範

      • STRUCTURE.md → 專案結構

      • APPROVALS.md → 操作限制

    • AGENTS.md、CLAUDE.md、gemini.md 只需要簡要索引或引用這些文件。

  3. 保持人類可讀性

    • 規範檔不只寫給 AI，也寫給新進工程師。

    • 使用清單、標題、範例程式碼塊，避免冗長文字。

 

結語

雖然各家工具的規範檔名稱不同，

但它們的目的完全一致：為 AI 提供一份可靠的專案規範。
無論團隊使用哪一套 AI 工具，只要有明確的規範檔，就能確保：

  • AI 產出的程式碼與團隊標準一致。

  • 不同開發者與工具都能快速上手專案。

  • 專案修改過程中，能避免誤觸敏感檔案或偏離架構。

因此，設定規範檔不僅是「善用 AI」的最佳實務，更是團隊長期維護專案品質與安全性的基石，以上的規範檔設定方式也提供給大家參考。