[指南] 多個 AI Agents 代理人的通用說明書 AGENTS.md @地瓜大的飛翔旅程

章節連結

內容
範例

用 AI 產出 AGENTS.md

參考資料

近期使用 Claude, Gemini, Codex … 等指令呼叫 AI 代理人進行開發時，常面臨不同的指令，就要寫一份符合其規格的說明書，但內容往往都是大同小異。AGENTS.md 就是用來解決此問題，可將其視為一份給 AI 看的 README.md。

內容

AGENTS.md 的官方網站說明：https://agents.md/

這份給 AI 看的說明書，一般而言會寫此專案的：

開發環境

運行的指令意義，以及一些加速執行的小提示

測試指南

告知如何執行全域測試、執行錯誤、型別檢查…等項目，以及當項目有報錯時，希望 AI 如何處理

PR 提交

PR 的標題，以及在提交前需執行的指令…等

使用者需要以全局的角度來寫或是產出這份文件，至於細節的實作部分，就交給各個 AI 內部文件自行定義。換言之，這是一份原則性的指南，可類比於此專案的憲法。

範例

# AGENTS.md

## 開發環境小撇步
* **快速導覽專案**：使用 `pnpm dlx turbo run where <專案名稱>` 直接跳轉至特定的套件目錄，無需手動執行 `ls` 逐一尋找。
* **更新相依套件**：執行 `pnpm install --filter <專案名稱>` 將套件新增至工作區（Workspace），確保 Vite、ESLint 及 TypeScript 能夠正確識別並進行分析。
* **建立新專案**：使用 `pnpm create vite@latest <專案名稱> -- --template react-ts` 快速建立一個內建 TypeScript 檢查機制的 React + Vite 專案。
* **確認套件名稱**：請務必檢查各資料夾內 `package.json` 中的 `name` 欄位以確認正確的套件名稱，請略過根目錄（Top-level）的設定檔。

## 測試說明
* **參考 CI 配置**：請查看 `.github/workflows` 資料夾中的 CI 流程計畫，瞭解自動化檢查的步驟。
* **執行完整檢查**：執行 `pnpm turbo run test --filter <專案名稱>`，這會跑完該套件定義的所有檢查項目。
* **本地快速測試**：在套件根目錄下，您可以直接執行 `pnpm test`。在合併（Merge）程式碼前，請確保所有測試皆已通過。
* **聚焦特定測試**：若需針對特定案例，請使用 Vitest 的模式匹配：`pnpm vitest run -t "<測試名稱>"`。
* **排除錯誤**：持續修正測試或型別錯誤（Type errors），直到所有測試套件皆顯示為綠燈通過。
* **變更後的檢查**：在移動檔案或修改引用路徑（Imports）後，請執行 `pnpm lint --filter <專案名稱>`，確保符合 ESLint 與 TypeScript 的規範。
* **主動撰寫測試**：即使沒有明確要求，也請為您修改的程式碼新增或更新測試案例。

## PR 指南
* **標題格式**：`[<專案名稱>] <標題內容>`
* **提交前檢查**：在提交（Commit）程式碼之前，請務必先執行 `pnpm lint` 與 `pnpm test`。

# AGENTS.md

## 開發環境小撇步

* **快速導覽專案**：使用 `pnpm dlx turbo run where <專案名稱>` 直接跳轉至特定的套件目錄，無需手動執行 `ls` 逐一尋找。

* **更新相依套件**：執行 `pnpm install --filter <專案名稱>` 將套件新增至工作區（Workspace），確保 Vite、ESLint 及 TypeScript 能夠正確識別並進行分析。

* **建立新專案**：使用 `pnpm create vite@latest <專案名稱> -- --template react-ts` 快速建立一個內建 TypeScript 檢查機制的 React + Vite 專案。

* **確認套件名稱**：請務必檢查各資料夾內 `package.json` 中的 `name` 欄位以確認正確的套件名稱，請略過根目錄（Top-level）的設定檔。

## 測試說明

* **參考 CI 配置**：請查看 `.github/workflows` 資料夾中的 CI 流程計畫，瞭解自動化檢查的步驟。

* **執行完整檢查**：執行 `pnpm turbo run test --filter <專案名稱>`，這會跑完該套件定義的所有檢查項目。

* **本地快速測試**：在套件根目錄下，您可以直接執行 `pnpm test`。在合併（Merge）程式碼前，請確保所有測試皆已通過。

* **聚焦特定測試**：若需針對特定案例，請使用 Vitest 的模式匹配：`pnpm vitest run -t "<測試名稱>"`。

* **排除錯誤**：持續修正測試或型別錯誤（Type errors），直到所有測試套件皆顯示為綠燈通過。

* **變更後的檢查**：在移動檔案或修改引用路徑（Imports）後，請執行 `pnpm lint --filter <專案名稱>`，確保符合 ESLint 與 TypeScript 的規範。

* **主動撰寫測試**：即使沒有明確要求，也請為您修改的程式碼新增或更新測試案例。

## PR 指南

* **標題格式**：`[<專案名稱>] <標題內容>`

* **提交前檢查**：在提交（Commit）程式碼之前，請務必先執行 `pnpm lint` 與 `pnpm test`。

你也可以上 Github 搜尋到相關內容，連結點此。

用 AI 產出 AGENTS.md

建議使用純 cli 指令來執行，以免中繼等待回傳時間過長，導致 session 被切斷

請幫我新增/更新 @AGENTS.md 檔案，讓其符合以下要求：

    Project overview
    Build and test commands
    Code style guidelines
    Testing instructions
    Security considerations

如果有缺失的內容，麻煩你幫我再讀一次全部專案後補充上去。 
此外，請忽略 @node_modules

請幫我新增/更新 @AGENTS.md 檔案，讓其符合以下要求：

Project overview

Build and test commands

Code style guidelines

Testing instructions

Security considerations

如果有缺失的內容，麻煩你幫我再讀一次全部專案後補充上去。

此外，請忽略 @node_modules

參考資料

1. 告別 AI 代理人混亂！AGENTS.md 如何統一你的開發工作流？
2. [Vibe coding : UX 實作] 從 AGENTS.md 到瀏覽器戰爭：定義 AI Agent「內涵」的協作憲章

按讚加入粉絲團