Project Audit

Elite Project Audit Skill

Purpose

Audit any Claude Code project across 10 categories. Produce a score out of 100, identify gaps, and generate a prioritized fix kit with actionable solutions.

Elite performance comes from elite structure. This audit shows you where the structure is missing.

How to Run

When this skill is invoked, execute the full audit below. Read the actual project files — don't guess or assume. Every score must be evidence-based.

Output format: Write the full audit report to docs/audit-report.md with:

1. Score summary table (all 10 categories)
2. Detailed findings per category (what exists, what's missing, evidence)
3. Prioritized fix kit (ordered by impact-to-effort ratio)
4. Top 3 quick wins (things fixable in under 15 minutes)

Category 1: CLAUDE.md Quality (0-10)

CLAUDE.md is the highest-leverage file in any Claude Code project. It loads every session and shapes every response.

What to check:

• Does CLAUDE.md exist at the project root?
• Does it follow the WHAT / WHY / HOW framework?
  • WHAT: Tech stack, project structure, key files
  • WHY: Project purpose, what each part does
  • HOW: Build commands, test commands, conventions, how to verify changes
• Is it lean? (Under ~150 instructions. Claude Code's system prompt already contains ~50 instructions — bloated CLAUDE.md files cause instruction-following to degrade)
• Does it include common mistakes to avoid? (The highest-value section — only include things Claude gets wrong)
• Are critical rules emphasized with "IMPORTANT:" or "NEVER"?
• Does it avoid duplicating information available in skills or other docs?
• Are build/test/lint commands documented?
• Is there a clear git workflow defined?

Scoring guide:

• 0-2: Missing or just a project description with no actionable instructions
• 3-4: Exists but bloated, unstructured, or missing key sections
• 5-6: Covers basics but missing conventions, common mistakes, or emphasis on critical rules
• 7-8: Well-structured, lean, covers WHAT/WHY/HOW with clear conventions
• 9-10: Tight, battle-tested, every line earns its place, iterated based on real mistakes

Also check for:

• CLAUDE.local.md for personal overrides (should be in .gitignore)
• ~/.claude/CLAUDE.md for global preferences
• Subdirectory CLAUDE.md files in monorepos

Category 2: Skills & Commands (0-10)

Skills provide on-demand context that loads only when relevant. Commands are reusable prompt templates. Together they prevent re-explaining standards every session and save significant tokens.

What to check:

Skills (.claude/skills/):

• Do any project-specific skills exist?
• Does each skill have a clear SKILL.md with a descriptive name and trigger description?
• Are skills focused on a single domain? (design system, API patterns, database migrations, etc.)
• Do skills reference actual project files rather than generic advice?
• Is domain knowledge moved OUT of CLAUDE.md and INTO skills? (key for token efficiency)

Commands (.claude/commands/):

• Do any slash commands exist?
• Essential commands to look for:
  • Session start / catchup (review branch status, errors)
  • Pre-deploy check (lint, typecheck, build, test, security scan)
  • PR creation (cleanup, commit, push, create PR)
  • Planning (create implementation plan before coding)
  • Test generation (scaffold tests for existing code)

Scoring guide:

• 0-2: No skills or commands configured
• 3-4: 1-2 basic commands, no skills
• 5-6: Some commands exist but no skills, or skills exist but are generic
• 7-8: 3+ skills with clear triggers, 4+ commands covering key workflows
• 9-10: Comprehensive skill + command library tailored to the project, with supporting reference files

Category 3: Hooks Configuration (0-10)

Hooks are deterministic guardrails — unlike CLAUDE.md rules (which are advisory), hooks are guaranteed to execute. They are your safety net.

What to check:

• Read .claude/settings.json (or equivalent) for hook configuration
• Essential hooks to look for:

Scoring guide:

• 0-2: No hooks configured
• 3-4: One hook (usually auto-format)
• 5-6: Auto-format + one other hook
• 7-8: Auto-format + safety guard + notification
• 9-10: All three essential hooks plus project-specific hooks (e.g., migration file protection, test runner)

Category 4: MCP Servers (0-10)

MCP servers connect Claude Code to external tools and services. The right MCPs eliminate context-switching. Too many bloat startup time and context.

What to check:

• Run claude mcp list or check .claude/settings.json for MCP configuration
• Evaluate based on project stack:

Scoring guide:

• 0-2: No MCP servers configured
• 3-4: 1 MCP that's not critical to the workflow
• 5-6: 1-2 relevant MCPs for the stack
• 7-8: 2-3 well-chosen MCPs matching the primary workflow
• 9-10: Right MCPs for the stack, not overloaded, wildcard permissions configured for trusted servers

Important: More is NOT better. Score DOWN if there are 5+ MCPs that bloat context without clear value.

Category 5: Project Structure (0-10)

Clean project structure helps both humans and Claude navigate the codebase efficiently.

What to check:

• Scan for files over 500 lines (flag any over 300 as warnings)
• Check for clear directory organization (components, lib, utils, hooks, types separated)
• Look for barrel exports / index files where appropriate
• Check for code duplication across files
• Monorepo: packages clearly separated with their own configs
• Are there any "junk drawer" directories? (utils/ with 30 unrelated files)
• Is there a clear separation between UI, business logic, API, and configuration layers?

Scoring guide:

• 0-2: No clear structure, files scattered, large monolithic files
• 3-4: Basic structure but multiple files over 500 lines, unclear separation
• 5-6: Good directory structure but some large files or unclear boundaries
• 7-8: Clean separation, most files under 300 lines, clear naming
• 9-10: Well-organized, modular, every directory has a clear purpose, no file over 500 lines

Category 6: Security (0-10)

Security basics that should be in place before any production deployment. Score based on what is actually implemented, not what is planned.

What to check:

Authentication & Authorization:

• Are all API routes behind authentication? (check for unprotected endpoints)
• Is there role-based access control where needed?
• Are auth tokens validated on every request?

Data Protection:

• Database: Is Row Level Security (RLS) enabled? (Supabase/Postgres)
• Are environment variables used for ALL secrets? (check for hardcoded keys)
• Is .env in .gitignore?
• Does .env.example exist with placeholder values?
• Is PII excluded from server logs?

Input Validation:

• Are request bodies validated? (Zod, Joi, or equivalent)
• Is there SQL injection prevention? (ORM or parameterized queries)
• Is there XSS prevention? (output encoding, sanitization)

Headers & Configuration:

• Check for security headers: Content-Security-Policy, X-Frame-Options, X-Content-Type-Options
• Is CORS configured (not wildcard * in production)?
• Are rate limits on API routes? (especially auth, payment, and AI endpoints)

Dependencies:

• Run npm audit / pnpm audit / yarn audit and check severity
• Are there known critical vulnerabilities?

Scoring guide:

• 0-2: Major gaps — no auth on routes, no RLS, hardcoded secrets
• 3-4: Auth exists but inconsistent, secrets in env but some gaps
• 5-6: Auth on most routes, RLS enabled, env vars used, but missing validation or headers
• 7-8: Solid auth, RLS, validation, env management, basic security headers
• 9-10: Comprehensive — auth + RLS + validation + headers + rate limiting + clean audit + no PII in logs

Category 7: Testing (0-10)

Not about 100% coverage. About whether the paths that matter are tested.

What to check:

Infrastructure:

• Is a test runner configured? (Vitest, Jest, Mocha, etc.)
• Is there a test setup file with proper mocks?
• Can tests run with a single command?
• Are tests in the CI/CD pipeline?

Coverage of critical paths:

• Authentication flows (login, signup, token refresh, logout)
• Payment / billing webhooks (if applicable)
• Core API routes (the ones that handle user data)
• Input validation (do bad inputs get rejected?)
• Business logic (state machines, calculations, transformations)
• Data integrity (deduplication, idempotency)

E2E tests:

• Is Playwright / Cypress configured?
• Are there E2E tests for critical user flows?

Scoring guide:

• 0-2: No test runner or tests
• 3-4: Test runner configured, 1-5 test files, minimal coverage
• 5-6: Test infrastructure solid, critical auth and API paths tested, in CI
• 7-8: Good unit + integration coverage of critical paths, E2E for core flows
• 9-10: Comprehensive testing, E2E for all critical flows, edge cases covered, tests run in CI with coverage thresholds

How to count: List the total number of API routes and the number with tests. Below 30% coverage = score capped at 5.

Category 8: Git & CI/CD (0-10)

Version control hygiene and automated quality gates.

What to check:

Git practices:

• Is there a clear branching strategy? (feature branches from main)
• Are commits following a convention? (conventional commits: feat/, fix/, etc.)
• Is there a PR template?
• Are there branch protection rules on main?

CI/CD pipeline:

• Does a CI config exist? (.github/workflows/, etc.)
• What checks run automatically? (typecheck, lint, tests, build, security audit)
• Does deployment happen automatically on merge to main?
• Is there a staging/preview environment?

Scoring guide:

• 0-2: No CI/CD, no branch strategy
• 3-4: Basic CI with lint or build check only
• 5-6: CI runs lint + typecheck + build, manual deployment
• 7-8: CI runs full suite, auto-deploy on merge, preview environments
• 9-10: Full pipeline with branch protection, PR template, automated security audit, preview deployments, and rollback capability

Category 9: Performance & Production Readiness (0-10)

The gap between "it works" and "it's production-ready."

What to check:

Error handling:

• Global error boundary (React: error.tsx / ErrorBoundary component)
• API error responses are structured and consistent
• Errors are logged with context (not swallowed silently)
• User-facing error states exist (not blank screens)

Loading states:

• Skeleton loaders or loading indicators on data-fetching pages
• Suspense boundaries where appropriate
• No blank/flash states during navigation

Performance:

• Images optimized (next/image, srcset, lazy loading)
• No N+1 database queries
• Proper caching headers on static assets
• Bundle size reasonable
• Lazy loading for below-fold content

Production configuration:

• Environment-specific config (dev vs. production)
• Error monitoring configured (Sentry, LogRocket, etc.)
• Analytics configured (even basic)
• Favicon, meta tags, Open Graph tags

Scoring guide:

• 0-2: No error boundaries, no loading states, unoptimized images
• 3-4: Basic error handling, some loading states, no monitoring
• 5-6: Error boundaries exist, loading states on key pages, images optimized
• 7-8: Solid error handling + loading states + optimized assets + monitoring
• 9-10: Comprehensive — error monitoring, analytics, optimized bundle, proper caching, all production configs

Category 10: Cost Efficiency (0-10)

How efficiently the Claude Code setup uses tokens and context window.

What to check:

CLAUDE.md bloat:

• Count lines in CLAUDE.md. Over 200 = concern. Over 300 = problem.
• Does CLAUDE.md load large files unconditionally?
• Calculate token impact: each line ≈ 12 tokens
• Are reference docs loaded via skills (on-demand) or CLAUDE.md (every session)?

Context management:

• Is domain knowledge in skills (loads when relevant) vs. CLAUDE.md (loads always)?
• Are there conditional reading instructions? ("Read X only when working on Y")
• Are there duplicate instructions between CLAUDE.md and skills/MEMORY.md?

Workflow efficiency:

• Do specific file references use @file syntax?
• Are prompts specific enough to avoid multi-turn clarification?
• Is there a model switching strategy? (Sonnet for routine, Opus for complex)

Scoring guide:

• 0-2: CLAUDE.md over 300 lines, loads multiple large files every session, no skills
• 3-4: Moderately bloated CLAUDE.md, some redundancy, no skills for offloading
• 5-6: Reasonable CLAUDE.md size, some skills exist but knowledge isn't fully migrated
• 7-8: Lean CLAUDE.md, skills handle domain knowledge, conditional doc loading
• 9-10: Optimized — lean CLAUDE.md, comprehensive skills, conditional loading, model strategy, no redundancy

Generating the Fix Kit

After scoring all 10 categories, generate a prioritized fix kit.

Prioritization Rules

1. Sort by impact-to-effort ratio — a 5-minute hook setup that gains +8 points ranks above a half-day refactor that gains +1 point
2. Group into tiers:
   • Tier 1: Do Today (under 15 minutes each, zero/low risk)
   • Tier 2: Do This Week (30-60 minutes each, low/medium risk)
   • Tier 3: Do This Month (1+ hours, may need staging/local dev to test)
   • Tier 4: Backlog (nice-to-have, do when convenient)
3. For each fix, include:
   • What to change (specific files)
   • How to change it (code, commands, or configs — copy-pasteable when possible)
   • Risk level (None / Low / Medium / High)
   • Production impact (will this affect live users?)
   • Dependencies (needs Docker, staging environment, etc.?)

Stage-Appropriate Advice

Consider the project's maturity when prioritizing:

IMPORTANT: Always note when a fix is "best practice" vs. "critical for current stage." A solo developer with 5 users has different priorities than a team with 500 users. Don't recommend spending a day on test coverage when the developer should be shipping features.

Report Template

# Project Audit Report

**Project:** [name]
**Date:** [date]
**Overall Score:** [X]/100

## Score Summary

| Category | Score | Status | Notes |
|----------|-------|--------|-------|
| CLAUDE.md Quality | X/10 | 🟢/🟡/🔴 | [one-line summary] |
| Skills & Commands | X/10 | 🟢/🟡/🔴 | |
| Hooks Configuration | X/10 | 🟢/🟡/🔴 | |
| MCP Servers | X/10 | 🟢/🟡/🔴 | |
| Project Structure | X/10 | 🟢/🟡/🔴 | |
| Security | X/10 | 🟢/🟡/🔴 | |
| Testing | X/10 | 🟢/🟡/🔴 | |
| Git & CI/CD | X/10 | 🟢/🟡/🔴 | |
| Performance | X/10 | 🟢/🟡/🔴 | |
| Cost Efficiency | X/10 | 🟢/🟡/🔴 | |

Status: 🟢 8-10 | 🟡 5-7 | 🔴 0-4

## Detailed Findings

[Per-category breakdown with evidence]

## Fix Kit

### Tier 1: Do Today
### Tier 2: Do This Week
### Tier 3: Do This Month
### Tier 4: Backlog

## Top 3 Quick Wins

1. [Specific action] — [time estimate] — [point impact]
2. [Specific action] — [time estimate] — [point impact]
3. [Specific action] — [time estimate] — [point impact]

How to Use This Skill

Run a full audit:

Run the project-audit skill on this project. Read all relevant files and produce the full report.

Audit a specific category:

Run the project-audit skill — Security category only. Detailed findings and fixes.

Re-audit after fixes:

Run the project-audit skill again. Compare against docs/audit-report.md and show what improved.

Audit a new project:

Run the project-audit skill. Fresh project — focus on foundation setup.

Installation

1. Create the directory: .claude/skills/project-audit/
2. Save this file as SKILL.md inside that directory
3. Restart Claude Code

The skill auto-loads whenever you ask Claude to audit, review, or evaluate your project setup.