fix(tokens): refresh stale "Opus 4.7" framing to model-neutral + Opus 4.8 anchor
Fase 4 token-opt, Item 1 of gap-review NEXT STEP #2. The prompt-cache pattern corpus + TOK scanner were frozen at an "Opus 4.7" framing after CC shipped Opus 4.8 (default, 2.1.154) and Fable 5 (2.1.170). Model-era facts re-verified against the official changelog cache before editing. The patterns are properties of prompt-caching, not of any model, so mechanic text is now model-neutral with a single "current default: Opus 4.8" anchor — preventing a re-freeze at the next model bump. - rename knowledge/opus-4.7-patterns.md -> prompt-cache-patterns.md (git mv, history preserved); 6 reference sites updated - TOK scanner: line-318 finding text (human-facing) made model-neutral; header + cache-prefix-scanner + CLI comments refreshed - configuration-best-practices.md body + footnote 4.7 -> 4.8 - human-facing docs: commands/{tokens,help,manifest}.md, project CLAUDE.md, README, docs/scanner-internals.md - gap-matrix row marked DONE; future Items 2/3 retargeted to new filename Failing-test-first (Iron Law): +2 knowledge staleness guards (era-anchor + no-refreeze) +1 scanner assertion (no stale model anchor in finding text). Suite 853 -> 856 green; zero snapshot drift; self-audit A(97) PASS. CHANGELOG / v5 plan / ratified gap-plan keep historical opus-4.7-patterns refs (correct record of past state). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8
This commit is contained in:
parent
b3c572ad46
commit
8376dab83f
15 changed files with 66 additions and 40 deletions
|
|
@ -17,7 +17,7 @@ Analyzes and optimizes Claude Code configuration across three pillars:
|
|||
|---------|-------------|
|
||||
| `/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` | Opus-4.7-aware token hotspots (6 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget) — optional `--accurate-tokens` API calibration, `--with-telemetry-recipe` cache-hit recipe pointer |
|
||||
| `/config-audit tokens` | prompt-cache-aware token hotspots (6 patterns: cache-breaking, redundant perms, deep imports, oversized cascade, bloated SKILL.md desc, MCP tool-schema budget) — optional `--accurate-tokens` API calibration, `--with-telemetry-recipe` cache-hit recipe pointer |
|
||||
| `/config-audit manifest` | Ranked table of every system-prompt token source (CLAUDE.md, plugins, skills, MCP, hooks) sorted by estimated tokens |
|
||||
| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact |
|
||||
| `/config-audit fix` | Auto-fix deterministic issues with backup + verification |
|
||||
|
|
|
|||
12
README.md
12
README.md
|
|
@ -15,7 +15,7 @@
|
|||
|
||||
|
||||
|
||||
A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 12 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, an Opus-4.7-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, and cross-plugin collision detection. Zero external dependencies.
|
||||
A Claude Code plugin that checks configuration health, suggests context-aware improvements, and auto-fixes issues — `CLAUDE.md`, `settings.json`, hooks, rules, MCP servers, `@imports`, and plugins. 12 deterministic scanners across 10 quality areas, context-aware feature recommendations, auto-fix with backup/rollback, a prompt-cache-aware Token Hotspots scanner with optional API-calibrated `--accurate-tokens` mode, plus cache-prefix stability, dead-tool, and cross-plugin collision detection. Zero external dependencies.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -104,7 +104,7 @@ Claude Code reads instructions from at least 7 different file types across multi
|
|||
|
||||
This plugin provides three layers of configuration intelligence:
|
||||
|
||||
- **Health** — 12 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, Opus-4.7-era token waste, cache-prefix instability, dead tool grants, and cross-plugin skill collisions
|
||||
- **Health** — 12 deterministic scanners verify correctness across every configuration file, catching broken imports, deprecated settings, conflicting rules, format errors, permission contradictions, prompt-cache token waste, cache-prefix instability, dead tool grants, and cross-plugin skill collisions
|
||||
- **Opportunities** — context-aware recommendations for Claude Code features that could benefit your specific project, backed by Anthropic's official guidance
|
||||
- **Action** — auto-fix with mandatory backups, syntax validation, rollback support, and a human-in-the-loop workflow for anything non-trivial
|
||||
|
||||
|
|
@ -303,7 +303,7 @@ Your team configuration changes over time. Track it:
|
|||
|---------|-------------|
|
||||
| `/config-audit` | Full audit with auto-scope detection (no setup needed) |
|
||||
| `/config-audit posture` | Quick health scorecard: A-F grades across 10 quality areas (incl. Token Efficiency, Plugin Hygiene) |
|
||||
| `/config-audit tokens` | Opus-4.7-aware token hotspots — ranked by estimated waste; 6 patterns + optional `--accurate-tokens` API calibration |
|
||||
| `/config-audit tokens` | prompt-cache-aware token hotspots — ranked by estimated waste; 6 patterns + optional `--accurate-tokens` API calibration |
|
||||
| `/config-audit manifest` | Ranked table of every system-prompt token source (CLAUDE.md, plugins, skills, MCP, hooks) sorted by estimated tokens |
|
||||
| `/config-audit feature-gap` | Context-aware feature recommendations grouped by impact |
|
||||
| `/config-audit fix` | Auto-fix deterministic issues with backup + verification |
|
||||
|
|
@ -333,7 +333,7 @@ By default, `/config-audit` auto-detects scope from your git context. Override w
|
|||
|
||||
## Deterministic Scanners
|
||||
|
||||
12 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, Opus-4.7-aware token-cost analysis, cache-prefix stability, dead-tool detection, and cross-plugin skill collisions. Plus a standalone plugin-health scanner. Zero external dependencies.
|
||||
12 Node.js scanners that perform structural analysis an LLM cannot reliably do: schema validation, circular reference detection, import resolution, conflict detection across scopes, prompt-cache-aware token-cost analysis, cache-prefix stability, dead-tool detection, and cross-plugin skill collisions. Plus a standalone plugin-health scanner. Zero external dependencies.
|
||||
|
||||
**Why deterministic?** LLMs are powerful at understanding intent and context. But they cannot reliably validate JSON schemas, detect circular `@import` chains, or catch that your global `settings.json` contradicts your project-level one. These scanners fill that gap — fast, repeatable, and zero false positives on structural issues.
|
||||
|
||||
|
|
@ -523,12 +523,12 @@ Reference documents that inform the feature-gap agent and context-aware recommen
|
|||
| File | Content |
|
||||
|------|---------|
|
||||
| `claude-code-capabilities.md` | Feature register: 18 config surfaces, Anthropic guidance, relevance table |
|
||||
| `configuration-best-practices.md` | Per-layer best practices (Opus 4.7 cache-stability guidance) |
|
||||
| `configuration-best-practices.md` | Per-layer best practices (cache-stability guidance) |
|
||||
| `anti-patterns.md` | Common mistakes mapped to scanner IDs |
|
||||
| `hook-events-reference.md` | All 26 hook events with details |
|
||||
| `feature-evolution.md` | Feature timeline for staleness detection |
|
||||
| `gap-closure-templates.md` | Config-specific templates for closing gaps |
|
||||
| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner |
|
||||
| `prompt-cache-patterns.md` | Token-cost dynamics (prompt-cache patterns) — patterns powering the TOK scanner |
|
||||
| `cache-telemetry-recipe.md` | `jq` recipe for verifying prompt-cache hit rate from session transcripts |
|
||||
|
||||
---
|
||||
|
|
|
|||
|
|
@ -32,7 +32,7 @@ if echo "$ARGUMENTS" | grep -q -- "--raw"; then RAW_FLAG="--raw"; fi
|
|||
|---------|-------------|
|
||||
| `/config-audit` | Full audit with auto-scope detection |
|
||||
| `/config-audit posture` | Quick scorecard with A-F grades per area (10 areas) |
|
||||
| `/config-audit tokens` | Opus-4.7 token hotspots; optional `--accurate-tokens` API calibration |
|
||||
| `/config-audit tokens` | prompt-cache token hotspots; optional `--accurate-tokens` API calibration |
|
||||
| `/config-audit manifest` | Ranked table of every system-prompt token source |
|
||||
| `/config-audit feature-gap` | Deep analysis of features you're not using |
|
||||
| `/config-audit fix` | Auto-fix deterministic issues; a copy of every changed file is saved first so you can roll back with one command |
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@ If `sources.length > 20`, follow the table with: _"Showing top 20 of {N} sources
|
|||
|
||||
```markdown
|
||||
**Next steps:**
|
||||
- `/config-audit tokens` — Opus-4.7 token-hotspot patterns (cache-breaking, redundant perms, deep imports, MCP budget)
|
||||
- `/config-audit tokens` — prompt-cache token-hotspot patterns (cache-breaking, redundant perms, deep imports, MCP budget)
|
||||
- `/config-audit whats-active` — same data grouped by category, with disable suggestions
|
||||
- `/config-audit feature-gap` — what *could* improve here, grouped by impact
|
||||
```
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
---
|
||||
name: config-audit:tokens
|
||||
description: Show ranked token hotspots and Opus 4.7 pattern findings — what's costing the most per turn and how to reduce it
|
||||
description: Show ranked token hotspots and prompt-cache pattern findings — what's costing the most per turn and how to reduce it
|
||||
argument-hint: "[path] [--global]"
|
||||
allowed-tools: Read, Bash
|
||||
model: sonnet
|
||||
|
|
@ -8,7 +8,7 @@ model: sonnet
|
|||
|
||||
# Config-Audit: Token Hotspots
|
||||
|
||||
Show the configuration sources that contribute the most tokens per turn, ranked by estimated tokens, with Opus 4.7-specific recommendations for reducing prompt-cache misses, schema bloat, and deep import chains.
|
||||
Show the configuration sources that contribute the most tokens per turn, ranked by estimated tokens, with prompt-cache-aware recommendations for reducing cache misses, schema bloat, and deep import chains.
|
||||
|
||||
Complementary to `/config-audit whats-active`:
|
||||
- **`whats-active`** = inventory view (what loads).
|
||||
|
|
@ -63,7 +63,7 @@ Use the Read tool on `$TMPFILE`. Extract:
|
|||
|
||||
- `total_estimated_tokens` — top-line number
|
||||
- `hotspots[]` — top 10 ranked sources
|
||||
- `findings[]` — Opus 4.7 pattern findings (CA-TOK-001..003); each finding in default mode carries humanizer fields (`userImpactCategory`, `userActionLanguage`, `relevanceContext`) alongside the v5.0.0 fields
|
||||
- `findings[]` — prompt-cache pattern findings (CA-TOK-001..003); each finding in default mode carries humanizer fields (`userImpactCategory`, `userActionLanguage`, `relevanceContext`) alongside the v5.0.0 fields
|
||||
- `counts` — severity breakdown
|
||||
|
||||
Render as markdown. Group findings by `userImpactCategory` (e.g., "Wasted tokens" vs "Configuration mistake") rather than re-deriving severity prose; lead each line with `userActionLanguage` ("Fix this now", "Fix soon", "Optional cleanup", etc.) so the urgency phrasing stays consistent with the rest of the toolchain. The humanizer already replaced jargon-heavy `title`/`description`/`recommendation` strings with plain-language equivalents — render them verbatim.
|
||||
|
|
@ -111,7 +111,7 @@ rm -f "$TMPFILE"
|
|||
- **`/config-audit whats-active`** — full inventory of what loads (plugins, skills, MCP, hooks)
|
||||
- **`/config-audit posture`** — overall health scorecard (Token Efficiency is the 8th area)
|
||||
- **`/config-audit fix`** — auto-fix deterministic issues (where applicable)
|
||||
- See `knowledge/opus-4.7-patterns.md` for the full pattern catalogue (CA-TOK-001 … 003)
|
||||
- See `knowledge/prompt-cache-patterns.md` for the full pattern catalogue (CA-TOK-001 … 003)
|
||||
- **Verify cache hit rate after a fix:** rerun with `--with-telemetry-recipe` to surface the path to `knowledge/cache-telemetry-recipe.md` — a copy-paste `jq` recipe that reads cache hit rate from your session transcripts. Opt-in. The TOK scanner is structural; this recipe is the runtime escape hatch.
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -164,9 +164,9 @@ Mest actionable nye funn:
|
|||
| surface | cc change | versions | verdict | action | target file | priority | effort |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| token management | `disableBundledSkills` flagges «unknown» + er uutnyttet token-lever | 2.1.169 | now-wrong | fix-false-positive | scanners/settings-validator.mjs | H | S |
|
||||
| token management | `disableBundledSkills` kan ANBEFALES (skjuler bundled-skill-desc fra system-prompt) | 2.1.169 | missing | new-feature-gap-check | knowledge/opus-4.7-patterns.md | M | S |
|
||||
| token management | `opus-4.7-patterns.md` rammet rundt 4.7; lean system prompt-default (2.1.154) senker baseline | 2.1.154, 2.1.170 | now-wrong | update-knowledge | knowledge/opus-4.7-patterns.md | H | M |
|
||||
| token management | CC truncerer skill-listing ved budsjett-overflow; config-audit kan varsle før | 2.1.178 | partial | new-scanner | knowledge/opus-4.7-patterns.md | M | M |
|
||||
| token management | `disableBundledSkills` kan ANBEFALES (skjuler bundled-skill-desc fra system-prompt) | 2.1.169 | missing | new-feature-gap-check | knowledge/prompt-cache-patterns.md | M | S |
|
||||
| token management | `prompt-cache-patterns.md` (rendøpt fra `opus-4.7-patterns.md`); modell-nøytral mekanisme-tekst + ett Opus 4.8-anker | 2.1.154, 2.1.170 | ✅ DONE 2026-06-18 | update-knowledge | knowledge/prompt-cache-patterns.md | H | M |
|
||||
| token management | CC truncerer skill-listing ved budsjett-overflow; config-audit kan varsle før | 2.1.178 | partial | new-scanner | knowledge/prompt-cache-patterns.md | M | M |
|
||||
| token management | `skillListingBudgetFraction`/`maxSkillDescriptionChars` (UVERIFISERT, under gulv) | ~2.1.105 | missing | update-knowledge | knowledge/claude-code-capabilities.md | L | S |
|
||||
| slash commands | **`/config key=value`** — in-session-anvendelse av settings-anbefalinger (kan refereres i fix/feature-gap-tekst) | 2.1.181 | missing | update-knowledge | knowledge/claude-code-capabilities.md | M | S |
|
||||
| slash commands | `/simplify` → `/code-review` (stale bundled-skill-liste) | 2.1.147 | now-wrong | update-knowledge | knowledge/claude-code-capabilities.md | M | S |
|
||||
|
|
|
|||
|
|
@ -18,7 +18,7 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs <path> [--global] [--full-mach
|
|||
| `import-resolver.mjs` | IMP | Broken @imports, circular refs, deep chains, tilde paths |
|
||||
| `conflict-detector.mjs` | CNF | Settings conflicts, permission contradictions, hook duplicates |
|
||||
| `feature-gap-scanner.mjs` | GAP | 25 feature checks across 4 tiers — shown as opportunities, not grades |
|
||||
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascade, bloated SKILL.md descriptions, MCP tool-schema budget (Opus 4.7 patterns) |
|
||||
| `token-hotspots.mjs` | TOK | Cache-breaking volatile content, redundant tool permissions, deep import chains, oversized cascade, bloated SKILL.md descriptions, MCP tool-schema budget (prompt-cache patterns) |
|
||||
| `cache-prefix-scanner.mjs` | CPS | Volatile content in lines 31–150 of CLAUDE.md cascade (beyond Pattern A's top-30 window) |
|
||||
| `disabled-in-schema-scanner.mjs` | DIS | Tools listed in BOTH `permissions.deny` AND `permissions.allow` — deny wins, allow entries are dead config |
|
||||
| `collision-scanner.mjs` | COL | Cross-plugin skill name collisions (low); user-vs-plugin overlaps (medium); `details.namespaces` payload |
|
||||
|
|
@ -52,7 +52,7 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs <path> [--global] [--full-mach
|
|||
| `fix-cli.mjs` | CLI: `node fix-cli.mjs <path> [--apply] [--json] [--global]` |
|
||||
| `drift-cli.mjs` | CLI: `node drift-cli.mjs <path> [--save] [--baseline name] [--json]` |
|
||||
| `whats-active.mjs` | CLI: `node whats-active.mjs <path> [--json] [--verbose] [--suggest-disables]` — read-only active-config inventory |
|
||||
| `token-hotspots-cli.mjs` | CLI: `node token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` — Opus-4.7 token hotspots ranking with optional API calibration |
|
||||
| `token-hotspots-cli.mjs` | CLI: `node token-hotspots-cli.mjs <path> [--json] [--global] [--output-file path] [--accurate-tokens] [--with-telemetry-recipe]` — prompt-cache token hotspots ranking with optional API calibration |
|
||||
| `manifest.mjs` | CLI: `node manifest.mjs <path> [--json]` — ranked system-prompt token-source table (v5 N2) |
|
||||
|
||||
## Standalone Scanner
|
||||
|
|
@ -67,10 +67,10 @@ Scanner CLI: `node scanners/scan-orchestrator.mjs <path> [--global] [--full-mach
|
|||
| File | Content |
|
||||
|------|---------|
|
||||
| `claude-code-capabilities.md` | Feature register: 18 config surfaces, Anthropic guidance, relevance table |
|
||||
| `configuration-best-practices.md` | Per-layer best practices (v5: Opus 4.7 cache-stability guidance replaces Sonnet-era 200-line rule) |
|
||||
| `configuration-best-practices.md` | Per-layer best practices (v5: cache-stability guidance replaces Sonnet-era 200-line rule) |
|
||||
| `anti-patterns.md` | Common mistakes mapped to scanner IDs |
|
||||
| `hook-events-reference.md` | All 26 hook events with details |
|
||||
| `feature-evolution.md` | Feature timeline for staleness detection |
|
||||
| `gap-closure-templates.md` | Config-specific templates for closing gaps |
|
||||
| `opus-4.7-patterns.md` | Token-cost dynamics for Opus 4.7 era — patterns powering the TOK scanner |
|
||||
| `prompt-cache-patterns.md` | Token-cost dynamics (prompt-cache patterns) — patterns powering the TOK scanner |
|
||||
| `cache-telemetry-recipe.md` | Manual `jq` recipe for verifying prompt-cache hit rate from session transcripts (v5 M7) |
|
||||
|
|
|
|||
|
|
@ -109,6 +109,6 @@ when structural signal alone isn't enough.
|
|||
|
||||
## See also
|
||||
|
||||
- `knowledge/opus-4.7-patterns.md` — structural patterns the TOK scanner detects (CA-TOK-001..005)
|
||||
- `knowledge/prompt-cache-patterns.md` — structural patterns the TOK scanner detects (CA-TOK-001..005)
|
||||
- `knowledge/configuration-best-practices.md` — CLAUDE.md cache-stability guidance
|
||||
- `/config-audit tokens --with-telemetry-recipe` — surfaces a pointer to this file in JSON output
|
||||
|
|
|
|||
|
|
@ -6,7 +6,7 @@
|
|||
|
||||
## CLAUDE.md
|
||||
|
||||
1. **Optimise for prompt-cache stability.** Place stable content in the first 30 lines (cache-friendly prefix); volatile content (timestamps, dynamic counts, rolling activity logs) goes below that threshold or moves to an `@import`-ed file outside the cache prefix. On Opus 4.7 the dominant cost lever is cache reuse, not file length.[^200lines]
|
||||
1. **Optimise for prompt-cache stability.** Place stable content in the first 30 lines (cache-friendly prefix); volatile content (timestamps, dynamic counts, rolling activity logs) goes below that threshold or moves to an `@import`-ed file outside the cache prefix. On Opus 4.8 the dominant cost lever is cache reuse, not file length.[^200lines]
|
||||
2. **Use `@import` for specs/docs.** `@path/to/spec.md` inlines the file at session start. Max 5 hops, but keep chains ≤ 2 hops — every `@import` boundary fragments the prompt-cache prefix. Keeps the main file scannable.
|
||||
3. **Use HTML comments for maintainer notes.** `<!-- Updated 2026-01-01: reason -->` is stripped before context injection — zero token cost.
|
||||
4. **Put personal dev notes in `CLAUDE.local.md`**, not `CLAUDE.md`. Add `CLAUDE.local.md` to `.gitignore`. Team members' sandbox URLs should never appear in git.
|
||||
|
|
@ -94,4 +94,4 @@
|
|||
|
||||
---
|
||||
|
||||
[^200lines]: The "keep CLAUDE.md under 200 lines" threshold was a Sonnet-era adherence heuristic — Sonnet's attention quality dropped on longer files, so trimming raw line count was the optimisation lever. Opus 4.7 uses prompt-cache structure as the dominant cost driver: the first 30 lines must stay byte-stable across turns to keep the cache hit, and `@import` boundaries fragment the cached prefix. A 400-line CLAUDE.md with stable structure outperforms a 150-line file whose top contains a daily-rolling activity log. See `knowledge/opus-4.7-patterns.md` for detection IDs (CA-TOK-001..003).
|
||||
[^200lines]: The "keep CLAUDE.md under 200 lines" threshold was a Sonnet-era adherence heuristic — Sonnet's attention quality dropped on longer files, so trimming raw line count was the optimisation lever. Opus 4.8 uses prompt-cache structure as the dominant cost driver: the first 30 lines must stay byte-stable across turns to keep the cache hit, and `@import` boundaries fragment the cached prefix. A 400-line CLAUDE.md with stable structure outperforms a 150-line file whose top contains a daily-rolling activity log. See `knowledge/prompt-cache-patterns.md` for detection IDs (CA-TOK-001..003).
|
||||
|
|
|
|||
|
|
@ -1,14 +1,16 @@
|
|||
# Opus 4.7 Configuration Patterns
|
||||
# Prompt-Cache Configuration Patterns
|
||||
|
||||
> Token-efficiency patterns for Claude Opus 4.7. Detection IDs map to TOK scanner findings.
|
||||
> Sources: research/01-opus-47-features-token-efficiency.md (Topic 1), research/04-prompt-caching-patterns.md (Topic 4). Last verified 2026-04-19.
|
||||
> Token-efficiency patterns for current Claude Code (defaults to Opus 4.8; Fable 5 is the top-capability model). Detection IDs map to TOK scanner findings.
|
||||
> Sources: research/01-opus-47-features-token-efficiency.md (Topic 1), research/04-prompt-caching-patterns.md (Topic 4). Patterns verified 2026-04-19; model-era anchor refreshed 2026-06-18.
|
||||
|
||||
Opus 4.7 raises the cost ceiling per turn while expanding the context window
|
||||
and prompt-cache window. Net effect: cache reuse and tool-schema discipline
|
||||
become the dominant levers for keeping a session affordable. The patterns
|
||||
below are structural — they can be detected statically by reading config files
|
||||
without running a session. Cache hit-rate measurement requires runtime
|
||||
telemetry and is explicitly out of scope.
|
||||
Current Claude Code defaults to Opus 4.8 (Fable 5 is the top-capability model).
|
||||
On these models the cost ceiling per turn is high and both the context window
|
||||
and prompt-cache window are large, so cache reuse and tool-schema discipline
|
||||
are the dominant levers for keeping a session affordable. These patterns are
|
||||
properties of prompt-caching itself, not of any single model — they are
|
||||
structural and detectable statically by reading config files without running a
|
||||
session. Cache hit-rate measurement requires runtime telemetry and is
|
||||
explicitly out of scope.
|
||||
|
||||
| # | Pattern | Detection (ID) | Severity | Fix |
|
||||
|---|---------|----------------|----------|-----|
|
||||
|
|
@ -5,7 +5,7 @@
|
|||
* cached prefix (≤ CACHED_PREFIX_LINES). Distinguishes from TOK Pattern A,
|
||||
* which only inspects the top 30 lines: CPS catches a `!git log` at line 60
|
||||
* or a `${TIMESTAMP}` at line 100. Volatile content anywhere in the cached
|
||||
* prefix breaks Opus 4.7 prompt-cache reuse from that line forward.
|
||||
* prefix breaks prompt-cache reuse from that line forward.
|
||||
*
|
||||
* Volatile patterns extend the TOK set with shell-exec `!` prefix and
|
||||
* `${VAR}` substitutions — both common cache-busters in real CLAUDE.md files.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
#!/usr/bin/env node
|
||||
|
||||
/**
|
||||
* token-hotspots CLI — emit ranked token hotspots and Opus 4.7 pattern findings
|
||||
* token-hotspots CLI — emit ranked token hotspots and prompt-cache pattern findings
|
||||
* for a target repo path.
|
||||
*
|
||||
* Usage:
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
/**
|
||||
* TOK Scanner — Token Hotspots / Opus 4.7 patterns
|
||||
* TOK Scanner — Token Hotspots / prompt-cache patterns
|
||||
*
|
||||
* Detects three structural Opus 4.7-era token-efficiency patterns
|
||||
* Detects three structural prompt-cache token-efficiency patterns
|
||||
* (severities recalibrated for tokens/turn impact in v5 F7):
|
||||
* CA-TOK-001 cache-breaking volatile top in CLAUDE.md (high)
|
||||
* CA-TOK-002 redundant tool/permission declarations (medium)
|
||||
|
|
@ -15,7 +15,7 @@
|
|||
* a `hotspots` array (≤10 entries, possibly fewer for tiny projects) on the
|
||||
* scanner result.
|
||||
*
|
||||
* Pattern catalogue: knowledge/opus-4.7-patterns.md
|
||||
* Pattern catalogue: knowledge/prompt-cache-patterns.md
|
||||
* Token heuristic: estimateTokens() in scanners/lib/active-config-reader.mjs
|
||||
*
|
||||
* Zero external dependencies.
|
||||
|
|
@ -315,7 +315,7 @@ export async function scan(targetPath, discovery) {
|
|||
description:
|
||||
`The first ${VOLATILE_TOP_LINES} lines of ${f.relPath || f.absPath} contain volatile ` +
|
||||
'tokens (timestamps, session ids, or activity logs). Volatile content above stable ' +
|
||||
'content defeats Opus 4.7 prompt-cache reuse on every turn.',
|
||||
'content defeats prompt-cache reuse on every turn.',
|
||||
file: f.absPath,
|
||||
evidence: CALIBRATION_NOTE,
|
||||
recommendation:
|
||||
|
|
|
|||
|
|
@ -92,3 +92,21 @@ test('configuration-best-practices.md recommends real MCP approval, not a `trust
|
|||
assert.doesNotMatch(md, /Set trust levels explicitly/,
|
||||
'the invented "set trust levels" advice must be gone');
|
||||
});
|
||||
|
||||
// Token-efficiency corpus era-anchor (Fase 4 token-opt). The prompt-cache pattern
|
||||
// catalogue was frozen at an "Opus 4.7" framing after CC shipped Opus 4.8 (default,
|
||||
// 2.1.154) and Fable 5 (2.1.170). The mechanics are properties of prompt-caching,
|
||||
// not of a model, so the corpus anchors the current default (Opus 4.8) once and
|
||||
// keeps the pattern text model-neutral — preventing a re-freeze at the next bump.
|
||||
test('prompt-cache pattern catalogue is anchored to Opus 4.8, not frozen at Opus 4.7', () => {
|
||||
const md = read('prompt-cache-patterns.md');
|
||||
assert.match(md, /Opus 4\.8/, 'must name the current default model (Opus 4.8), not a stale 4.7 anchor');
|
||||
assert.doesNotMatch(md, /Opus 4\.7/, 'all stale Opus-4.7 era-stamping must be gone from the pattern catalogue');
|
||||
});
|
||||
|
||||
test('configuration-best-practices.md CLAUDE.md cost framing names Opus 4.8, not stale 4.7', () => {
|
||||
const md = read('configuration-best-practices.md');
|
||||
assert.match(md, /Opus 4\.8/, 'the cache-vs-length cost-lever framing must name the current default model');
|
||||
assert.doesNotMatch(md, /On Opus 4\.7|Opus 4\.7 uses prompt-cache/,
|
||||
'the present-tense Opus-4.7 cost framing (body + footnote) must be refreshed to 4.8');
|
||||
});
|
||||
|
|
|
|||
|
|
@ -61,6 +61,12 @@ describe('TOK scanner — opus-47/cache-breaking', () => {
|
|||
const f = result.findings.find(x => x.id === 'CA-TOK-001');
|
||||
assert.equal(f.severity, 'high', `expected high after F7, got ${f.severity}`);
|
||||
});
|
||||
|
||||
it('CA-TOK-001 description carries no stale Opus-4.7 anchor (mechanic is model-agnostic)', () => {
|
||||
const f = result.findings.find(x => x.id === 'CA-TOK-001');
|
||||
assert.doesNotMatch(f.description, /Opus 4\.7/,
|
||||
'prompt-cache mechanics are a feature property, not model-specific; do not era-stamp a stale model');
|
||||
});
|
||||
});
|
||||
|
||||
describe('TOK scanner — opus-47/redundant-tools', () => {
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue