agent-clinic/claude-md-doctor

"name": "Tristan Chen"   },   "homepage": "https://github.com/agent-clinic/claude-md-doctor",

},   "homepage": "https://github.com/agent-clinic/claude-md-doctor",   "license": "MIT",

"homepage": "https://github.com/agent-clinic/claude-md-doctor",

Executable file

#!/usr/bin/env python3

#!/usr/bin/env python3

return """<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 418">

label, value = "CLAUDE.md checkup", "grade %s" % grade     lw, vw = 10 + len(label) * 7, 10 + len(value) * 7     return """<svg xmlns="http://www.w3.org/2000/svg" width="%d" height="20" role="img" aria-label="%s: %s">

lw, vw = 10 + len(label) * 7, 10 + len(value) * 7     return """<svg xmlns="http://www.w3.org/2000/svg" width="%d" height="20" role="img" aria-label="%s: %s"> <clipPath id="r"><rect width="%d" height="20" rx="3"/></clipPath>

return """<svg xmlns="http://www.w3.org/2000/svg" width="%d" height="20" role="img" aria-label="%s: %s">

print("badge: %s" % badge_path)     print("badge snippet: [![CLAUDE.md health](%s)]"           "(https://github.com/agent-clinic/claude-md-doctor)"

print("badge snippet: [![CLAUDE.md health](%s)]"           "(https://github.com/agent-clinic/claude-md-doctor)"           % os.path.basename(badge_path))

"(https://github.com/agent-clinic/claude-md-doctor)"

#!/usr/bin/env python3

#!/usr/bin/env python3

#!/usr/bin/env python3

#!/usr/bin/env python3

#!/usr/bin/env python3

[Credential-related source omitted]

#!/usr/bin/env python3

CITATIONS = {     "official-200": ("Claude Code memory doc — “Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.”", "https://code.claude.com/docs/en/memory"),

"official-200": ("Claude Code memory doc — “Size: target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence.”", "https://code.claude.com/docs/en/memory"),

"official-best-practices": ("Claude Code best practices — deletion test; “Bloated CLAUDE.md files cause Claude to ignore your actual instructions!”; sparse emphasis.", "https://code.claude.com/docs/en/best-practices"),

"official-hooks": ("Claude Code memory doc — CLAUDE.md is “context, not enforced configuration”; use a PreToolUse hook to block an action regardless.", "https://code.claude.com/docs/en/memory"),

"official-4mib": ("Claude Code memory doc — a CLAUDE.md over 4 MiB is skipped entirely.", "https://code.claude.com/docs/en/memory"),

"official-40k": ("Claude Code troubleshooting — startup warning at 40,000 characters of memory content.", "https://code.claude.com/docs/en/troubleshooting"),

"eth": ("Gloaguen et al. (ETH Zurich), “Evaluating AGENTS.md” (v2): context files cost +20–23% inference with no significant success change; agents measurably comply with explicit directives; “describe only minimal requirements.”", "https:/

"mcmillan": ("McMillan, factorial study of 1,650 Claude Code sessions: no detectable structural effect of file size/position/contradictions in tested range; within-session adherence decay ≈ 5.6%/function.", "https://arxiv.org/abs/2605.10039

"ifscale": ("IFScale: adherence 98.4% at 100 instructions → 84.8% at 250 → 68.9% at 500; errors shift to silent omission.", "https://arxiv.org/abs/2507.11538"),

"agentif": ("AGENTIF (NeurIPS 2025): best model satisfies all constraints of an agentic instruction 27.2% of the time; ≈0 past 6,000 words.", "https://arxiv.org/abs/2505.16944"),

"sysbench": ("SysBench: system-message constraint adherence decays ≈12.8pp/turn over 5 turns (GPT-4o).", "https://arxiv.org/abs/2408.10943"),

"levy": ("Levy, Jacoby & Goldberg (ACL 2024): accuracy 0.92 → 0.68 with 3,000 tokens of padding; degradation starts ≈500 tokens.", "https://arxiv.org/abs/2402.14848"),

"chroma": ("Chroma “Context Rot”: 18 models degrade with input length even on trivial tasks; focused ~300-token prompts beat 113k-token contexts.", "https://www.trychroma.com/research/context-rot"),

"longllmlingua": ("LongLLMLingua (ACL 2024): +21.4% at ~4× prompt compression — cutting filler can raise performance.", "https://arxiv.org/abs/2310.06839"),

"caps": ("Dillitzer et al., “Attention is Case-Sensitive”: uppercase shifts +1.85pp accuracy; near-zero on reasoning models; saturation spends the effect.", "https://arxiv.org/abs/2608.03711"),

"sigil": ("SIGIL: prose agents perform 56% of the steps their own skill mandates while outputs still pass checks; script-compiled harnesses reach 86%.", "https://arxiv.org/abs/2607.27309"),

"trace": ("TRACE: with memory alone, 57.5% of applicable user-preference checks are still violated; compiling corrections into runtime checks cuts violations from 100% to 2–38%.", "https://arxiv.org/abs/2606.13174"),

"harness-if": ("Harness-IF: models comply 3.6–7.4pp worse on rules that oppose their unprompted defaults — high compliance on a with-prior rule may be coincidence, not obedience; skill/tool descriptions rank below project files in precedenc

"iheval": ("IHEval (NAACL 2025): when instructions conflict, all models drop sharply — the best open-source model resolves conflicts at only 48%. Contradictory rules measurably degrade compliance, and the winner is not reliably the rule you

"hierarchy": ("OpenAI Instruction Hierarchy: models are trained to prioritize privileged instructions — a project-file rule that fights trained-in behavior starts at a disadvantage; some rules need hooks because the prior will win.", "https

"specbench": ("SpecBench: agents saturate visible checks while holdout gaps grow ~28pp per 10× code size — a check the agent can see may be satisfied without honoring the rule.", "https://arxiv.org/abs/2605.21384"),

"agent-readmes": ("“Agent READMEs” (2,303 context files): tests 75.9% / implementation 70.8% / architecture 68.1%; security & performance nearly absent; files accrete without pruning.", "https://arxiv.org/abs/2511.12884"),

"cursor-rules": ("Jiang & Nam (MSR 2026), 401 repos: five-theme content taxonomy; ~28.7% duplicated lines across a repo's rules files.", "https://arxiv.org/abs/2512.18925"),

"awm": ("Agent Workflow Memory: induced, selectively-loaded workflows +51.1% relative on WebArena — recurring procedures belong in on-demand skills.", "https://arxiv.org/abs/2409.07429"),

"unblocked": ("Unblocked, “Audit a bloated CLAUDE.md in 7 steps” — the manual audit this tool automates.", "https://getunblocked.com/blog/audit-fix-bloated-claude-md/"),

"surface-bloat": ("“Too Many CLAUDE.md and Skill Files?” — aggregate memory surfaces fail silently (60 files ≈ 64k standing tokens); fixes: consolidate → thin router/index → one-screen invariants + on-demand procedures.", "https://xtrace.ai

#!/usr/bin/env python3

#!/usr/bin/env python3

<meta name="viewport" content="width=device-width, initial-scale=1"> <title>CLAUDE.md checkup — {{REPO_NAME}}</title> <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Crect x='4' y=

<title>CLAUDE.md checkup — {{REPO_NAME}}</title> <link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Crect x='4' y='1' width='4' height='10' fill='%23c0492f'/%3E%3Crect x='1' y='4' wid

<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 12 12'%3E%3Crect x='4' y='1' width='4' height='10' fill='%23c0492f'/%3E%3Crect x='1' y='4' width='10' height='4' fill='%23c0492f'/%3E%3C/svg%3E