{"slug": "claude-code-adoption-audit-score-your-usage-on-the-5-step-ai-adoption-ladder-to", "title": "Claude Code /adoption-audit — score your usage on the 5-step AI-adoption ladder (evidence-first, local, read-only). Save to ~/.claude/commands/adoption-audit.md", "summary": "A developer created an adoption-audit command for Claude Code that scores usage against Boris Cherny's 5-step AI-adoption ladder. The tool runs locally and read-only, analyzing session transcripts under ~/.claude/projects to produce an evidence-first report with a bottleneck and a 2-week improvement plan.", "body_md": "| description | Audit your Claude Code usage against the 5-step AI-adoption ladder and produce a scored, evidence-first report (+ optional artifact). |\n|---|---|\n| argument-hint | [extra exclude-regex for repos to ignore] |\n| allowed-tools | Bash, Read, Write, Edit, Artifact, Agent |\n\nAudit **my own** Claude Code usage against Boris Cherny's 5-step AI-adoption ladder,\nplace me on a step from measured evidence, name my #1 bottleneck, and give a\nprioritized 2-week plan to reach the next step. Be rigorous and evidence-first — no\nflattery. State the number you found for every dimension. If a dimension can't be\nmeasured, say so and name what to enable.\n\nInstall:save this file as`~/.claude/commands/adoption-audit.md`\n\n(user-global, works in any project) or`.claude/commands/adoption-audit.md`\n\n(per-project). Run`/adoption-audit`\n\n.Privacy:everything below is local and read-only — it reads your session transcripts under`~/.claude/projects`\n\n. Nothing leaves your machine unlessyouchoose to publish an artifact.Method:aggregate with shell tools; do NOT read every transcript into context. For a huge project, spawn a subagent to extract counts, then merge.\n\n`EXCLUDE`\n\n— regex of project/folder names that are**not your work**(repos you cloned to study, templates, vendored code). Anything provided as`$ARGUMENTS`\n\nis added to this. Default: none.`ARTIFACT_URL`\n\n— leave empty on first run. If you publish the optional artifact, paste its URL back here so future runs**update it in place** instead of minting a new one.\n\n```\nEXCLUDE_REGEX=\"\"     # e.g. \"some-template|vendored-repo\"  ($ARGUMENTS is appended)\nARTIFACT_URL=\"\"      # e.g. https://claude.ai/code/artifact/xxxxxxxx\n```\n\n**0 Gated**— 0 agents / chat only, no approved tooling or infra.** 1 Assisted**— ~1 / one supervised session at a time; you review almost every change; work is synchronous.** 2 Parallel**— ~10 / 5–10 concurrent agents on their own worktrees; auto mode always on; Claude self-verifies (test/build/lint) before you look; automated code + security review; you review final diffs.**3 Supervised autonomy**— ~100 / Claude writes nearly all code; fan-out via subagents, /loop, /batch, /goal, routines, workflows; Claude kicks off Claude; standards encoded in CLAUDE.md + Skills; cost managed via OTel/analytics.**4 AI-native**— ~1000+ / loop closed, most agents kicked off by Claude; Agent SDK schedules fleets; you monitor by exception.\n\n```\nP=~/.claude/projects\nEX=\"${EXCLUDE_REGEX:-}\"; [ -n \"$1\" ] && EX=\"${EX:+$EX|}$1\"   # merge $ARGUMENTS into excludes\nexf(){ if [ -n \"$EX\" ]; then grep -vE \"$EX\"; else cat; fi; }\n\n# ---- Inventory ----\necho \"top-level sessions:\"; find $P -mindepth 2 -maxdepth 2 -name '*.jsonl' | wc -l\necho \"workflow runs:\";      find $P -type d -name 'wf_*' | wc -l\necho \"subagent transcripts:\"; find $P -path '*/subagents/*' -name 'agent-*.jsonl' | wc -l\n\n# ---- Date range + sessions-per-ISO-week trend (is usage growing?) ----\nfind $P -mindepth 2 -maxdepth 2 -name '*.jsonl' | while read f; do\n  jq -rc '.timestamp//empty' \"$f\" 2>/dev/null | sort | head -1; done | cut -c1-10 | \\\n  while read d; do date -j -f '%Y-%m-%d' \"$d\" '+%Y-W%V' 2>/dev/null || date -d \"$d\" '+%Y-W%V' 2>/dev/null; done | sort | uniq -c\n\n# ---- Tool-use frequency: top-level = your direct work; mindepth 3 = subagents/workflows ----\nfind $P -mindepth 2 -maxdepth 2 -name '*.jsonl' -print0 | xargs -0 cat 2>/dev/null | \\\n  jq -rc 'select(.type==\"assistant\")|.message.content[]?|select(.type==\"tool_use\")|.name' 2>/dev/null | sort | uniq -c | sort -rn\nfind $P -mindepth 3 -name '*.jsonl' -print0 | xargs -0 cat 2>/dev/null | \\\n  jq -rc 'select(.type==\"assistant\")|.message.content[]?|select(.type==\"tool_use\")|.name' 2>/dev/null | sort | uniq -c | sort -rn | head\n\n# ---- Permission posture: auto mode always on? ----\nfind $P -mindepth 2 -maxdepth 2 -name '*.jsonl' -print0 | xargs -0 cat 2>/dev/null | \\\n  jq -rc '..|.permissionMode?//empty' 2>/dev/null | sort | uniq -c | sort -rn\n\n# ---- Self-verification: does Claude run tests/build/lint/typecheck itself? ----\nfind $P -name '*.jsonl' -print0 | xargs -0 cat 2>/dev/null | \\\n  jq -rc 'select(.type==\"assistant\")|.message.content[]?|select(.type==\"tool_use\" and .name==\"Bash\")|.input.command' 2>/dev/null | \\\n  grep -oiE '\\b(pytest|npm run build|npm test|yarn test|vitest|jest|eslint|ruff|mypy|tsc|go test|cargo test|black|prettier|playwright test|typecheck)\\b' | sort | uniq -c | sort -rn\n\n# ---- Concurrency: max overlapping top-level sessions (wall-clock) ----\nfind $P -mindepth 2 -maxdepth 2 -name '*.jsonl' | while read f; do\n  ts=$(jq -rc '.timestamp//empty' \"$f\" 2>/dev/null | sort); s=$(echo \"$ts\"|head -1); e=$(echo \"$ts\"|tail -1)\n  [ -n \"$s\" ] && echo \"$s|$e\"; done | awk -F'|' '{print $1\" S\";print $2\" E\"}' | sort | \\\n  awk '{if($2==\"S\"){c++;if(c>m)m=c}else c--}END{print \"max concurrent sessions:\",m}'\n# Peak concurrent subagents in the busiest session (true parallel fan-out):\nBIG=$(find $P -path '*/subagents/*' -name 'agent-*.jsonl' | awk -F/ '{print $1\"/\"$2\"/\"$3\"/\"$4\"/\"$5\"/\"$6\"/\"$7}' | sort | uniq -c | sort -rn | head -1 | awk '{print $2}')\n[ -n \"$BIG\" ] && find \"$BIG\" -name 'agent-*.jsonl' | while read f; do ts=$(jq -rc '.timestamp//empty' \"$f\" 2>/dev/null|sort); s=$(echo \"$ts\"|head -1); e=$(echo \"$ts\"|tail -1); [ -n \"$s\" ]&&echo \"$s|$e\"; done | \\\n  awk -F'|' '{print $1\" S\";print $2\" E\"}' | sort | awk '{if($2==\"S\"){c++;if(c>m)m=c}else c--}END{print \"peak concurrent subagents:\",m}'\n\n# ---- Orchestration / proactivity / automated review — ACTUAL tool_use only ----\n# (WARNING: a plain grep for \"code-review\"/\"worktree\" is polluted by system-prompt text;\n#  count real invocations by matching tool_use .name.)\nfind $P -name '*.jsonl' -print0 | xargs -0 cat 2>/dev/null | \\\n  jq -rc 'select(.type==\"assistant\")|.message.content[]?|select(.type==\"tool_use\")|.name' 2>/dev/null | \\\n  grep -iE 'Workflow|^Agent$|Task|Monitor|SendMessage|Worktree|review|Cron|Remote|Push|Schedule' | sort | uniq -c | sort -rn\n\n# ---- Context engineering: your CLAUDE.md / skills / agents / MCP (excludes non-your-work) ----\nCODE_ROOT=\"${CODE_ROOT:-$HOME/projects}\"   # set to where your repos live\necho \"your skills:\";   find \"$CODE_ROOT\" ~/.claude -maxdepth 6 -path '*/skills/*/SKILL.md' 2>/dev/null | exf | wc -l\necho \"your CLAUDE.md:\"; find \"$CODE_ROOT\" -maxdepth 4 \\( -iname 'CLAUDE.md' -o -iname 'AGENTS.md' \\) 2>/dev/null | exf | wc -l\necho \"your subagents:\"; find \"$CODE_ROOT\" -maxdepth 5 -path '*/.claude/agents/*.md' 2>/dev/null | exf | wc -l\necho \"hooks configured:\"; find \"$CODE_ROOT\" ~/.claude -maxdepth 4 -name 'settings*.json' 2>/dev/null | exf | xargs grep -l '\"hooks\"' 2>/dev/null | wc -l\necho \"settings signals:\"; grep -E 'defaultMode|effortLevel|\"model\"|OTEL|ENABLE_TELEMETRY' ~/.claude/settings.json 2>/dev/null\n```\n\nFor each, cite the number found and mark whether it **leads** or **lags** your overall step:\n**Concurrency** (typical & max overlap; peak parallel subagents) ·\n**Permission posture** (auto vs default rate) ·\n**Self-verification** (test/build/lint runs; any enforcing hook/verify skill?) ·\n**Isolation** (worktrees + subagent fan-out) ·\n**Orchestration** (Workflow / Agent / Task / /loop / /batch / routines) ·\n**Automated review** (code-review + security-review actually invoked? hooks/CI?) ·\n**Context engineering** (CLAUDE.md, Skills, agents, memory, MCP servers wired in) ·\n**Proactivity** (does Claude kick off Claude — cron/routines/remote?) ·\n**Cost & observability** (OTel export, analytics, deliberate model/effort) ·\n**Review depth** (read every diff vs final diffs vs monitor by exception).\n\n**Verdict**(one line): \"You are at Step X (confidence …), leaning X+1 on .\"** Scorecard table**: dimension | measured signal | step 0–4.** Evidence appendix**: brief, with counts/paths.**#1 bottleneck** keeping you at your step (match the framework's bottleneck for that step).**Climb to Step X+1**— 3–5 highest-leverage, specific actions (exact command/config/skill + why it moves the needle). Relevant docs: auto mode[https://code.claude.com/docs/en/auto-mode-config](https://code.claude.com/docs/en/auto-mode-config)· code review[https://code.claude.com/docs/en/code-review](https://code.claude.com/docs/en/code-review)· security review[https://github.com/anthropics/claude-code-security-review](https://github.com/anthropics/claude-code-security-review)· remote control[https://code.claude.com/docs/en/remote-control](https://code.claude.com/docs/en/remote-control)· workflows[https://code.claude.com/docs/en/workflows](https://code.claude.com/docs/en/workflows)· sandboxing[https://code.claude.com/docs/en/sandboxing](https://code.claude.com/docs/en/sandboxing)· costs[https://code.claude.com/docs/en/costs](https://code.claude.com/docs/en/costs)\n\nPrint the report as markdown (the primary deliverable — works everywhere, incl. headless).\n\n**Optional artifact:** if you want a visual dashboard, build a self-contained HTML page and\npublish it with the `Artifact`\n\ntool. Suggested treatment: a compact \"instrument panel\" — a\n5-step ascent-ladder hero marking your current step, a metrics readout strip, a scorecard with\n0–4 segmented meters colored by severity (lag/dev/lead), and a sessions-per-week trend. Design\nboth light and dark themes; use monospace for data/labels. If `ARTIFACT_URL`\n\nis set above, pass\nit as the `url`\n\nparameter to update in place; otherwise publish fresh, then paste the returned\nURL into `ARTIFACT_URL`\n\nso next time updates the same page.", "url": "https://wpnews.pro/news/claude-code-adoption-audit-score-your-usage-on-the-5-step-ai-adoption-ladder-to", "canonical_source": "https://gist.github.com/batou9150/5df83474911b946a451be0074fb766cd", "published_at": "2026-07-18 09:36:16+00:00", "updated_at": "2026-07-23 08:27:54.493502+00:00", "lang": "en", "topics": ["developer-tools", "ai-agents", "ai-tools", "ai-infrastructure"], "entities": ["Claude Code", "Boris Cherny"], "alternates": {"html": "https://wpnews.pro/news/claude-code-adoption-audit-score-your-usage-on-the-5-step-ai-adoption-ladder-to", "markdown": "https://wpnews.pro/news/claude-code-adoption-audit-score-your-usage-on-the-5-step-ai-adoption-ladder-to.md", "text": "https://wpnews.pro/news/claude-code-adoption-audit-score-your-usage-on-the-5-step-ai-adoption-ladder-to.txt", "jsonld": "https://wpnews.pro/news/claude-code-adoption-audit-score-your-usage-on-the-5-step-ai-adoption-ladder-to.jsonld"}}