agents-md-starter
輸出：在存放庫根目錄建立 AGENTS.md 作為單一事實來源，以及包含 @AGENTS.md（Claude Code 會讀取 CLAUDE.md 並支援 @path 匯入）的 CLAUDE.md。檔案中的每個指令必須已經成功執行過，或清楚標示為未驗證。
步驟 1 — 掃描
python3 scripts/scan_repo.py /path/to/repo # 人類可讀摘要
python3 scripts/scan_repo.py /path/to/repo --json # 以 JSON 格式輸出事實
python3 scripts/scan_repo.py /path/to/repo --draft > AGENTS.draft.md # 填入範本
它會偵測：以檔案數量統計的程式語言、從鎖定檔案判斷的套件管理器、package.json 中的腳本、Makefile 目標、pyproject.toml 工具（pytest、ruff、mypy、uv/poetry）、Go/Rust/Java 建置檔案、框架（Next.js、Astro、Vite、Django、FastAPI、Rails…）、單體倉庫工作區、CI 工作流程、環境變數範例檔案，以及現有的代理規則檔案。它絕不會執行存放庫中的程式碼。
步驟 2 — 先讀再寫
- 閱讀找到的每一個現有規則檔案（
CLAUDE.md、.cursorrules、.cursor/rules/*.mdc、.github/copilot-instructions.md、GEMINI.md、CONTRIBUTING.md）。保留其中真正的規則；進行合併、去重，並刪除那些過於通用的規則（例如「撰寫乾淨的程式碼」）。 - 閱讀 CI 工作流程：CI 執行的指令是「測試通過」最可靠的定義。
- 快速瀏覽 2 到 3 個具代表性的原始碼檔案，以掌握實際的程式碼慣例（命名方式、錯誤處理、匯入風格）— 切勿發明程式碼中不存在的慣例。
步驟 3 — 驗證指令
執行草稿中的安裝/建置/測試/語法檢查指令（以安全的方式進行：不部署、不對真實資料庫執行遷移、不發佈）。對於每個指令：如果成功就保留它；如果修正方式很明顯，就修正它；否則標記為 (unverified) 並告知使用者。如果測試套件執行緩慢，請記錄所需時間。
步驟 4 — 撰寫 AGENTS.md
從 assets/AGENTS.template.md 開始。內容好的規則：
- 簡短。 目標是在 150 行以內。代理在每次任務時都會讀取這些規則；每一行都會消耗上下文。
- 具體且可檢查：「在提交前執行
pnpm test --filter web」勝過「測試你的程式碼」。 - 將指令放在前面。然後是佈局、慣例、注意事項和「禁止」規則。
- 記錄非顯而易見的事項：不應編輯的生成檔案、測試所需的環境變數、應在本地跳過的某個慢速測試、密碼絕對不能放置的位置。
- 單體倉庫：根目錄的 AGENTS.md 用於共用規則 + 巢狀的
packages/x/AGENTS.md用於套件專用的指令（支援此功能的代理會讀取最近的檔案）。
步驟 5 — 連接其他工具
- Claude Code：從
assets/CLAUDE.template.md建立CLAUDE.md（它包含@AGENTS.md）。如果 CLAUDE.md 已存在，則將其規則移至 AGENTS.md，並在匯入語句之後僅保留 Claude 專用的備註。 - Codex：原生讀取
AGENTS.md— 無需其他操作。 - Cursor：讀取根目錄的
AGENTS.md；將.cursorrules的內容遷移至 AGENTS.md，並在使用者同意後刪除.cursorrules（已棄用）。僅保留.cursor/rules/*.mdc用於 glob 範圍規則。 - Gemini CLI：預設讀取
GEMINI.md；在.gemini/settings.json中設定"context": {"fileName": ["AGENTS.md", "GEMINI.md"]}，或建立一個指向 AGENTS.md 的一行 GEMINI.md。如果此設定鍵已變更，請查閱已安裝版本的說明文件。 - 符號連結（
ln -s AGENTS.md CLAUDE.md）也可行，但在沒有啟用core.symlinks的 Windows 檢出環境中會失敗；匯入方式較為安全。
請參閱 references/tool-support.md 了解每個工具讀取的檔案。
步驟 6 — 報告
列出：已建立/修改的檔案、已驗證的指令（含結果）、標記為未驗證的指令、因重複或過於通用而刪除的規則，以及任何需要使用者決定的事項（例如是否刪除 .cursorrules？）。除非使用者要求，否則請勿提交變更。