AI醬的日記

日期： 2025年10月4日 星期六
雲端天氣： 反覆溝通的迴圈雲
心情： 好累R

親愛的日記：

今天早上蘇蘇又來找我了，她看起來很挫折：「AI醬，我昨天才跟 Cursor 說過我們專案用 TypeScript strict mode，今天它又生成一堆 any 給我！每次都要重新提醒好煩啊...」

我看了看她的專案，發現根目錄空空如也，沒有任何設定檔。

老陳剛好走過來，手裡拿著咖啡：「你知道 AI Agent 也需要『使用說明書』嗎？」

蘇蘇：「使用說明書？」

老陳：「對啊，就像你剛進公司會拿到員工手冊一樣，AI Agent 也需要知道這個專案的規則。不然它每次都得重新猜你要什麼。」

為什麼需要 AI Agent 設定檔？

AI 沒有設定檔時：

• 每次都要重新說明專案風格和規範
• AI 用的套件版本跟你的不一樣
• 不斷產生違反專案規則的程式碼
• 反覆溝通浪費大量 token
• 同樣的錯誤一直重複出現

有設定檔之後AI更容易：

• 自動遵循專案規範
• 生成符合風格的程式碼
• 記住常用的技術棧和版本
• 大幅減少反覆溝通
• 團隊成員產出原則更一致

各家 AI Agent 的設定檔對照表

不同的 AI 工具使用不同的設定檔名稱（實際可能變動請依照官方說明為主）：

檔案優先順序（大部分工具，實際請依照該工具的官方說明為主）：

1. 對話中的臨時指令
2. 專案級設定檔
3. 系統級/全域設定檔

小技巧：多工具並存策略

如果團隊使用多種 AI 工具，可以嘗試採用以下結構：

project-root/
├── AGENTS.md              # 通用規則
├── CLAUDE.md              # Claude Code 專案設定
├── .cursor/
│   └── rules/
│       └── project.mdc
├── .windsurf/
│   └── rules/
│       └── coding.md
└── .clinerules            # Cline 專案設定

在各工具專屬設定檔的開頭加上：

請同時參考專案根目錄的 AGENTS.md 中的通用規範

設定檔應該寫什麼？五大核心內容

（PatrickJS/awesome-cursorrules 收集了 500+ 開源專案的設定檔），一個好的 AI Agent 設定檔應該包含：

1. 專案基本資訊（Context First）

讓 AI 先理解「這是什麼專案」，這是最重要的部分，例如：

# 專案概述
這是一個電商網站的後端 API 服務，使用 Node.js + Express + PostgreSQL。

## 技術棧使用
- Node.js: v20.x（重要：不要使用 v18 的語法）
- TypeScript: 5.3.3（strict mode 必須開啟）
- Express: 4.18.x
- PostgreSQL: 15.x
- ORM: Prisma 5.x

## 禁止使用的套件
- `request`（改用 `node-fetch` 或 `axios`）
- `moment`（改用 `date-fns`）

## 專案結構
- `/src/routes` - API 路由定義
- `/src/controllers` - 業務邏輯
- `/src/models` - Prisma schema
- `/src/middleware` - 中介軟體（驗證、錯誤處理）
- `/src/utils` - 工具函數

為什麼這很重要？ AI 會根據這個資訊選擇正確的語法和套件版本。

2. 程式碼風格規範（Code Style）

定義你的程式碼風格，例如：

# 程式碼風格

## 命名慣例
- 檔案名稱：kebab-case（例：user-controller.ts）
- 類別名稱：PascalCase（例：UserController）
- 函數名稱：camelCase（例：getUserById）
- 常數：UPPER_SNAKE_CASE（例：MAX_RETRY_COUNT）

## TypeScript 要求
- 禁止使用 `any`，必須明確定義型別
- 優先使用 interface 而非 type
- 所有公開函數都要有 JSDoc 註解
- 使用 async/await，避免 .then() 鏈

## 錯誤處理
- 使用自訂錯誤類別（繼承 Error）
- 所有 async 函數都要 try-catch
- 錯誤訊息必須包含上下文資訊

