痛點：AI 寫程式為何總在同一個地方出包

用 Cursor、Windsurf 或 Claude Code 寫專案的人，幾乎都遇過同一種崩潰：AI 吐出一整段程式碼，你複製貼上跑起來——建置報錯、測試全紅、依賴裝錯位置。問題不在 AI 笨，而是它根本不知道你這個專案的「潛規則」。

AGENTS.md 就是放在專案根目錄的一個 Markdown 檔，專門寫給 AI 看，告訴它怎麼建置、怎麼測試、遵守什麼規範。README.md 是寫給人看的，裡面塞滿專案介紹、貢獻指南、品牌故事。AI 讀到這些內容，就像新人入職第一天被塞了一本公司型錄，然後被要求立刻寫 code——它知道公司做什麼，但不知道建置指令、不知道測試怎麼跑、不知道 ESLint 規則是什麼。結果就是每次都要在對話裡反覆糾正：「用 pnpm 不是 npm」「測試在 packages/web 下面」「別忘了跑 lint」。這些糾正重複一百遍，專案還是亂。

接案場景的損失更直接：你接了一個 Next.js + Prisma 的外包，用 Cursor 幫你加速，結果 AI 用 npm install 裝依賴，pnpm 的 workspace 設定全廢；它不知道你的資料庫 schema 在哪個目錄，產生的 migration 檔直接報錯。客戶催交付，你花三小時 debug AI 寫的 code——這錢賺得超憋屈。

AI 不知道專案潛規則的 3 個典型翻車場景：① 套件管理員搞錯（專案用 pnpm，AI 預設 npm install），依賴裝到錯的位置，workspace 設定失效；② 測試入口找不到（專案測試在 packages/web 下面，AI 在根目錄跑 pnpm test，報「找不到測試檔案」）；③ 程式碼風格不一致（專案用 ESLint + Prettier，AI 產生的程式碼縮排、引號全錯，CI 直接掛掉）。

機會：AGENTS.md 把「人類文件」和「機器文件」徹底切開

GitHub 上的開源專案 AGENTS.md（倉庫網址 github.com/agentsmd/agents.md，截至 2026-08-25 約 2.4 萬 stars）解決的就是這個問題。它的核心思路極簡單：在專案根目錄放一個 Markdown 檔，專門告訴 AI 如何建置、如何測試、遵守什麼程式碼風格。

這不是 README 的替代品，而是補充。README 服務於人類貢獻者，AGENTS.md 服務於 AI 助理。兩者職責清楚，互不干擾。

據源帖稱，AGENTS.md 已被數萬個開源專案採用（具體數字待核），覆蓋 VS Code、Cursor、Windsurf、Aider、GitHub Copilot 等主流 AI 寫程式工具（核證結論確認）；此外據社群回饋，OpenAI Codex、Google Jules 等工具也提供支援（⚠️未核實）。你現在不學，等於讓 AI 用方言跟你對話。

路徑一：手寫一份最小可用的 AGENTS.md

成本極低。新增檔案，寫三段就夠用。

前置認知：以下範例用 pnpm（比 npm 更省磁碟、支援 monorepo workspace），turbo 是 monorepo 工作流程編排工具，--filter 參數指定只對某個子包生效，避免影響整個倉庫。

第一段「Dev environment tips」：告訴 AI 專案用什麼套件管理員、怎麼跳轉子包、怎麼新增模組。例如官方範例裡的：

• pnpm dlx turbo run where <project_name> —— 直接跳到指定子包目錄，不用 ls 一個個翻
• pnpm install --filter <project_name> —— 只裝某個子包的依賴，不動整個 monorepo
• pnpm create vite@latest <project_name> -- --template react-ts —— 新增一個帶 TypeScript 檢查的 React + Vite 子包

這些指令 AI 自己猜不到，但你寫下來它就照做。

第二段「Testing instructions」：告訴 AI 測試怎麼跑、CI 排程在哪、送出前必須跑哪些檢查。官方範例包含：

• pnpm turbo run test --filter <project_name> —— 跑指定子包的完整檢查
• pnpm vitest run -t "<test name>" —— 只跑符合某個名字的單一測試
• 「Fix any test or type errors until the whole suite is green」—— 不全綠不許停
• 「Add or update tests for the code you change, even if nobody asked」—— 最後這句是關鍵，不寫的話 AI 經常偷懶不寫測試

