Agent Config Audit

Agent Config Audit

Audit and maintain the full AI agent configuration stack across a workspace — CLAUDE.md, CODEX.md, AGENTS.md, .cursorrules, hooks, settings, and supporting .agents/ docs.

Contract

Inputs:

• Workspace root
• Scope: full, dedup, stale, codex, cursor, settings, or fix
• Optional list of repos/config files to include

Outputs:

• Audit report with critical/moderate/minor findings
• Proposed fix plan
• Applied changes only when fix mode is explicit

Creates/Modifies:

• Report mode: no file changes
• Fix mode: agent config files, .agents/ docs, and related settings

External Side Effects:

• None by default
• Does not push, publish, or call external APIs

Confirmation Required:

• Before applying fix mode
• Before overwriting existing agent configs
• Before deleting or consolidating duplicated rules

Delegates To:

• rules-capture for single new preferences
• agent-folder-init for missing .agents/ structure
• session-documenter when audit findings should be recorded

When to Use

• User mentions: "audit CLAUDE.md", "agent config", "rules out of date", "config drift", "sync docs"
• After restructuring repos, adding/removing projects, or changing conventions
• Periodic maintenance (monthly recommended)
• When agents keep making the same mistake despite rules existing (symptom of stale or contradictory config)
• After a major refactor where file paths, package names, or architecture changed

When NOT to Use

• If writing actual application code → use bugfix, refactor-code, or repo-specific skills
• If capturing a single new rule from conversation → use rules-capture
• If auditing code quality / CRITICAL-NEVER-DO violations → use genfeed-codebase-audit
• If checking formatter/linter configs (biome, prettier, tsconfig) → use genfeed-config-harmony
• If scaffolding .agents/ from scratch → use agent-folder-init

Inputs

Workflow

Step 1: Inventory — Discover All Config Files

Scan the workspace for every agent config file:

# Find all agent config files across workspace (including sub-repos)
glob "**/CLAUDE.md"
glob "**/CODEX.md"
glob "**/AGENTS.md"
glob "**/.cursorrules"
glob "**/.cursor/rules"
glob "**/.claude/settings.json"
glob "**/.claude/settings.local.json"
glob "**/.claude/hooks.json"
glob "**/.agents/memory/*.md"

Build an inventory table:

| Layer           | Files Found | Total Lines |
|-----------------|-------------|-------------|
| CLAUDE.md       | N           | N           |
| CODEX.md        | N           | N           |
| AGENTS.md       | N           | N           |
| .cursorrules    | N           | N           |
| .claude/ config | N           | N           |
| .agents/memory/ | N           | N           |

Step 2: Dedup Check — Find Duplicated Rules

These rules commonly appear in multiple places. Search for each across ALL config files:

Rules to check:

• any types / No any — should be in CLAUDE.md + hooks only
• console.log / logger — should be in CLAUDE.md only
• Conventional commits — should be in CLAUDE.md only
• AbortController — should be in CLAUDE_RULES.md / repo CLAUDE.md only
• Session file naming — should be in hooks.json + one doc reference only
• Import order — should be in CLAUDE_RULES.md only
• Soft delete (isDeleted) — should be in CRITICAL-NEVER-DO.md only
• Multi-tenancy (organization: orgId) — should be in CRITICAL-NEVER-DO.md only

For each rule, count occurrences:

grep "No \`any\`\|NO \`any\`\|no any types" across all config files

Healthy target: Each rule appears in max 2 files (one "teach" doc + one runtime enforcement like hooks).

Flag: Any rule appearing 3+ times across config files.

Step 3: Staleness Check — Find Outdated Files

Check for stale dates and paths:

# Find files with old "Last Updated" dates (> 90 days old)
grep -r "Last Updated:" across .cursorrules, .cursor/rules

# Find hardcoded workspace paths that should be relative
grep -r "/Users/" across .agents/ config files

# Find references to directories that no longer exist
# Compare referenced paths against actual directory listing

Flag: Any file with "Last Updated" > 90 days behind current date. Flag: Any hardcoded absolute path in config files. Flag: Any reference to a directory that doesn't exist.

Step 4: CODEX.md Value Check

For each CODEX.md, check if it has:

• [ ] Codex-specific constraints (sandbox, no network, no interactive)
• [ ] Repo-specific entry points (key files to read first)
• [ ] NOT just "read CLAUDE.md" (that's a zero-value redirect stub)

grep -l "Codex-Specific\|sandbox\|no network\|No network" across all CODEX.md files

Flag: Any CODEX.md without Codex-specific guidance.

Step 5: AGENTS.md Consistency Check

For each AGENTS.md:

• [ ] Has repo-specific context (not just generic "docs in .agents/")
• [ ] Links to correct .agents/ paths that actually exist
• [ ] Consistent structure across repos

Flag: Any AGENTS.md that's a pure generic stub (< 20 lines with no repo-specific content).

Step 6: Cursor Config Check

For .cursorrules and .cursor/rules:

• [ ] No emoji in headers (wastes tokens)
• [ ] "Last Updated" within 90 days
• [ ] Project paths reference actual directories
• [ ] No duplicated session file rules (hooks.json handles this)

Step 7: Settings Audit

For .claude/settings.json and .claude/settings.local.json:

• [ ] Denied skills have documented rationale (in SETTINGS-NOTES.md or equivalent)
• [ ] Local bash overrides don't contradict documented standards without explanation
• [ ] No stale tool references

Step 8: Generate Report

Output format:

# Agent Config Audit Report
**Date:** YYYY-MM-DD
**Workspace:** [path]
**Files Scanned:** N

## Summary
- Critical issues: N
- Moderate issues: N
- Minor issues: N
- Total config lines: N (target: reduce by dedup)

## Critical: Rule Duplication
| Rule | Occurrences | Files | Target |
|------|-------------|-------|--------|
| "No any types" | 6 | [list] | 2 |

## Critical: Stale Files
| File | Last Updated | Days Stale |
|------|-------------|------------|

## Moderate: Low-Value CODEX.md
| File | Lines | Has Codex Constraints | Has Entry Points |
|------|-------|----------------------|------------------|

## Moderate: Stub AGENTS.md
| File | Lines | Has Repo Context |
|------|-------|------------------|

## Minor: Emoji in Config
| File | Emoji Count |
|------|-------------|

## Recommendations
1. [Specific actionable fix]
2. [Specific actionable fix]

Step 9: Apply Fixes (if fix mode)

If user requested fix mode, apply changes following these principles:

• Each rule lives in ONE canonical location
• Hooks enforce at runtime — docs teach, not repeat
• Strip emoji from all config files
• Update all "Last Updated" dates
• Replace hardcoded paths with relative references
• Expand zero-value CODEX.md stubs with Codex-specific constraints

Reference Files

• references/canonical-ownership.md — Which rule belongs in which file
• references/healthy-config-example.md — Example of a well-structured config set

Anti-Patterns

Validation

After running the audit:

• [ ] No rule appears in more than 2 config files
• [ ] All .cursorrules files have "Last Updated" within 90 days
• [ ] Every CODEX.md has Codex-specific sandbox guidance
• [ ] No hardcoded absolute paths in any config file
• [ ] No emoji in .cursorrules or .cursor/rules headers
• [ ] Denied skills in settings.json have documented rationale
• [ ] Total config file line count decreased or stayed flat (no bloat)

Related Skills

• rules-capture — Route here if user is expressing a new rule during conversation (not auditing)
• agent-folder-init — Route here if scaffolding .agents/ structure from scratch
• genfeed-config-harmony — Route here if the issue is formatter/linter configs (biome, prettier, tsconfig)
• genfeed-codebase-audit — Route here if auditing code quality, not config quality
• claude-md-management:revise-claude-md — Route here if updating a single CLAUDE.md with session learnings (not full audit)
• claude-md-management:claude-md-improver — Complementary; focuses on individual CLAUDE.md quality while this skill focuses on cross-file consistency

Canonical Rule Ownership

Each rule should live in ONE file. Other files may reference it but should not repeat it.

Ownership Map

File Roles

Referencing vs Repeating

Good reference (brief, points to canonical):

No `any` types — see CLAUDE.md cross-repo rules for details.

Bad repetition (full rule restated):

No `any` types — use `unknown` or proper interfaces. Define all interfaces in `packages/interfaces/` or `packages/props/`.

The second version will drift when the canonical source gets updated.

Healthy Config Set — Example

What a well-maintained agent config stack looks like for a monorepo workspace.

Root Level

CLAUDE.md (~80 lines)

• Workspace overview (repo table)
• Cross-repo rules (5-7 rules, one line each)
• Agent behavior section
• Self-correction protocol
• Learned Rules section (seeded, actively used)

CODEX.md (~30-40 lines)

• Codex-specific constraints (sandbox, no network, no interactive)
• Quick nav to critical docs
• Cross-repo rules (brief, for context since Codex can't load CLAUDE.md hierarchy)

AGENTS.md (~15-20 lines)

• Brief workspace description
• Navigation to .agents/README.md and CLAUDE.md
• Links to priority reading

.cursor/rules (~100-130 lines)

• No emoji in headers
• Reading order for session start
• Session file rules (brief, since hooks enforce)
• Project navigation structure
• Documentation location table
• "Last Updated" within 90 days

.claude/settings.json

• Denied skills with companion SETTINGS-NOTES.md documenting rationale
• MCP server config

.claude/hooks.json

• Runtime enforcement for violations that burn the most time
• Fast timeouts (5s)
• Targeted (not duplicating what linters catch)

Per-Repo Level

CLAUDE.md (~50-150 lines)

• Tech stack
• Commands (dev, build, test, lint)
• Repo-specific critical rules (may briefly reference cross-repo rules)
• Architecture (key directories, patterns)
• Learned Rules section (seeded)
• Does NOT repeat full cross-repo rules from root

CODEX.md (~20-30 lines)

• Codex-specific notes (what won't work in sandbox)
• Key entry points (3-5 most important files)
• Links to CLAUDE.md and .agents/

AGENTS.md (~15-30 lines)

• Repo description with tech context (not just "docs in .agents/")
• Links to project .agents/ and workspace .agents/

.cursorrules (~60-70 lines)

• No emoji
• Reading order specific to this project
• Navigation to project .agents/ structure
• "Last Updated" within 90 days

Health Metrics