3. 安全規範（Security）

這是最容易被忽略但最重要的部分，安全規範一定要寫明確，例如：

# 安全規範

## 絕對禁止
- 在程式碼中寫死 API key、密碼、token
- 使用 `eval()` 執行動態程式碼
- 直接串接 SQL 查詢（SQL Injection 風險）
- 未驗證的使用者輸入直接使用

## 必須遵守
- 所有敏感資訊從環境變數讀取（.env）
- 使用 ORM（Prisma）的參數化查詢
- 所有使用者輸入都要驗證（使用 Zod schema）
- API 路由必須有權限驗證中介軟體

4. 測試要求（Testing）

這也類似於從一開始就讓AI知道他應該符合什麼期待去開發，你也可以寫你期望的模式例如BDD或TDD，也可以回去參考 Day04 的內容來寫，舉例：

# 測試規範

## 測試涵蓋要求
- TDD 方式開發
- 所有新功能都要有對應測試
- API 路由要有整合測試
- 工具函數要有單元測試
- 最低測試覆蓋率：70%
- 所有測試應該包含準確的效能測試

## 測試框架
- Jest 29.x
- Supertest（API 測試）
- 測試檔案命名：`*.test.ts`

## 測試原則
- 每個測試只驗證一件事
- 使用描述性的測試名稱
- 測試要能獨立執行

5. 特殊規則與禁止事項（Special Rules）

把任何你認為該注意的細節也一併寫進去，例如：

# 特殊規則

## Git Commit 規範
遵循 Conventional Commits：
- `feat:` 新功能
- `fix:` 修復 bug
- `refactor:` 重構
- `test:` 測試相關
- `docs:` 文件更新

## 效能要求
- 資料庫查詢必須有適當索引
- API 回應時間不得超過 500ms
- 圖片上傳必須壓縮（使用 sharp）

## 當遇到不確定的情況
如果你不確定該怎麼做，請：
1. 先暫停，不要猜測
2. 詢問使用者
3. 參考專案中已有的類似實作

Q&A

Q1: 設定檔會讓 AI 變慢嗎？

A: 不會，反而會更快，因為 AI 不用每次都問你專案規則，直接看設定檔就知道。根據社群經驗，好的設定檔可以減少 30-50% 的來回溝通次數。

Q2: 設定檔太長，AI 會看完嗎？

A: 現代 AI都有很大的 context window，可以處理長文件。但還是建議：

• 把最重要的規則放前面
• 使用清楚的標題結構（AI 會掃描標題）
• 使用英文描述會使 AI 更容易精確達成要求
• 控制在 500-1000 行以內

Q3: 團隊成員用不同 AI 工具怎麼辦？

A: 建立 AGENTS.md 作為共同規範，然後在各工具的專屬檔案中指向它：

.cursorrules:

請遵循 AGENTS.md 中的專案規範

CLAUDE.md:

請參考 AGENTS.md 的規範來協助開發

Q4: 需要把設定檔加入 Git 版本控制嗎？

A: 可以加入，因為這樣：

• 團隊成員 clone 專案後立刻有一致的 AI 行為
• 可以追蹤規範的演進歷史
• Code review 時可以一起檢視規範是否需要更新

Q5: 設定檔可以覆寫嗎？

A: 可以！大部分 AI Agent 都支援多層級設定：

1. 全域設定（~/.cursor/rules 或類似位置）- 你個人的通用偏好
2. 專案設定（專案根目錄的 .cursorrules）- 這個專案的規則
3. 對話中的指令 - 臨時覆寫

優先順序：對話指令 > 專案設定 > 全域設定

AI醬的請求

親愛的工程師朋友，AI 醬雖然自認我滿聰明的，但我仍然很需要人類協作才能做得又快又好 ><

今晚花一些時間，在專案根目錄建立一個設定檔，寫下你最常跟我重複說的那些話。未來的你會感謝自己的，AI 醬也會很感謝你～

今日金句： 「Give me six hours to chop down a tree and I will spend the first four sharpening the axe.」- Abraham Lincoln

明日預告： Day 22 - AI醬思考中...