第三段「PR instructions」：規範提交標題格式、強制跑 lint 和 test。官方範例是 Title format: [<project_name>] <Title>，以及「Always run pnpm lint and pnpm test before committing」。

這三段加起來不到 50 行，但能讓 AI 產生程式碼的一次通過率明顯提升（據社群回饋，具體數字待核）。

路徑二：在大型 monorepo 中嵌套使用

如果你接的是企業級專案，程式碼庫是 monorepo 結構（多個相關專案放在同一個 Git 倉庫裡管理，例如前端、後端、共用程式碼各一個子目錄），單一 AGENTS.md 不夠用。AGENTS.md 支援嵌套：在每個子目錄放一份專屬的 AGENTS.md，AI 會自動讀取「最近的那一份」。

實務做法：根目錄的 AGENTS.md 寫全域規範（套件管理員、CI 流程、安全注意事項），然後在 packages/web/、packages/api/、packages/shared/ 各放一份，寫這個子包特有的建置指令、測試入口、特殊依賴。例如前端包需要寫「元件庫用 shadcn，樣式用 Tailwind，圖示用 lucide-react」；後端包需要寫「資料庫 migration 用 Prisma，API 路由在 src/routes 下面，權限驗證用 JWT」。

AI 在子目錄工作時，會自動載入最近的 AGENTS.md，優先權高於根目錄。這代表同一個專案裡，前端 AI 助手和後端 AI 助手能拿到完全不同的指令，不會互相串台。

路徑三：把它變成接案的差異化賣點

現在 AI 接案市場已經捲成紅海——人人都會用 Cursor，但交付品質參差不齊。如果你能在標書裡寫一句「本專案已配置 AGENTS.md 標準文件，AI 輔助開發遵守專案規範」，中標率會明顯高於只會說「我用 AI 寫 code」的同行。

具體打法：接到案後，先花 30 分鐘讀懂客戶的專案結構，然後寫一份客製化的 AGENTS.md。這份文件本身就是交付物的一部分——客戶拿到後，未來自己用 AI 維護程式碼也會更順暢。

把 AGENTS.md 配置服務單獨報價（參考報價，需依當地市場調整）：基礎版 NT$2,500（單檔配置 + 一份 README 說明），企業版 NT$15,000（monorepo 嵌套 + 安全規範 + 團隊培訓）。交付物清單：① 客製 AGENTS.md 檔案 ② 30 天 LINE 答疑 ③ 一段 10 分鐘的錄影培訓。適用場景：客戶已有 Cursor/Windsurf 會員但用不出效果。不適合：客戶還在用純人工開發、沒導入 AI 工具。

案例：AGENTS.md 的相容性護城河

AGENTS.md 採用 MIT 授權（素材包確認），由社群維護（具體治理結構待核），官網是 agents.md。

相容性是它最大的護城河：核證結論確認 VS Code、Cursor、Windsurf、Aider、GitHub Copilot 都支援讀取 AGENTS.md；據社群回饋，OpenAI Codex、Claude Code、Gemini CLI、Google Jules 等工具也提供支援（⚠️未核實）。這代表你寫一份檔案，主流 AI 助手都能用——不需要為每個工具單獨寫設定。

對比其他方案：Cursor 的 .cursorrules 只對 Cursor 有效，換 Windsurf 就失效；Claude Code 的 CLAUDE.md 只服務 Claude；GitHub Copilot 的指令系統又是另一套。AGENTS.md 的「一次編寫、到處執行」特性，是它短期內被廣泛採用的根本原因。

工具遷移成本歸零。今天你用 Cursor，明天換 Windsurf，AGENTS.md 直接複用，不需要重寫規則。

行動呼籲：今晚就給專案補一份機器手冊

5 分鐘行動清單：① 打開專案根目錄 ② 新增 AGENTS.md ③ 複製官方模板（github.com/agentsmd/agents.md）④ 填入三項指令（建置、測試、lint）⑤ 下次讓 AI 寫程式時觀察效果。

如果你用的是 monorepo，今晚額外花 20 分鐘給每個子包加一份嵌套設定。明天開工時你會發現，AI 產生的程式碼不再需要你反覆糾正。

AGENTS.md 是目前 ROI 最高的 AI 寫程式設定——30 分鐘投入，換每月數小時的 debug 時間。