audit

name: audit description: Score a codebase for AI-readiness against a 7-category 100-point rubric and generate a markdown report, an HTML dashboard, module-level CLAUDE.md scaffolds, and an ANTIPATTERNS.md seed extracted from git history. Use this skill whenever the user wants to assess how well their codebase is set up for AI agents (Claude/Codex/Gemini), generate per-module CLAUDE.md files, extract anti-patterns, or build a navigation map for a large codebase — even if they don't explicitly say the word "audit". Trigger on phrases like "ai-ready audit", "AI 준비도", "코드베이스 감사", "score my codebase for AI agents", "generate module CLAUDE.md", "anti-patterns from git history", "AI 친화 코드베이스", "make this repo navigable for Claude", or "we have no map for AI".

AI-Ready Codebase Audit

Turns a codebase into an AI-navigable one. Inspired by Meta's internal "AI had no map" → "59 module CLAUDE.md files" approach (Meta Engineering blog, 2026).

What This Skill Produces

For a target codebase you point it at, this skill creates an .ai-ready/ directory containing:

1. audit.json — raw scores (per-category, per-rule, evidence). Includes single_module_mode: bool + package_catalog: path|null so consumers know which layout was scored.
2. audit-report.md — human-readable report with ROI-prioritized action list
3. README.md — auto-generated guide for .ai-ready/ consumers (artifact map, plugin install, score interpretation, re-run instructions)
4. dashboard.html — self-contained HTML dashboard with score gauge, category bars, and trend sparkline (open in browser)
5. history/{timestamp}.json — every run is archived here so the dashboard can render a trend line. Do not delete.
6. scaffolds/... — drafts for the missing docs (see "Layout-aware scaffolds" below)
7. scaffolds/ANTIPATTERNS.md — seed anti-patterns extracted from git history (clustered hotspots)
8. hooks/freshness_check.sh — copied from the plugin so a project's .claude/settings.json Stop hook can reference it as $CLAUDE_PROJECT_DIR/.ai-ready/hooks/freshness_check.sh

Layout-aware scaffolds

The audit auto-detects the layout from build manifests and switches scoring + scaffold output:

Single-module reasoning: spawning N package-level CLAUDE.md files for a single Gradle/Maven/npm module fragments context and adds maintenance burden. A single docs/PACKAGES.md catalog (lazy-loaded from root CLAUDE.md) covers the same ground while keeping the doc surface small. The audit rubric scores them on parallel rules — see RUBRIC.md "Layout-aware scoring".

Inputs You Need

• Target codebase path (absolute path). Example: /Users/me/projects/my-api
• (Optional) Top N modules to scaffold (default: 5)
• (Optional) Lookback days for git anti-pattern extraction (default: 180)

How To Run

The skill ships a baseline four-step run plus several optional action scripts (see "Additional Action Scripts" below). All scripts are stdlib-only — no third-party dependencies. Run the four baseline scripts in this order:

SKILL_DIR="$CLAUDE_PLUGIN_ROOT/skills/audit"
TARGET="<absolute path to target codebase>"
OUT="$TARGET/.ai-ready"
mkdir -p "$OUT"

# 1) Score the codebase
python3 "$SKILL_DIR/scripts/audit.py" --target "$TARGET" --out "$OUT"

# 2) Generate scaffolds (auto-branches by layout):
#    - Multi-module → per-module CLAUDE.md drafts (top N hot modules)
#    - Single-module → docs/PACKAGES.md catalog draft (one file, all packages)
python3 "$SKILL_DIR/scripts/scaffold.py" --target "$TARGET" --out "$OUT/scaffolds" --top 5

# 3) Extract anti-patterns from git history (last 180 days)
python3 "$SKILL_DIR/scripts/extract_antipatterns.py" --target "$TARGET" --out "$OUT/scaffolds/ANTIPATTERNS.md" --days 180

# 4) Render HTML dashboard from audit.json
python3 "$SKILL_DIR/scripts/dashboard.py" --audit "$OUT/audit.json" --out "$OUT/dashboard.html"

After it finishes, open $OUT/dashboard.html to see the score, then review $OUT/audit-report.md for the ROI action list.

Additional Action Scripts

To raise the score by executing ROI actions directly, use the scripts below. The companion ai-ready:apply skill invokes them automatically, but they also work standalone — useful when you want to apply only a single action.

Scripts that modify existing files (inject_module_map.py, install_hook.py) are idempotent and expose a --dry-run option so changes can be previewed first.

Project Config (.ai-ready/config.json) — v0.2.0+

Optional file at <target>/.ai-ready/config.json enables frontmatter-aware behavior. Without it, the v0.1.x defaults apply (backward compatible — no changes for existing users).

