Caliber 把 AI 設定檔從手寫維護改成生成加同步
Continuously sync your AI setups with one command. Codebase tailor suited agent skills, MCPs and config files for Claude Code, Cursor, and Codex.
秒懂
- 它是什麼？
- Caliber 針對 CLAUDE.md、.cursor/rules、AGENTS.md 這類 AI 上下文檔案會隨重構失效的問題，改以本地評分、產生差異、再回寫的方式維護。它適合多代理並用的團隊，但前提是你願意讓 pre-commit hook 介入每次提交。
- 適合誰用？
- 如果你同時用 Claude Code、Cursor、Codex 或 Copilot，而且已經被多份互相矛盾的設定檔拖住，Caliber 值得先跑一次 caliber score 看現況分數，再決定是否讓它接管寫入。若你的 CLAUDE.md 本來就簡短且不引用具體路徑，或者你無法接受 pre-commit hook 在每次提交時執行 refresh，這個工具帶來的複雜度高於收益。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 51 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月15日）與我們的分析，不構成法律意見。
開源專案深度解析
手寫 CLAUDE.md 為什麼會過期
專案重構之後，設定檔裡的路徑、依賴名稱、目錄結構都會與現實脫節。README 直接把這件事寫成開場句：手寫的 CLAUDE.md 在你重構的那一刻就開始過期，代理會引用不存在的路徑、漏掉新依賴，並根據昨天的架構給建議。這不是幻覺問題，是維護問題。檔案本身沒有錯，只是沒有人負責在每次改名或搬動模組後回頭更新它。
Caliber 要解決的是這個維護斷層，而不是提升模型能力。它的目標讀者是同時支援多種代理工具的團隊：有人用 Claude Code，有人用 Cursor，有人用 Codex，於是倉庫裡同時存在 CLAUDE.md、.cursor/rules/*.mdc、AGENTS.md、copilot-instructions.md。這些檔案描述的其實是同一份專案知識，卻各自腐化。README 的立場很清楚：讓工具從程式碼推導出這些內容，並在程式碼變動時重新推導。
評分不打 LLM：確定性的檢查清單
README 提供的 Before/After 對照顯示，一個只有手寫 CLAUDE.md 的倉庫在初始狀態下拿到 35/100、Grade D，跑完 /setup-caliber 後變成 94/100、Grade A。分數拆成六個維度：FILES & SETUP、QUALITY、GROUNDING、ACCURACY、FRESHNESS、BONUS。
關鍵在於評分方式。README 明確寫道評分是確定性的，不用 LLM、不發 API 呼叫，做法是把設定檔與實際的專案檔案系統交叉比對：被引用的路徑是否存在、程式碼區塊是否齊全、自上次提交以來是否出現設定漂移。這代表分數可以被重現，也代表它無法判斷文字寫得好不好。一份敘述空洞但路徑全部正確的 CLAUDE.md，在 GROUNDING 與 ACCURACY 上會拿到高分。分數衡量的是設定檔與倉庫的一致性，不是設定檔的內容品質，兩者不要混為一談。
命令列上可以比較分支差異：caliber score --compare main。這個設計適合放進 PR 流程，讓設定檔的退化和程式碼一起被看見。
bootstrap 之後，工作交給代理技能
安裝分兩段。第一段在終端機執行 npx @rely-ai/caliber bootstrap，README 標示這步約兩秒且完全在本機進行，不呼叫 LLM、不傳送程式碼。它的作用是安裝 /setup-caliber 這個技能。
第二段必須在 Claude Code 或 Cursor 的 CLI session 中輸入 /setup-caliber，README 特別提醒不要在 IDE 的聊天視窗裡做。這一步由代理分析語言、框架、依賴與架構，產生各平台的設定檔，並安裝 hook。若你不使用這兩個工具，改用 caliber init，它是同樣流程的命令列精靈，可搭配自己的 Anthropic、OpenAI、MiniMax 或 Vertex AI 金鑰。
之後進入循環：程式碼演進，caliber refresh 重新產生設定。pre-commit hook 會自動觸發這個循環。整個資料流可以理解為：bootstrap 裝技能，代理產生設定，hook 在提交時偵測漂移並刷新。Caliber 本身不生成文字，生成由你的模型與金鑰完成，這也是它宣稱不接觸程式碼的原因。
它會寫出哪些檔案
不同平台產出的檔案並不相同，這點在採用前要先看清楚。Claude Code 拿到 CLAUDE.md、CALIBER_LEARNINGS.md、.claude/skills/*/SKILL.md、.mcp.json 與 .claude/settings.json，其中 skills 採用 OpenSkills 格式。Cursor 拿到 .cursor/rules/*.mdc，帶有 description、globs、alwaysApply 的 frontmatter，另有 .cursor/skills/*/SKILL.md 與 .cursor/mcp.json。Codex 拿到 AGENTS.md 與 .agents/skills/*/SKILL.md。OpenCode 同樣使用 AGENTS.md，README 說明當兩者都被指定時會共用同一份，技能放在 .opencode/skills/。GitHub Copilot 只拿到 .github/copilot-instructions.md。
這裡可以看出一個取捨：Copilot 的支援明顯比其他平台淺，沒有對應的技能目錄與 MCP 設定。若你的團隊以 Copilot 為主，Caliber 能幫你維護的只有單一檔案。另外 .mcp.json 標示為自動探索的 MCP 伺服器設定，這意味著產出內容取決於探索結果，值得在第一次產生後逐項檢查，而不是直接提交。
審核在前、寫入在後，以及 undo
Caliber 的寫入流程刻意模仿程式碼審查。先評分，這是唯讀稽核；再提出變更，以 diff 呈現；然後由你逐項接受、透過對話調整或拒絕；寫入前原始檔會備份到 .caliber/backups/；最後 caliber undo 可還原到先前狀態。README 說它不會在未經詢問的情況下覆蓋既有設定。
有一個分支值得注意：如果現有設定已經拿到 95 分以上，Caliber 會跳過完整重寫，只針對未通過的檢查做局部修補。這是聰明的省事設計，但也意味著高分倉庫不會得到結構性調整，只會補洞。當你覺得設定檔的組織方式本身有問題時，高分反而會讓工具不動作。
備份與 undo 是這個工具最實際的安全網。不過 README 沒有說明備份保留幾份、undo 能回溯幾步，這在長期使用後會變成需要自己驗證的問題。
Windows、hook 與其他會靜默失敗的地方
README 的 Windows 說明是整份文件裡最具體的警告。首先必須從終端機執行，PowerShell、CMD 或 Git Bash 皆可，但不能從 IDE 聊天視窗。其次建議使用 Git Bash，因為 pre-commit hook 與自動同步腳本使用 shell 語法，Git for Windows 附帶的 Git Bash 會自動處理；若你只用 PowerShell，hook 可能被靜默跳過。靜默是關鍵詞，這代表你不會看到錯誤，只會發現設定檔停止更新。
另外兩點：Cursor Agent CLI 在 Windows 上要從官網下載而非使用 curl | bash，並在終端機執行 agent login；同一個專案不要同時開多個終端機跑 Caliber，README 說這會造成狀態衝突與非預期的 provider 偵測結果。
把這些限制放在一起看，Caliber 的失敗模式偏向安靜而非吵鬧。hook 沒跑、狀態衝突、provider 認錯，都不會擋住你的提交。若你打算採用，驗證 hook 是否真的執行是第一個要做的檢查，而不是等到某天發現 CLAUDE.md 還停在三個月前的架構。
什麼時候該改用其他做法
如果你的需求只是讓一份 CLAUDE.md 保持正確，直接手寫並在 PR 檢查清單裡加一行就夠了，不需要引入一個會寫檔、裝 hook、管備份的工具。Caliber 的價值隨代理數量增加而上升，單一代理的專案用起來是殺雞用牛刀。
另一個方向是通用文件產生器，例如以程式碼註解為來源的 API 文件工具。差異在於產出物與觸發時機：那類工具產出的是給人讀的參考文件，通常在發布流程觸發；Caliber 產出的是給代理讀的上下文檔，在每次提交時刷新，且格式要符合各代理的載入慣例，例如 .cursor/rules 的 frontmatter 或 OpenSkills 的 SKILL.md 結構。自己寫腳本也能做到類似效果，但你要自行維護五套格式與 MCP 探索邏輯，這正是 Caliber 想省下的部分。
反過來說，如果你的倉庫已經有一套運作良好的設定產生流程，Caliber 的評分模型與你的標準未必一致，35 分或 94 分對你沒有意義。分數是它自己的尺，不是產業標準。
維護成本與授權
專案以 MIT 授權發布，套件名稱為 @rely-ai/caliber，主要語言是 TypeScript，需要 Node.js 20 以上。MIT 意味著你可以自由使用與修改，但授權不涉及你產出的設定檔內容，也不涉及你把程式碼送進哪個模型供應商，那部分取決於你自己帶的金鑰與供應商條款。這裡不構成法律意見，實際條款請自行確認。
版本節奏值得留意。近期發布紀錄顯示 v1.53.3、v1.53.4、v1.53.5 集中在同一天，這種密度通常代表活躍修補，也代表行為可能在短時間內變動。對已經寫入 hook 的團隊來說，升級前先在分支跑一次 caliber score 與 diff，比直接更新套件安全。
長期成本主要落在兩處：一是 hook 在每次提交時執行 refresh 所帶來的時間與噪音，二是設定檔產出後仍需人工審閱，因為 Caliber 提供的是差異與分數，不是正確性保證。把它當成一位會自動更新文件但需要你按確認的同事，比較接近實際使用感受。
編輯結論
如果你同時用 Claude Code、Cursor、Codex 或 Copilot，而且已經被多份互相矛盾的設定檔拖住，Caliber 值得先跑一次 caliber score 看現況分數，再決定是否讓它接管寫入。若你的 CLAUDE.md 本來就簡短且不引用具體路徑，或者你無法接受 pre-commit hook 在每次提交時執行 refresh，這個工具帶來的複雜度高於收益。採用前請先確認三件事：Node.js 版本是否達到 20、Windows 上是否使用 Git Bash（PowerShell 下 hook 可能靜默跳過）、以及 .caliber/backups/ 與 caliber undo 的還原範圍是否符合你的預期。
社群筆記