AI Agent 專案規範檔設計指南

2025-09-24 17:07:05

隨著 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`

最佳實務

優先共用 AGENTS.md
- Codex CLI 預設讀取。
- Gemini CLI 也支援並建議共用。
- 其他工具雖有專屬檔，但仍可在 AGENTS.md 作為核心規範，然後用各家專屬檔引用或轉載。
核心規範模組化
- 在 /docs/ai/ 建立細分文件，例如：
  - CODING.md → 程式規範
  - STRUCTURE.md → 專案結構
  - APPROVALS.md → 操作限制
- AGENTS.md、CLAUDE.md、gemini.md 只需要簡要索引或引用這些文件。
保持人類可讀性
- 規範檔不只寫給 AI，也寫給新進工程師。
- 使用清單、標題、範例程式碼塊，避免冗長文字。