From 96e32df87bb033bc8dbde60e263d8e8b43c50c11 Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Mon, 29 Jun 2026 08:32:44 +0200 Subject: [PATCH] =?UTF-8?q?docs(claude-md):=20trim=20project=20CLAUDE.md?= =?UTF-8?q?=20to=20invariants=20(=E2=88=92662=20always-tok)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plugin's own CLAUDE.md is loaded every turn while working in this repo (measured 2,178 always-loaded tokens via `manifest`, the largest slice of the 2,745-tok project delta). Much of it was reference-grade prose that duplicates README.md, `/config-audit help`, and docs/ — verbose per-command feature lists, the full plain-language-output spec, the session-dir ASCII tree — none of which is invariant for working on the plugin. Trimmed to what is invariant: command names + one-line purpose, the agent / hook tables (model/color/tools, script/event), finding-ID format, enforced .claude/rules conventions, coding style, test command, gotchas. Detail now points to README / docs/. Also dropped two stale badge-duplicate figures that had already rotted (the README badge owns them): "18 commands" (now 21) and "1279 tests / 72 files" (now 1344) — removed rather than re-pinned so they can't go stale again. Measured: CLAUDE.md 134->102 lines, 8844->6170 B, 2,178->1,516 tok (-30%); config-audit project always-delta 2,745->2,083 tok (-24%). Full suite 1344/0; frozen v5.0.0 + SC-5 + default-output snapshots byte-stable (no scanner/snapshot reads this repo's CLAUDE.md). Docs-only — no version bump, no catalog ref change. Co-Authored-By: Claude Opus 4.8 (1M context) Claude-Session: https://claude.ai/code/session_01683eAqVecv9VZfQzL8CQ9h --- CLAUDE.md | 92 ++++++++++++++++++------------------------------------- 1 file changed, 30 insertions(+), 62 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 97054c1..a367750 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,13 +1,8 @@ # Config-Audit Plugin -Claude Code Configuration Intelligence — know if your configuration is correct, find what could improve it, fix it automatically. +Claude Code Configuration Intelligence — know if your config is correct, find what could improve it, fix it automatically. Three pillars: **Health** (deterministic scanners), **Opportunities** (context-aware recommendations), **Action** (auto-fix with backup/rollback). -## What this plugin does - -Analyzes and optimizes Claude Code configuration across three pillars: -- **Health** — Deterministic scanners verify correctness, consistency, and completeness -- **Opportunities** — Context-aware recommendations for features that could benefit your project -- **Action** — Auto-fix with backup/rollback +Per-command flags, patterns, and feature lists live in `README.md` and `/config-audit help`. This file carries what's invariant for working on the plugin. ## Commands @@ -15,15 +10,15 @@ Analyzes and optimizes Claude Code configuration across three pillars: | Command | Description | |---------|-------------| -| `/config-audit` | Full audit with auto-scope detection (no setup needed) | -| `/config-audit posture` | Quick health scorecard (A-F grades, 10 quality areas incl. Token Efficiency, Plugin Hygiene) | -| `/config-audit tokens` | prompt-cache-aware token hotspots (8 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget, MCP tool-schema deferral, stale plugin-cache disk-cleanup), each ranked hotspot tagged with its load pattern (always / on-demand / external) — **cache-aware** (stale `~/.claude/plugins/cache` versions excluded by default; only each plugin's active version counts; `--no-exclude-cache` for the full walk), optional `--accurate-tokens` API calibration, `--with-telemetry-recipe` cache-hit recipe pointer | -| `/config-audit manifest` | Ranked table of every token source (CLAUDE.md, rules, agents, skills, output styles, MCP, hooks) sorted by estimated tokens, each tagged with its load pattern (always-loaded / on-demand / external) + an always-loaded subtotal ("tokens that enter context every turn") | -| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact (incl. a conditional `disableBundledSkills` lever when the active skill listing is over budget — remediation companion to SKL `CA-SKL-002`) | -| `/config-audit optimize` | Optimization lens (mechanism-fit) — config that works but fits a better mechanism: procedure→skill (CA-OPT-001, deterministic), lifecycle→hook / unscoped path→rule / "never"→permission (prose-judgment via opus `optimization-lens-agent`). Hybrid motor; every finding cites a best-practices-register rule. Agent-driven, **not byte-stable** | +| `/config-audit` | Full audit with auto-scope detection | +| `/config-audit posture` | A-F health scorecard (10 quality areas) | +| `/config-audit tokens` | Prompt-cache-aware token hotspots, each tagged with its load pattern; cache-aware | +| `/config-audit manifest` | Ranked table of every token source + always-loaded subtotal | +| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact | +| `/config-audit optimize` | Mechanism-fit lens (procedure→skill, lifecycle→hook, path→rule, never→permission). Agent-driven, **not byte-stable** | | `/config-audit fix` | Auto-fix deterministic issues with backup + verification | | `/config-audit rollback` | Restore configuration from backup | -| `/config-audit plan` | Create action plan from audit findings | +| `/config-audit plan` | Create action plan from findings | | `/config-audit implement` | Execute plan with backups + auto-verify | | `/config-audit help` | Show all commands | @@ -33,9 +28,9 @@ Analyzes and optimizes Claude Code configuration across three pillars: |---------|-------------| | `/config-audit drift` | Compare current config against saved baseline | | `/config-audit plugin-health` | Audit plugin structure, frontmatter, cross-plugin coherence | -| `/config-audit whats-active` | Read-only inventory of plugins, skills, MCP, hooks, CLAUDE.md active for a repo (with token estimates) | -| `/config-audit knowledge-refresh` | Keep the best-practices register fresh — deterministic stale check (sources older than ~90d) + web candidate poll (CC changelog + Anthropic blog); **human-approved writes only** (Verifiseringsplikt). The "living" half of the knowledge base. Web/judgment-driven, **not byte-stable** | -| `/config-audit campaign` | Machine-wide audit campaign — durable ledger ABOVE sessions: per-repo lifecycle (pending→audited→planned→implemented) + machine-wide roll-up by severity + **machine-wide always-loaded token bill** (`refresh-tokens` live cross-repo sweep — shared global layer counted once + per-repo deltas) + cross-repo prioritized backlog + plan **export** (drop a planned repo's plan into its own `docs/`), resumable across sessions. Read-only report (campaign-cli) + **human-approved** writes via deterministic write/export CLIs. THIN: tracks+routes state, reuses existing implement/rollback for execution. Judgment-driven, **not byte-stable** | +| `/config-audit whats-active` | Read-only inventory of active plugins/skills/MCP/hooks/CLAUDE.md (with token estimates) | +| `/config-audit knowledge-refresh` | Refresh the best-practices register (stale check + web poll). Human-approved writes; **not byte-stable** | +| `/config-audit campaign` | Machine-wide audit ledger + token bill across repos. Human-approved writes; **not byte-stable** | | `/config-audit discover` | Run discovery phase only | | `/config-audit analyze` | Run analysis phase only | | `/config-audit interview` | Gather user preferences (opt-in) | @@ -51,68 +46,43 @@ Analyzes and optimizes Claude Code configuration across three pillars: | planner-agent | Create action plan | opus | yellow | Read, Glob, Write | | implementer-agent | Execute changes | sonnet | magenta | Read, Write, Edit, Bash, Glob | | verifier-agent | Verify results | sonnet | purple | Read, Glob, Grep | -| feature-gap-agent | Context-aware feature recommendations | opus | green | Read, Glob, Grep, Write | -| optimization-lens-agent | Mechanism-fit precision gate (prose-judgment lens cases) | opus | orange | Read, Glob, Grep, Write | +| feature-gap-agent | Feature recommendations | opus | green | Read, Glob, Grep, Write | +| optimization-lens-agent | Mechanism-fit precision gate | opus | orange | Read, Glob, Grep, Write | ## Hooks | Event | Script | Purpose | |-------|--------|---------| -| PreToolUse | `auto-backup-config.mjs` | Auto-backup config files before Edit/Write | -| PostToolUse | `post-edit-verify.mjs` | Verify config files after Edit/Write, block on new critical/high | -| SessionStart | `session-start.mjs` | Checks for active (unfinished) sessions | -| Stop | `stop-session-reminder.mjs` | Reminds about current session phase | +| PreToolUse | `auto-backup-config.mjs` | Backup config files before Edit/Write | +| PostToolUse | `post-edit-verify.mjs` | Verify after Edit/Write, block on new critical/high | +| SessionStart | `session-start.mjs` | Check for active (unfinished) sessions | +| Stop | `stop-session-reminder.mjs` | Remind about current session phase | ## Reference docs (read on demand) -- **Scanner inventory, lib modules, action engines, knowledge base, per-scanner/per-block implementation notes:** `docs/scanner-internals.md` -- **Plain-language output (v5.1.0), humanizer vocabularies, output modes:** `docs/humanizer.md` +- `docs/scanner-internals.md` — scanner inventory, lib modules, action engines, knowledge base, per-scanner/per-block implementation notes (design rationale, primary-source verification, byte-stability lessons) +- `docs/humanizer.md` — plain-language output (v5.1.0), humanizer vocabularies, output modes -## Plain-Language Output (v5.1.0) — summary +## Plain-Language Output (v5.1.0) -Default output of all 18 commands routes through `humanizeEnvelope` from `lib/humanizer.mjs`. Findings get three decorated fields: - -- `userImpactCategory` — Configuration mistake / Conflict / Wasted tokens / Dead config / Missed opportunity -- `userActionLanguage` — Fix this now / Fix soon / Fix when convenient / Optional cleanup / FYI (derived from severity) -- `relevanceContext` — `affects-everyone` (default) / `affects-this-machine-only` (`*.local.*` files) / `test-fixture-no-impact` - -`--raw` bypasses the humanizer for byte-stable v5.0.0 output. `--json` is also byte-stable. Full detail and Wave 5 lessons: `docs/humanizer.md`. +Default output of all commands routes through `humanizeEnvelope` (`lib/humanizer.mjs`), decorating each finding with `userImpactCategory`, `userActionLanguage`, and `relevanceContext`. `--raw` and `--json` bypass the humanizer for byte-stable v5.0.0 output. Full detail: `docs/humanizer.md`. ## Suppressions -Create `.config-audit-ignore` at project root to suppress known findings: -``` -CA-SET-003 # Exact ID -CA-GAP-* # Glob pattern (all GAP findings) -``` -Suppressed findings tracked in envelope's `suppressed_findings` for audit trail. Disable with `--no-suppress`. +Create `.config-audit-ignore` at project root — one exact ID or glob per line (`CA-SET-003`, `CA-GAP-*`). Suppressed findings are tracked in the envelope's `suppressed_findings` for audit trail. Disable with `--no-suppress`. ## Architecture -### Workflow -``` -/config-audit → discover + analyze (auto) → plan → implement → verify -``` -Default: auto-detects scope from git context. Override with `/config-audit full|repo|home|current`. Delta mode: `--delta` (incremental). +Workflow: `/config-audit → discover + analyze (auto) → plan → implement → verify`. Auto-detects scope from git context; override with `full|repo|home|current`; `--delta` for incremental. Session state lives under `~/.claude/config-audit/sessions/{id}/` (scope.yaml, discovery.json, state.yaml, findings/, analysis-report.md, action-plan.md, backups/, implementation-log.md). -### Session Directory -``` -~/.claude/config-audit/sessions/{session-id}/ -├── scope.yaml, discovery.json, state.yaml -├── findings/, analysis-report.md, action-plan.md -├── backups/, implementation-log.md -└── interview.md (if interview run) -``` - -### Finding ID Format -`CA-{SCANNER}-{NNN}` — e.g. `CA-CML-001`, `CA-SET-003`, `CA-HKV-002`, `CA-RUL-005`, `CA-TOK-005`, `CA-CPS-001`, `CA-DIS-001`, `CA-COL-001`, `CA-SKL-001`, `CA-OST-001`, `CA-OPT-001`, `CA-AGT-001` +Finding ID format: `CA-{SCANNER}-{NNN}` — e.g. `CA-CML-001`, `CA-SET-003`, `CA-HKV-002`, `CA-RUL-005`, `CA-TOK-005`, `CA-CPS-001`, `CA-SKL-001`, `CA-OST-001`, `CA-OPT-001`, `CA-AGT-001`. ## Conventions -Enforced project conventions live in `.claude/rules/` (auto-loaded as project instructions): - -- `ux-rules.md` — output/narration/formatting rules for all commands (never dump raw JSON, narrate before each step, space-separated command suggestions) +Enforced conventions live in `.claude/rules/` (auto-loaded as project instructions): +- `ux-rules.md` — output/narration/formatting for all commands (never dump raw JSON, narrate before each step, space-separated command suggestions) - `command-development.md` — required command frontmatter + `plugin:action` naming +- `agent-development.md` — agent frontmatter + "when to use" conventions - `state-management.md` — update `state.yaml` after every workflow phase Coding style: scanners are zero-dependency Node ESM; new findings use the `CA-{SCANNER}-{NNN}` ID format; byte-stable CLIs are verified against frozen `tests/snapshots/v5.0.0/` baselines. @@ -123,12 +93,10 @@ Coding style: scanners are zero-dependency Node ESM; new findings use the `CA-{S node --test 'tests/**/*.test.mjs' ``` -1279 tests across 72 test files (23 lib + 39 scanner + 1 hook + 1 agent + 3 commands + 1 knowledge + 4 top-level). Test fixtures in `tests/fixtures/`. Top-level humanizer tests: `json-backcompat.test.mjs`, `raw-backcompat.test.mjs`, `scenario-read-test.test.mjs`, `snapshot-default-output.test.mjs`. - -Per-scanner and per-build-block implementation notes (design rationale, primary-source verification, byte-stability lessons) live in `docs/scanner-internals.md` → **Implementation notes**. +Test fixtures in `tests/fixtures/`. Per-scanner and per-build-block implementation notes (design rationale, primary-source verification, byte-stability lessons) live in `docs/scanner-internals.md` → **Implementation notes**. ## Gotchas - Session directories accumulate — use `/config-audit cleanup` to manage -- Scanners run on Node.js >= 18 (uses node:test, node:fs/promises) +- Scanners run on Node.js ≥ 18 (uses node:test, node:fs/promises) - Plugin CLAUDE.md files in node_modules should be excluded via scope