設定 vibator
參考資訊：npx vibator docs configuration 會印出設定格式，而
npx vibator docs rules 則會印出每條規則及其選項與預設值。
此技能是工作流程；那些文件才是合約。
設定是一個探索任務：正確的設定取決於專案實際包含的內容。先檢查，再撰寫，然後執行。
基本規則
- 絕不為讓檢查通過而弱化閘門。 關閉規則、放寬其預算或排除某個檔案，只因為它目前檢查失敗，只會隱藏問題而非解決問題。請修正檢查結果，或讓規則保持失敗狀態並明確說明。唯一的單行跳過方式是
// vibator-ignore: <原因>，且原因為必填。 - 僅設定與預設值不同的項目。 每條規則在沒有任何設定時，都已以其自身的預設嚴重程度執行。一個重新陳述所有預設值的設定檔，只會淹沒真正重要的設定行。
include和exclude會取代規則的預設值。 它們不會合併。在縮小範圍前，請先複製您仍需要的預設值。- 絕不設
recommended: false僅為讓執行通過。 它會停用設定檔中未命名的所有規則，包括那些通過的規則。它存在的目的是為了明確聲明一個經過審慎選擇的項目，而這個選擇必須由人類決定。 - 專案所延伸的設定檔不是您可以編輯的。 預設集定義了多個專案共用的標準。請在本機設定差異部分，或請求人類修改預設集。絕不要透過編輯
node_modules底下的檔案來消除檢查結果；下次安裝時它仍會被取代。
步驟
-
從有效檔案開始。 如果沒有
vibator.json，請執行npx vibator init；它會寫入$schema行，為編輯器提供驗證功能。 接著執行npx vibator list會顯示每條規則及其預設值。 在撰寫自己的規則之前，請先檢查專案是否已延伸某個預設集，或是否存在可供延伸的預設集（例如package.json中的@scope/quality風格套件，或跨多個同級儲存庫重複的相同設定）。延伸它勝過重新陳述它；請參閱下方的「建置於共用預設集上」。 -
執行一次，無設定：
npx vibator --reporter json。這會顯示 哪些規則通過、哪些失敗，以及哪些因缺少選項而崩潰。先閱讀計數，再閱讀診斷資訊；一條有 400 個檢查結果的規則需要一個決定，而不是今天修復 400 個問題（請參閱步驟 6）。 -
探索預設關閉的規則需要什麼。 每條規則關閉是因為它無法在沒有專案知識的情況下運作。請尋找它們：
locale-parity：找到 locales 目錄（locales/、i18n/、public/locales/）。注意佈局：每個語言一個目錄 （layout: "directory-per-locale"）或每個語言一個檔案 （"file-per-locale"），以及哪個語言是來源語言。codegen-drift：閱讀package.json中的 scripts，尋找程式碼產生器 （db:generate、openapi、graphql-codegen），並找出每個產生器寫入的路徑。為每個產生器設定一個項目，包含name、command、paths。banned-patterns：閱讀專案的審查慣例（CONTRIBUTING、 樣式文件、反覆出現的審查意見）。每個「絕不要做 X」的模式形狀都會變成一個項目，包含自己的message、expected和fix， 撰寫時要像內建規則一樣謹慎。no-deprecated-apis：列出 tsconfig；單倉庫可能希望每個應該被檢查的專案都列在options.projects中。
-
使用
guidelines將現有專案文件連結到規則上。 如果儲存庫有AGENTS.md、CLAUDE.md或聲明了某個規則所強制執行標準的樣式文件，請對應它："guidelines": {"AGENTS.md": ["tsdoc-coverage"]}。僅在專案的標準取代了內建指南而非提供額外上下文時，才使用每個規則的docs欄位。 -
對分割標準使用陣列形式。 一條規則可以使用不同的 glob 和選項執行多次：
"max-file-size": [ {"include": ["src/**"], "options": {"maxKb": 256}}, {"include": ["assets/**"], "options": {"maxKb": 4096}} ] -
在遺留程式碼庫上透過
--changed逐步採用，而非透過弱化規則。 立即檢查新工作（npx vibator --changed，或在 CI 中針對拉取請求的整個差異使用--since origin/main），同時逐步處理積壓問題。對於有大量檢查結果的規則，請在過渡期使用warn：檢查結果保持可見但不阻擋。不要使用off來代表「以後再說」。 -
驗證結果。 執行
npx vibator並確認：每個啟用的規則都有執行（崩潰的規則是設定錯誤，其訊息會指出缺少了什麼）、剩餘的檢查結果是真實的，並且npx vibator explain <rule>對任何您覆寫的項目顯示正確的指南。
建置於共用預設集上
extends 接受以 . 開頭的路徑或套件識別碼，並根據宣告它的檔案來解析。較晚的項目會覆蓋較早的項目，而檔案自身的設定會覆蓋所有項目。
{
"extends": ["@acme/quality/vibator.json"],
"rules": { "max-file-size": "warn" }
}
合併行為遵循 Biome，因此該堆疊的使用者會如預期般運作。有兩個後果需要正確處理：
- 純嚴重程度會保留其他所有設定。 在一個設定了
maxKb和include的預設集之上寫入"max-file-size": "warn"只會更改嚴重程度；預算和 glob 會被繼承。您不需要重新陳述它們，而重新陳述它們正是專案默默偏離其預設集的方式。 - 陣列是取代，而非串接。 要為繼承而來的
allow或patterns清單新增一個項目時，請寫入您想要的整個清單。這是刻意的：它使得移除一個繼承而來的項目成為可能。
只寫出差異部分。一個重複預設集已經說明內容的設定檔，與一個與預設集牴觸的設定檔是無法區分的，而下次預設集更新將不會影響您所複製的欄位。
一個作為精選項目建置的預設集會設定 "recommended": false 並列出它想要的規則。在此類預設集下，未命名的規則不會執行，因此在斷定缺少某條規則之前，請先檢查這一點。
指南路徑以相同方式解析：由預設集陳述的 docs 和 guidelines 項目會根據預設集進行解析，因此檢查結果會指向與預設集一起提供的文件。您自己的路徑仍會根據專案根目錄進行解析。
嚴重程度政策
error：確定性規則，幾乎沒有誤報。warn：可能對其未見過的程式碼庫判斷錯誤的規則（env-example-sync比對文字；prefer-array-methods無法區分陣列與Set），以及具有大量積壓問題的規則的過渡期採用。off：僅適用於不適用的規則（沒有語言環境意味著沒有locale-parity），絕不作為通過檢查的手段。
常見錯誤
- 寫入
include而遺失規則的預設排除項目（測試、.d.ts）。 - 在嚴重程度覆寫旁重述預設集的選項，假設純嚴重程度會捨棄它們。它不會，而且複製會停止追蹤預設集。
- 啟用
codegen-drift，但其使用的產生器需要環境中沒有的服務或金鑰。該規則會實際執行命令。 - 在
guidelines中將每個文件對應到每條規則。僅對應實際陳述該規則標準的文件。 - 編輯設定檔以結束失敗的執行，而不是修正檢查結果。 如果人類要求設定閘門，只有人類才能決定降低它。