audit-rules
audit-rules
Diagnose agent instruction files (AGENTS.md, CLAUDE.md, CLAUDE.local.md, etc.) against best practices, report issues, then optionally improve them with user consent.
Core principle: Diagnose → Report → Ask whether to improve → Apply only what is approved.
Guardrails
| # | Check | On failure |
|---|---|---|
| - | Skill update check | Let SELF be the value of the name field in this SKILL.md's frontmatter (e.g., init-public-rules). Let LOCAL be metadata.version from this same frontmatter. Fetch https://raw.githubusercontent.com/dev-goraebap/agent-collab/main/manifest.json (1 HTTP request, fail silently on network error). Then evaluate exactly one case in this order: Case A — outdated: if manifest.skills[SELF] exists and LOCAL < manifest.skills[SELF], tell the user (in their language) "agent-collab {SELF} has a new version ({LOCAL} → {manifest.skills[SELF]}). Run /agent-collab-updater when convenient. Continuing with the current task." then proceed. Case B — up to date: if manifest.skills[SELF] exists and LOCAL === manifest.skills[SELF], proceed silently. Case C — renamed away: if SELF does NOT exist as a key in manifest.skills AND SELF exists as a key in manifest.deprecated (note: check the keys of deprecated, not the renamedTo values), tell the user "This skill {SELF} was renamed to {manifest.deprecated[SELF].renamedTo} since v{manifest.deprecated[SELF].since}. Run /agent-collab-updater to migrate." then proceed. Case D — unknown: if SELF is not in manifest.skills and not in manifest.deprecated, tell the user "Skill {SELF} is no longer maintained. Run /agent-collab-updater to clean up." then proceed with caution. Important: manifest.deprecated maps OLD names → NEW names. Never warn about a skill whose name is currently in manifest.skills just because that name appears as a renamedTo value somewhere in deprecated. |
Language Policy
Conduct all user-facing communication in the user's language: interview questions, follow-up prompts, status messages, diagnostic reports, and summaries. Detect the language from (in order):
- The language of the user's most recent messages in the current session
- Declarations in their local rules file (e.g.,
CLAUDE.local.md,.cursor/rules/local.mdc) — look for instructions like "respond in Korean" - OS locale (
$LANG,$LC_ALL) - English as fallback
Generated file content follows the file's audience: team-shared files (AGENTS.md, CHANGELOG.md) stay in English regardless of the user's language; personal files (CLAUDE.local.md, GEMINI.local.md, etc.) use the user's language unless they specify otherwise.
Target Files
Auto-scan these files from the project root:
| File | Agent |
|---|---|
AGENTS.md |
Universal |
CLAUDE.md or .claude/CLAUDE.md |
Claude Code |
CLAUDE.local.md |
Claude Code personal |
.cursorrules |
Cursor (legacy) |
.cursor/rules/*.mdc |
Cursor (current) |
.github/copilot-instructions.md |
GitHub Copilot |
.windsurfrules or .windsurf/rules/*.md |
Windsurf |
GEMINI.md |
Gemini CLI |
.roo/rules/*.md |
Roo Code |
.junie/guidelines.md |
JetBrains Junie |
Only inspect files that exist. If none are found:
"No agent instruction files found. Run /init-public-rules to create one."
Diagnostic Items
Read references/checklist.md for the full checklist.
1. Anti-Pattern Detection
| ID | Anti-Pattern | Severity | Criteria |
|---|---|---|---|
| A1 | Self-evident advice | Medium | Phrases like "write clean code", "follow best practices" that don't change behavior |
| A2 | Linter/formatter overlap | Medium | Specifying formatting rules (indentation, semicolons) when ESLint/Prettier/Biome exists |
| A3 | Code-readable content | Medium | Copying package.json scripts verbatim, listing directory structure as raw tree output |
| A4 | Stale references | High | Mentioning non-existent files, directories, or functions |
| A5 | Cross-tool duplication | Medium | Same rules duplicated in AGENTS.md and CLAUDE.md |
| A6 | Vague boundaries | Medium | No Boundaries section, or items listed without Always/Ask/Never categorization |
| A7 | Private settings in public file | High | AGENTS.md containing response language, personal URLs, personal habits |
2. Token Efficiency Analysis
| ID | Item | Criteria |
|---|---|---|
| T1 | Total length | AGENTS.md: under 150 lines recommended, 300 warning, 500+ danger |
| T2 | Section balance | Flag if any section exceeds 40% of total |
| T3 | Bridge inefficiency | CLAUDE.md contains duplicated content instead of just @AGENTS.md or @../AGENTS.md |
| T4 | Excessive comments/descriptions | More explanation than rules (action directive ratio < 50%) |
3. Structure Checks
| ID | Item | Criteria |
|---|---|---|
| S1 | Commands placement | Recommend if no commands section near top of file |
| S2 | Missing code examples | Code Style section has descriptions but no code snippets |
| S3 | Missing command flags | Only npm test without -- --coverage or similar flags |
| S4 | Missing Boundaries | No Always/Ask/Never three-tier boundaries |
| S5 | Missing bridge | AGENTS.md exists but neither .claude/CLAUDE.md nor root CLAUDE.md found — suggest running /init-public-rules |
4. Spec Index Validation
Runs only when AGENTS.md contains a ## Specs (or ## Specs (<Platform>)) section. If the section is absent, skip this entire category silently — the user is not using /manage-docs and these checks would just produce noise.
| ID | Item | Severity | Criteria |
|---|---|---|---|
| X1 | Specs section orphan | High | The ## Specs section references a folder or INDEX.md path that does not exist on disk |
| X2 | INDEX dangling entries | High | Inside INDEX.md, items in ## Always-on or ## Active work point to files that no longer exist |
| X3 | INDEX header drift | Medium | INDEX.md is missing one of the three standard section headers (## Always-on, ## Active work, ## Archived) or they have been renamed/decorated |
| X4 | Incomplete Specs section | Low | A ## Specs section exists but contains neither an INDEX.md path (in-repo mode) nor an external platform usage convention (external mode) — looks hand-written and may confuse /manage-docs on next invocation |
Workflow
Step 1: Collect and Read Files
Read all target files and tally line counts and approximate token counts (lines × 3 estimate).
Step 2: Run Checklist
Iterate through all items in references/checklist.md. For stale reference checks (A4), verify that mentioned files/directories actually exist.
For Spec Index Validation (X1–X4): first check whether AGENTS.md contains a ## Specs (or ## Specs (<Platform>)) section. If not, skip the entire X category — the user is not using /manage-docs and these checks would only add noise. If yes, run X1 (orphan), X2 (dangling, only when in-repo mode is detected via an INDEX.md path), X3 (header drift), and X4 (incomplete).
Step 3: Output Diagnosis Report
Present results sorted by severity (High → Medium → Low):
📋 Rules Diagnosis Report
File: AGENTS.md (187 lines, ~561 tokens)
File: .claude/CLAUDE.md (1 line, @../AGENTS.md bridge)
--- Issues Found (5) ---
🔴 [A4] Stale reference
Line 32: `src/utils/auth.ts` — file does not exist
→ Suggestion: Remove line or update to actual path
🟡 [A2] Linter overlap
Lines 45-48: "2-space indent, semicolons required" — .prettierrc already handles this
→ Suggestion: Delete these 4 lines (Prettier auto-handles)
🟡 [T1] Length warning
187 lines — recommended under 150. Current level is acceptable but watch additions
→ Suggestion: Review if Code Style section (52 lines) can be trimmed
🟡 [A1] Self-evident advice
Line 71: "Always write clean code"
→ Suggestion: Delete (not a concrete action directive)
🟢 [S3] Missing command flags
Line 12: `npm test` — consider adding coverage or single-file options
→ Suggestion: Add `npm test -- --coverage`
--- Passed (12) ---
✅ Commands placement correct
✅ Boundaries with clear 3-tier separation
✅ Bridge file (.claude/CLAUDE.md) exists
...
Step 4: Ask Whether to Improve
If issues are found, ask the user:
Issues found. Would you like to improve them?
1. Yes — select items to fix
2. No — keep the report and finish
If "No": End with the report only. If no issues were found, skip this step entirely.
If "Yes": Proceed to the next step.
Step 5: Apply Improvements
Ask the user to select items:
Please select which suggestions to apply.
Choose by number or say "apply all".
Modify only the items the user selects. When applying:
- Show what changes on which lines for each fix
- Batch all changes but show before/after diff
- If user says "apply all", apply all suggestions at once
After completion, show updated line and token counts:
✅ 4 items applied
AGENTS.md: 187 lines → 171 lines (−16 lines, ~48 tokens saved)
Cross-Skill References
Suggest other skills based on diagnostic findings:
- A5 (cross-tool duplication) is severe → "Run /migrate-rules to consolidate into AGENTS.md"
- S5 (missing bridge) → "Run /init-public-rules to create the bridge"
- A7 (private settings in public file) → "Run /init-private-rules to separate private settings"
- X1 (Specs orphan) or X4 (incomplete Specs section) → "Run /manage-docs to (re)initialize the spec index"
- X2 (INDEX dangling) → "Run /manage-docs and choose the prune action to clean up missing entries"
- X3 (INDEX header drift) → "Restore the standard headers (
## Always-on,## Active work,## Archived) in INDEX.md so /manage-docs can parse it"
Prohibited Actions
- Never modify files without user consent
- If no issues are found, report "All clean" only. Do not fabricate issues
- Never suggest rewriting a file from scratch. Always suggest partial edits