{
  "version": 1,
  "frontmatter": {
    "required":  ["type", "feature", "module", "status", "created", "updated"],
    "search":    ["aliases", "tags"],
    "evolution": ["supersedes", "superseded-by"]
  },
  "index": {
    "groups": [
      { "id": "adr", "title": "ADR (`docs/adr/`)",
        "match": { "path_prefix": "docs/adr/" }, "sub_group_by": "feature" }
    ],
    "cross_reference": { "enabled": true, "title": "한영 검색 인덱스" },
    "evolution_graph": { "enabled": true, "title": "ADR 결정 진화", "scope": "adr" }
  },
  "lazy_load_triggers": {
    "detect":               [ { "path": "docs/adr/", "label": "[`docs/adr/`](docs/adr/)", "trigger": "ADR 조회" } ],
    "override_hardcoded":   [ "docs/decisions" ]
  },
  "rubric": {
    "decision_records": { "dir_hints": ["docs/design"] },
    "api_contracts":    { "build_deps": ["springdoc", "springfox"] }
  }
}

What it changes:

1. gen_index.py switches from hardcoded categories (claude / guides / docs-decisions / docs-other) to config-defined groups with frontmatter sub_group_by (e.g., feature/module), plus optional cross_reference and evolution_graph sections.
2. inject_lazy_load_index.py adds project-specific triggers (detect) and removes obsolete built-in ones (override_hardcoded).
3. Each .md file's YAML frontmatter is parsed via the bundled stdlib-only parser (frontmatter_parser.py) — no PyYAML dependency added.
4. audit.py scoring respects the rubric section (v0.3.0+): decision_records.dir_hints makes the ADR rule (3.2) credit a consolidated decision directory such as docs/design/ (when a project absorbed ADR/PRD/api-doc into one living doc); api_contracts.build_deps makes the API-contract rule (4.3) credit code-gen dependencies such as springdoc/springfox that emit OpenAPI at runtime. Separately — no config needed — the verification-gate rule (5.1) now also credits project-level .claude/settings.json hooks that run lint/test/format on edit/commit, recognizing the AI-agent harness as a mechanical verification gate.

Full schema is documented in skills/audit/scripts/config_loader.py.

When To Use Each Output

• audit-report.md — read first. Tells you what to fix and in what order.
• dashboard.html — share with team / track progress over time.
• scaffolds/<module>/CLAUDE.md (multi-module) — review, edit, then move into the actual module directory.
• scaffolds/PACKAGES.md (single-module) — review, fill in the TODO lines, then move to docs/PACKAGES.md and reference it from root CLAUDE.md lazy-load.
• scaffolds/ANTIPATTERNS.md — review, prune false positives, then move to repo root.
• hooks/freshness_check.sh — install as a Claude Code Stop hook (instructions below).

Installing the Freshness Hook

After reviewing the generated scaffold, add this to the target project's .claude/settings.json:

{
  "hooks": {
    "Stop": [
      {
        "matcher": ".*",
        "hooks": [
          { "type": "command", "command": "$CLAUDE_PROJECT_DIR/.ai-ready/hooks/freshness_check.sh" }
        ]
      }
    ]
  }
}

The hook runs at session end, compares mtimes between source files and their nearest CLAUDE.md, and writes a warning if the source has drifted ahead by >7 days (configurable inside the script).

The 7-Category Rubric (100 points)

See RUBRIC.md for the full criteria and detection rules. Summary:

Grade bands: 0-39 = AI-blind, 40-59 = AI-aware, 60-79 = AI-enabled, 80-89 = AI-maximalist, 90-100 = Agentic-ready.

Detection Heuristics (Quick Reference)

The audit script looks at:

• Presence and line counts of CLAUDE.md (root + per module)
• Presence of ANTIPATTERNS.md, ARCHITECTURE.md, ADR/, docs/decisions/
• Hooks in .git/hooks/, .husky/, .claude/hooks/, .claude/settings.json
• CI configs: .github/workflows/, .gitlab-ci.yml, .circleci/, Jenkinsfile
• Build manifest signals to identify modules: build.gradle.kts, build.gradle, pom.xml, package.json, Cargo.toml, go.mod, pyproject.toml, Package.swift (Swift Package Manager), Podfile (CocoaPods)
• Recent git activity to find "hot" modules
• "DO NOT" / "절대" / "금지" / "MUST NOT" markers in CLAUDE.md content

Limitations

• Heuristics-based scoring; expect ±5 points of noise. Use the trend, not the absolute number.
• Anti-pattern extraction depends on commit message hygiene. Repos with vague messages produce thin output.
• The skill is language-agnostic but the module detection prefers conventional layouts (Gradle multi-module, npm monorepo, Python src/ layout, Go modules, Cargo workspaces).
• HTML dashboard is intentionally dependency-free (vanilla CSS + inline SVG) — pretty enough but not interactive.

Re-running

This is meant to be run periodically (monthly is a good cadence). Each run overwrites audit.json / audit-report.md / dashboard.html / README.md, but also archives the result to history/{timestamp}.json so the dashboard can render a trend sparkline. Don't delete the history/ directory.

월간 정합 스캔 연계: 대상 repo 가 living design 문서 체계 (docs/design/domain_{name}.md) 를 쓰면, 월간 audit 와 같은 날 /sync-docs --all (전역 드리프트 스캔) 을 함께 수행하는 리듬을 권장한다. 역할 분담 — audit 는 구조 지표 (커버리지 / 길이 / freshness 메타), 전역 스캔은 내용 정합 (문서 서술 ↔ 코드 동작의 양방향 드리프트). audit 만으로는 문서 내용이 코드와 맞는지 보장되지 않는다.