同步文件
文件會默默地偏離實作。當 README 提到一個已被移動的檔案時，並不會有任何失敗。請在每次堆疊式 PR 階段或功能完成後、PR 開啟前執行此技能。
此技能的合約包含提交。 它可能會在未詢問的情況下提交，但始終提交到目前分支，絕不提交到 main。
何時跳過
- 文件參考到的內容沒有任何變更（僅純內部邏輯變更）。請在 PR 的「測試」章節中寫下「文件已檢查，無漂移」，讓審查者知道已執行過。
- 使用者明確表示目前還不想提交文件變更。
清單：docs/DOCS.md
範圍內的文件清單放在 docs/DOCS.md 中，而不是 AGENTS.md，這樣常駐的上下文就不會隨著每次同步而增長。
# 文件清單
| 路徑 | 擁有者 | 由誰產生 |
|---|---|---|
| README.md | 專案介紹、設定、環境變數、佈局 | |
| AGENTS.md | 代理規則 + 專案閘道 | |
| packages/api/README.md | 端點、腳本、環境變數 | |
| docs/api/openapi.json | API 參考 | `pnpm generate:openapi` |
## 凍結（永不因同步而編輯）
- docs/plans/
## 漂移檢查
<!-- 每條 grep 代表一個實際發生過的錯誤，並附上註解說明原因 -->
第一次執行： 建立它。掃描根目錄和每個套件中的 README.md / AGENTS.md / CLAUDE.md、貢獻者文件、API 文件（OpenAPI 描述、llms.txt）、技能和規則目錄，以及環境變數參考（.env.example、設定模式）。記錄每個文件擁有哪些內容。
每次執行： 找到任何未列出的文件，都會在同一次提交中加入。
程序
- 稽核。 比對目前分支與其基礎分支的差異 (
git diff <base>...HEAD --stat)，並列出文件中可能提及的變更：路徑、套件名稱、路由、指令和腳本、環境變數、匯出的 API、行為、慣例。 - 驗證。 對於清單中的每份文件，根據程式碼檢查每一個具體聲明：每個命名的檔案存在於該路徑、每個指令存在於 manifest、每個環境變數確實被讀取、每個路由和匯出如描述般存在。閱讀程式碼；不要相信文字敘述，包括你先前寫的文字。
- 編輯。 修正漂移。描述程式碼實際做的事情，且永遠不要為了讓文件更好讀而憑空發明行為。如果程式碼和文件不一致且你無法判斷哪個是錯的，請標記出來，而不是猜測。
- 重新產生。 執行清單中列出的每個產生器指令。切勿手動編輯自動產生的文件。
- 執行
docs/DOCS.md中列出的漂移檢查。 當同步發現一個很可能重複發生的錯誤（例如舊路徑、重新命名的指令）時，為它新增一條帶有說明原因的 grep。 - 提交。 按路徑暫存檔案，切勿使用
git add -A。在目前分支上製作一個原子提交，訊息格式為docs(<scope>): sync <what> with <change>。 - 推送（如果分支已追蹤遠端倉庫，請先執行
git pull --rebase）。切勿推送到main。
規則
- 凍結歷史：
docs/plans/中的設計、計劃和交接文件是當時決策的快照。它們會在 grep 中出現；這是預期的，不是漂移。同步時永不編輯它們。 - 實驗性原型在被刪除後一旦其方向已發布或放棄，就會被刪除，不會保留下來作為參考。一旦生產環境有了更好的了解，實驗原型的結論就是倉庫中最不可靠的文字。任何仍然值得知道的資訊都會被移入已發布程式碼的文件中。
- 大小預算： 文件行數計入 PR 預算。如果同步將某個階段推超過 500 行，請將其作為一個僅限文件的階段疊加到堆疊頂端（請參閱
stacked-prs）。 - 指標檔案保持簡短。 一個僅指向
AGENTS.md的CLAUDE.md或GEMINI.md應保持這種方式。不要將內容複製進去。