Kjell Tore Guttormsen
fe686b6594
Five additive scanner findings extend existing scanners (count stays 13): DIS forbidden-param rules (Tool(param:value) on a canonicalizing field — deny/ask = false security, allow = dead config) and ineffective allow-wildcards + Tool(*) deny-all; CML context-window-scaled 40.0k-char CLAUDE.md budget mirroring CC's startup warning; PLH plugin namespace collision (two plugins declaring the same name). PLH cross-plugin command-name overlap reframed HIGH → LOW (namespacing keeps both reachable). feature-gap recommends disableBundledSkills under skill-listing pressure. Version sync: plugin.json 5.2.0→5.3.0, README version badge + What's New + version-history row + TOC anchor (tests badge already 936+, scanner count stays 13), CHANGELOG [5.3.0] entry, 3 knowledge-backing entries. 936/936 tests; self-audit configGrade A 97, pluginGrade A 100, readmeCheck.passed:true; gitleaks clean. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Ter3E2JSi1Khgmuf2kady8
69 lines
4.6 KiB
Markdown
69 lines
4.6 KiB
Markdown
# Prompt-Cache Configuration Patterns
|
||
|
||
> 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.
|
||
|
||
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 |
|
||
|---|---------|----------------|----------|-----|
|
||
| 1 | Cache-breaking volatile top-of-file content in CLAUDE.md (timestamps, session ids, rolling activity logs above stable content) | CA-TOK-001 | medium | Move volatile sections to the bottom of CLAUDE.md, or extract to an `@import`-ed file that lives outside the prompt-cache prefix. Keep the first 30 lines stable across turns. |
|
||
| 2 | Redundant tool/permission declarations in settings.json (e.g., both `"Read"` and `"Read(**)"`, duplicate Bash matchers, overlapping glob patterns) | CA-TOK-002 | low | Deduplicate the `permissions.allow` and `permissions.deny` arrays. Prefer the most specific entry that still grants the intended access. Each duplicate entry inflates the tool-schema payload sent on every turn. |
|
||
| 3 | Deep `@import` chain in CLAUDE.md (more than 2 hops, e.g., A → B → C → D) | CA-TOK-003 | medium | Flatten the chain to ≤ 2 hops. Each `@import` boundary fragments the prompt-cache prefix; deeply chained imports defeat caching for the deepest content even when it never changes. |
|
||
|
||
> The v4 sonnet-era signature pattern was removed in v5 F5 — too noisy and not
|
||
> actionable. Hotspots ranking and per-pattern findings cover the same ground
|
||
> with concrete, file-anchored signal.
|
||
|
||
## Detection notes
|
||
|
||
- **Pattern 1 (cache-breaking)** is detected by inspecting the first ~30 lines
|
||
of CLAUDE.md for tokens that look volatile: literal `{timestamp}`, `{uuid}`,
|
||
`{date}`, `{session}` placeholders, or runs of ISO-timestamp-prefixed lines.
|
||
The scanner does not attempt to verify cache-hit rate; it flags the *shape*
|
||
of content that empirically defeats prompt-cache reuse.
|
||
- **Pattern 2 (redundant tools)** is detected by flattening the
|
||
`permissions.allow` and `permissions.deny` arrays and looking for entries
|
||
that are strict subsets of broader entries (e.g., `Bash(npm test)` when
|
||
`Bash(*)` is also present), or exact duplicates.
|
||
- **Pattern 3 (deep imports)** uses the existing IMP scanner's chain depth as
|
||
the input — anything > 2 hops triggers TOK-003 as well as the IMP finding.
|
||
|
||
## Threshold calibration
|
||
|
||
All thresholds in this catalogue are **structural** — derived from the
|
||
existing `estimateTokens(bytes, kind)` heuristic in
|
||
`scanners/lib/active-config-reader.mjs:29-39`. They are intentionally
|
||
conservative until Topic 3 (token-cost model) research is complete. When
|
||
Topic 3 lands, severities for patterns 1–3 will be re-tuned.
|
||
|
||
The `estimateTokens` heuristic uses ~4 bytes per token for markdown content,
|
||
which is conservative but unverified against an authoritative tokenizer.
|
||
All token counts surfaced by the TOK scanner carry an implicit ±20%
|
||
uncertainty band.
|
||
|
||
## Severity Scale
|
||
|
||
| Severity | Meaning |
|
||
|----------|---------|
|
||
| medium | Materially inflates token cost per turn (cache miss, schema bloat) |
|
||
| low | Detectable inefficiency that compounds across long sessions |
|
||
| info | Informational signal — no action required, may indicate room for optimisation |
|
||
|
||
## Skill-listing budget lever: disableBundledSkills
|
||
|
||
When the active skill listing exceeds its token budget (SKL `CA-SKL-002`), the
|
||
`disableBundledSkills` setting is a direct token-efficiency lever: it removes the descriptions
|
||
of plugin-bundled skills from the skill listing injected into the system prompt, shrinking the
|
||
per-turn baseline. Unlike trimming individual descriptions (`CA-SKL-001`), it is a single switch
|
||
that drops the entire bundled-skill surface at once — appropriate when the bundled skills are not
|
||
in active use. feature-gap surfaces it as a conditional recommendation, the remediation companion
|
||
to `CA-SKL-002`. Sibling levers: `skillOverrides` (selectively re-enable specific skills) and
|
||
per-skill description trimming.
|