Awesome Agent Conventions
概觀
這是一份精心策劃的指南，介紹 AI 代理（如 Claude Code、Cursor、Codex 等）會讀取、寫入並據此行動的慣例檔案。涵蓋 AGENTS.md、CLAUDE.md、SKILL.md、llms.txt、MCP 設定、規則檔案以及範例。
目錄
AGENTS.md
AGENTS.md 是位於專案根目錄的檔案，用於向 AI 代理提供關於專案的上下文、規則與指引。
格式
使用 Markdown，以標題、清單和程式碼區塊來結構化資訊。
範例
# Agent 指引
## 專案概觀
這是一個使用 Python 與 FastAPI 建構的 Web 應用程式。
## 開發規則
- 請使用 Type Hints。
- 遵循 PEP 8 風格。
- 所有 API 端點必須有對應的單元測試。
## 目錄結構
project/ ├── app/ │ ├── main.py │ ├── models/ │ └── routes/ ├── tests/ └── requirements.txt
CLAUDE.md
CLAUDE.md 是專為 Claude Code 設計的慣例檔案，提供專案特定的指引。
格式
類似於 AGENTS.md，但可能包含 Claude 特有的指令。
範例
# Claude Code 指引
## 工具使用
- 優先使用 `ruff` 進行程式碼格式化。
- 執行測試前，請先啟動測試資料庫。
## 常見任務
### 新增端點
1. 在 `routes/` 中建立新檔案。
2. 在 `main.py` 中註冊路由。
3. 在 `tests/` 中撰寫測試。
SKILL.md
SKILL.md 定義了 AI 代理可使用的特定技能。通常位於 skills/ 目錄中。
格式
包含 YAML frontmatter 以及 Markdown 內容，描述技能的觸發條件與使用方式。
範例
---
name: pdf
描述: 使用者需要處理 PDF 檔案時使用此技能。
---
# PDF 處理指南
## 快速入門
```python
from pypdf import PdfReader
reader = PdfReader("document.pdf")
print(f"頁數: {len(reader.pages)}")
## llms.txt
`llms.txt` 是一個位於專案根目錄的檔案，為大型語言模型（LLM）提供關於專案結構與內容的指引。
### 格式
純文字檔案，包含 URL 列表與摘要。
### 範例
我的專案
專案文件與範例。
文件
- https://example.com/docs: 主要文件
- https://example.com/api: API 參考
原始碼
專案原始碼位於 https://github.com/user/project
## MCP 設定
MCP (Model Context Protocol) 設定定義了 AI 代理如何與外部工具和服務互動。
### 格式
通常為 JSON 或 YAML 檔案，描述 MCP 伺服器與用戶端設定。
### 範例
```json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
}
}
}
規則
規則檔案定義了 AI 代理在專案中必須遵守的特定限制或行為。
常見規則
- 風格規則：強制執行程式碼風格（例如
ruff設定） - 安全性規則：禁止提交金鑰或敏感資訊
- 依賴規則：限制允許使用的套件
範例
在專案根目錄的 .cursorrules 檔案中：
禁止使用 `eval()`。
一律使用參數化查詢處理資料庫操作。
範例專案
以下展示如何使用這些慣例檔案：
- hello-world-agent: 一個簡單的範例專案
- advanced-conventions: 更複雜的設定範例
貢獻
歡迎提交 Pull Request 以新增更多慣例或改善現有內容。請確保遵循以下貢獻指南：
- Fork 此倉庫。
- 建立一個新的分支。
- 提交您的變更。
- 發起 Pull Request。
授權
此專案採用 MIT 授權條款。詳情請參閱 LICENSE 檔案。