專案脈絡
協助使用者決定並寫下專案的穩定規則，每條規則都放在它應該歸屬的檔案中。使用者做決定：你負責閱讀、提出具體選項和草稿。
它取代了 Spec Kit 的 constitution.md。該文件的所有內容都找到了更好的歸宿：
| 內容 | 檔案 | 由誰閱讀 |
|---|---|---|
| 技術棧、層級、相依規則、不可協商原則、詞彙表 | docs/ARCHITECTURE.md | 人員與代理；spec-to-plan 和 review-spec 會檢查原則 |
| 品質、分支、提交、PR、審查、AI 使用方式 | CONTRIBUTING.md | 人員（以及代理，透過連結） |
| 每個結構性決策的原因與被捨棄的替代方案 | docs/adr/NNNN-*.md | 兩者，按需查閱 |
| 命令、邊界、非明顯慣例、文件地圖 | AGENTS.md (+ 包含 @AGENTS.md 的 CLAUDE.md) | 代理，每次對話中 |
| 如何回報漏洞、代理政策 | SECURITY.md | 人員 |
範本位於 assets/en/（英文）和 assets/es/（西班牙文）。使用專案文件所採用的語言；如果不清楚，請詢問。每個範本都在其開頭註解中說明如何填寫。
規則
- 請勿重複。 如果某項內容已存在於
pyproject.toml、CI 或 linter 中，請連結到它，不要複製。如果一個原則出現在兩個檔案中，最終會導致彼此矛盾：原則只存在於ARCHITECTURE.md。 - 簡短的
AGENTS.md： 少於 150 行。它是一份地圖，用來連結；它不包含內容。對於每一行問：「如果移除這一行，代理會出錯嗎？」如果不會，就刪掉。 - 能用工具檢查的，就用工具檢查。 對於每個原則，詢問如何驗證（lint、import-linter、測試、CI、審查）並在對應的欄位中記錄。
- 不要有易變的內容： 沒有衝刺狀態或待辦事項。那些應該放在任務追蹤器或
docs/plans/中。 - 完整展示每個檔案（或如果已存在，則展示 diff），並且只在使用者批准後才寫入。
流程
1. 閱讀專案
在提問之前，先閱讀：清單檔案（pyproject.toml、package.json、go.mod…）、README.md、任何現有的脈絡檔案、.github/workflows/、linter 設定和資料夾結構。利用你找到的資訊來提出建議，而不是問開放式問題。
決定模式並告知使用者：
- 綠地（沒有程式碼或幾乎沒有）：
ARCHITECTURE.md是規範性的，說明「將會」如何。 - 棕地：
ARCHITECTURE.md是描述性的，說明「現在」如何。理想狀態應放入 ADR 和工具的漸進式規範。如果脈絡檔案已存在，只詢問有哪些缺口並提出 diff。 - 從
constitution.md遷移：根據上表分配其內容，並建議刪除或將其縮減為一個連結。
2. 分輪訪談
一次一個類別。針對每個問題，提供具體選項（A、B、「保持開放」、「其他」）。如果檔案中已有答案，請要求確認，而不是提問。如果某個類別不適用（例如沒有資料庫），請跳過並說明原因。每輪結束時，總結已決定的內容。
| 輪次 | 決策內容 | 目的地 |
|---|---|---|
| 1. 目的 | 專案是什麼、排除哪些範圍；類型（應用程式、服務、函式庫、CLI） | ARCHITECTURE.md §1，README.md |
| 2. 技術棧與架構 | 語言、框架、持久化、基礎設施；層級或模組以及哪些可以匯入哪些 | ARCHITECTURE.md §2–4，每個結構性決策一個 ADR |
| 3. 不可協商原則 | 5–10 條穩定、可驗證的規則：為什麼，以及每條規則如何被檢查 | ARCHITECTURE.md §5 |
| 4. 品質 | 先測試還是後測試、最低覆蓋率、型別提示、絕不模擬的內容 | CONTRIBUTING.md §5；如果是不可協商的，也放入原則 |
| 5. 安全性 | 認證、敏感資料、輸入驗證、法規遵循 | ARCHITECTURE.md §10，SECURITY.md |
| 6. 流程 | 分支、Conventional Commits、合併或壓縮、核准、PR 大小、允許的 AI 工具 | CONTRIBUTING.md §4，§6–7 |
| 7. 相依性 | 新增依賴的原則、禁止的函式庫、自建或購買 | 原則（如果是不可協商的）或 CONTRIBUTING.md |
| 8. 給代理的資訊 | 命令（驗證命令是強制的）、非明顯慣例、關鍵或脆弱區域（棕地）、邊界（總是 / 詢問 / 從不） | AGENTS.md |
在第 8 輪中，驗證命令是與其他技能（plan-to-tasks、implement、review）的契約。如果不存在，請提議 setup-guardrails-python（或該語言對應的命令）或將其作為開放問題留在 AGENTS.md 中。如果專案將使用 review-prepush 或 review-pr，也提供可選的 ## Code review 區段（範本在 review-context/assets/AGENTS-code-review.md）：基底分支、高風險路徑、報告語言……
3. 起草與寫入
順序：ARCHITECTURE.md → ADR → CONTRIBUTING.md → SECURITY.md → AGENTS.md。AGENTS.md 最後寫，因為它連結了所有其它檔案。
- 從
assets/中的範本開始。刪除尚不適用的章節；不要留空。 - ADR：複製
ADR.md為docs/adr/0000-template.md（西班牙文為0000-plantilla.md）和adr-README.md為docs/adr/README.md。從第 2–3 輪的每個結構性決策建立一個 ADR。棕地：只建立 3–5 個追溯性的 ADR，針對最常被質疑的內容，包含被捨棄的替代方案。 AGENTS.md必須包含：- 「規劃」行：在實作之前，根據
docs/ARCHITECTURE.md中的原則檢查計畫； - 指向
CONTRIBUTING.md的連結，以了解流程。
- 「規劃」行：在實作之前，根據
CLAUDE.md只包含@AGENTS.md，除非它已有其他內容。在這種情況下，建議將其內容移到AGENTS.md中。pull_request_template.md放在.github/中。提供它，但不要強迫使用。
4. 總結
列出已建立或已更改的檔案，以及遺留的開放問題。提醒使用者：
AGENTS.md應每月檢視並精簡，特別是在更換模型時。ARCHITECTURE.md應每季與程式碼比對。- 代理重複犯的每個錯誤，都應變成工具規則，或作為最後手段，寫入「已知陷阱」下方。