open/config-audit
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

fix(claude-md-linter): reframe CLAUDE.md length from HIGH adherence cliff to MEDIUM token cost

Browse source 
The >500-line check emitted HIGH severity with "Files over 500 lines
significantly reduce Claude's adherence to instructions." CC 2.1.169
scaled the "too long" warning by context window, and the plugin's own
configuration-best-practices.md:97 footnote already says raw line count
is a Sonnet-era heuristic superseded by cache-prefix stability — so the
absolute HIGH + universal adherence claim is now-wrong.

- >500 lines: HIGH -> MEDIUM, reworded to token-cost-every-turn +
  smaller-context-model caveat + cache-prefix pointer; notes CC 2.1.169
  scales the threshold by context window.
- >200 lines: stays MEDIUM, dropped the absolute "optimal adherence"
  framing for the same token/context-window framing.

Aligns the scanner with anti-patterns.md:7 (CA-CML-001 = medium) and
configuration-best-practices.md:97. No snapshot impact (byte snapshots
use a 24-line fixture CLAUDE.md).

Full suite: 842/842 green (+5). self-audit PASS, A(100)/A(97).
This commit is contained in:
Kjell Tore Guttormsen 2026-06-18 13:15:38 +02:00
commit feaa7ed2e4
2 changed files with 61 additions and 4 deletions
Download patch file Download diff file Expand all files Collapse all files

12
scanners/claude-md-linter.mjs
View file

@ -59,15 +59,19 @@ export async function scan(targetPath, discovery) {
const imports = findImports(content);
// --- Length checks ---
// Raw line count is no longer an absolute adherence threshold: CC 2.1.169
// scales the "too long" warning by context window, and cache-prefix
// stability (not line count) is the dominant cost driver on large-context
// models. These are MEDIUM token-cost signals, not a HIGH adherence cliff.
if (lines > MAX_ABSOLUTE_LINES) {
findings.push(finding({
scanner: SCANNER,
severity: SEVERITY.high,
severity: SEVERITY.medium,
title: 'CLAUDE.md exceeds 500 lines',
description: `${file.relPath} has ${lines} lines. Files over 500 lines significantly reduce Claude's adherence to instructions.`,
description: `${file.relPath} has ${lines} lines. A file this size loads in full on every turn (token cost) and, on smaller-context models, can crowd out instructions. Large-context models tolerate longer files when the cache prefix stays stable — raw line count is no longer an absolute adherence threshold (CC 2.1.169 scales it by context window).`,
file: file.absPath,
evidence: `${lines} lines`,
recommendation: 'Split into @imports and .claude/rules/ files. Keep CLAUDE.md under 200 lines.',
recommendation: 'Split into @imports and .claude/rules/ files, and keep the top of CLAUDE.md byte-stable for cache hits (see token / cache-prefix findings). Under ~200 lines stays safest across models.',
autoFixable: false,
}));
} else if (lines > MAX_RECOMMENDED_LINES) {
@ -75,7 +79,7 @@ export async function scan(targetPath, discovery) {
scanner: SCANNER,
severity: SEVERITY.medium,
title: 'CLAUDE.md exceeds recommended 200 lines',
description: `${file.relPath} has ${lines} lines. Best practice is under 200 lines for optimal adherence.`,
description: `${file.relPath} has ${lines} lines. Under ~200 lines is the safe default across models; larger is fine on large-context models when the cache prefix stays stable. A long file still costs tokens every turn.`,
file: file.absPath,
evidence: `${lines} lines`,
recommendation: 'Consider using @imports or .claude/rules/ for detailed content.',