instrlint

English | 繁體中文

instrlint 會 lint 自己。

為什麼需要 instrlint？

CLAUDE.md 會隨時間膨脹。規則從範本複製過來、在不同段落重複出現、或留著指向早已不存在的檔案。有些規則默默地和 tsconfig.json、.editorconfig 重複——白白佔用 token 預算，什麼好處也沒有。

instrlint 掃描你的指令檔，告訴你哪裡要修。一個指令、一個分數、一份可執行的報告。

有兩件事讓它和單純的行數計算工具不同：

• Host 協調的 LLM 驗證 — 在 Claude Code 執行 /instrlint --verify，host model 自己判斷有疑義的 findings。不需要 API key，不需要外部服務。當前 session 裡已在運行的模型就是驗證者。
• 拆分決策引導 — 根指令檔太長時，instrlint 不只說「去拆一拆」，而是逐段引導你做決定：每個段落會被分入四個桶，再依你選擇的範圍執行——因為並非每份過長的 CLAUDE.md 都該用同一種方式拆。

支援 Claude Code、Codex 和 Cursor。487 個測試。從 v0.2.3 開始用自己 lint 自己。

快速開始

npx instrlint

在含有 CLAUDE.md 或 AGENTS.md 的專案根目錄執行即可，免安裝。

或全域安裝，在任何專案都能直接使用：

npm install -g instrlint
instrlint

輸出範例

  ╭──────────────────────────────────────────────────╮
  │  instrlint  ─  sample-project                    │
  │  claude-code  ·  measured                        │
  ├──────────────────────────────────────────────────┤
  │  ███████████████░░░░░░░░░░░░░░░  50/100   F      │
  ╰──────────────────────────────────────────────────╯

  ── 預算 ──────────────────────────────────────────────
  18,957 / 200,000 tokens (9%)  █░░░░░░░░░░░░░

  ── 問題總覽 ────────────────────────────────────────────
  Contradictions    ✖ 1
  Budget            ⚠ 1
  Dead rules        ⚠ 5
  Duplicates        ⚠ 1  ℹ 1
  Stale refs        ⚠ 2
  Structure         ℹ 11

  ── 首要問題 ────────────────────────────────────────────
  1. ✖  規則矛盾：「Use exceptions for error handling. Throw errors with descrip..…
  2. ⚠  根指令檔有 206 行（建議：< 200 行）
  3. ⚠  規則「Always use TypeScript strict mode. Enable all strict checks to ca…
  4. ⚠  規則「Use 2-space indentation for all files. Never use tabs.」已由 .editor…
  5. ⚠  規則「Always use semicolons at the end of statements.」已由 .prettierrc (s…
     … 還有 17 個（執行 instrlint <command> 查看詳情）

  ── 1 個嚴重問題 · 9 個警告 · 12 個建議 ────────────────────────

加上 --lang zh-TW 即可取得完整繁體中文輸出：

npx instrlint --lang zh-TW

能找出什麼問題

Token 預算 — 使用 cl100k_base encoding 計算所有指令檔和 MCP server 的 token 用量。標記超過 200 行的根指令檔，以及超過 context 視窗 25% 的情況。

冗餘規則 — 偵測已被 config 檔強制執行的規則：TypeScript strict mode、Prettier 格式化、ESLint、EditorConfig、conventional commits、C# .csproj/.editorconfig 設定等，約 20 種模式，涵蓋 JS/TS 和 C# 生態系。

結構問題 — 互相矛盾的規則、過時的檔案參照、高度相似的重複規則，以及路徑範圍化的優化機會。

自動修復 — --fix 安全地移除冗餘規則、過時參照和完全重複的規則。需要乾淨的 git 工作目錄。

CI 整合 — instrlint ci 依嚴重程度回傳 exit code。支援 SARIF 輸出供 GitHub Code Scanning 使用。使用 instrlint init-ci --github 產生 workflow 設定。

支援工具

| 工具 | 根指令檔 | 設定目錄 | |------|----------|----------| | Claude Code | CLAUDE.md | .claude/ | | Codex | AGENTS.md | .agents/, .codex/ | | Cursor | .cursorrules | .cursor/ |

從專案結構自動偵測。可用 --tool 強制指定。

支援生態系（冗餘規則偵測）

| 生態系 | 檢查的 config 檔 | |--------|------------------| | JavaScript / TypeScript | tsconfig.json、.eslintrc.*、.prettierrc.*、.editorconfig、commitlint.config.* | | C# / .NET | .csproj、Directory.Build.props、.editorconfig（dotnet_*、csharp_* 欄位）|

更多生態系（Python、Go、Rust）列入規劃。歡迎參閱貢獻新增規則。

在 Claude Code 或 Codex 中使用

安裝一次 skill：

npx instrlint install --claude-code          # 全域（~/.claude/commands/）
npx instrlint install --claude-code --project  # 僅專案
npx instrlint install --codex

重新啟動編輯器以載入指令，然後使用：

/instrlint           # 完整報告
/instrlint --fix     # 自動修復安全問題
/instrlint --verify  # LLM 驗證報告 — 不需要 API key

注意： Claude Code 只在啟動時載入 custom commands。/reload-plugins 無法載入新安裝的指令。

當報告需要更深入的審查，skill 會自動觸發兩段式驗證：instrlint 將低信心的 findings 寫成 candidates.json，host model 逐一判斷後寫 verdicts.json，再由 instrlint 合併結果——過濾 false positive，並附上 ✓ / ❓ badge。不需要 API key；當前 session 的模型就是驗證者。

根指令檔過長時，/instrlint 會引導你做拆分決策：每個段落被分入四個桶——值得抽出（低載入率）、可抽出但不省 token、該刪不是該搬、或必須留在原檔。你選範圍，skill 執行。

常用指令

instrlint                           # 完整健康檢查
instrlint --fix                     # 自動修復冗餘規則、過時參照、重複規則
instrlint --format markdown         # Markdown 輸出（供 PR 留言使用）
instrlint --lang zh-TW              # 繁體中文輸出

instrlint ci --fail-on warning      # CI 模式：警告也 exit 1
instrlint init-ci --github          # 產生 GitHub Actions workflow

instrlint install --claude-code     # 安裝為 Claude Code skill

# LLM 驗證（兩段式，不需要 API key）
instrlint --emit-candidates instrlint-candidates.json
instrlint --apply-verdicts instrlint-verdicts.json

所有選項請執行：instrlint --help

貢獻

核心差異化功能是 src/detectors/config-overlap.ts 中的 config 重疊規則。新增規則的方式：

1. 在 OVERLAP_PATTERNS 陣列新增一筆
2. 將規則關鍵字對應到強制執行它的 config 檔 + 欄位
3. 在 tests/fixtures/ 新增觸發該規則的 fixture
4. 在 tests/detectors/config-overlap.test.ts 新增測試案例

完整架構文件請參閱 CLAUDE.md。

授權

MIT — 詳見 LICENSE