Claude Md Tuner

CLAUDE.md Tuner

A CLAUDE.md is loaded into context on every session, so every line has a permanent token cost and every wrong line steers the agent wrong forever. The goal is a short, high-signal, verifiable file — not a wiki. This skill both generates a new one from the repo and audits/trims an existing one.

Core principle

Include a line only if it changes what the agent does and the agent could not cheaply discover it itself. Ruthlessly cut anything that is: (a) obvious from the code, (b) aspirational rather than enforced, (c) a general best practice not specific to this repo, or (d) already true by default.

Mode A — Generate from scratch

1. Learn the repo, don't guess. Detect the stack: read package.json/pyproject.toml/go.mod/Cargo.toml/Gemfile; find the real build/test/lint commands in scripts, Makefile, justfile, and CI workflows. Prefer commands you can see are wired up over conventional ones.
2. Verify the commands exist before writing them. A CLAUDE.md that says npm test when the script is npm run test:unit is worse than saying nothing.
3. Capture only load-bearing conventions: the package manager to use (never mix), where code vs. tests live, the one architectural rule that's easy to violate, any command that is dangerous or slow, and how to run a single test (agents waste minutes running full suites otherwise).
4. Record hard "don'ts" that have real consequences here: "never edit generated/", "never commit to main", "migrations are irreversible in prod".

Mode B — Audit an existing CLAUDE.md

Read it and classify every line/section into: Keep (specific + enforced + non-obvious), Fix (right idea, wrong/stale detail), Cut (obvious, generic, aspirational, or duplicated). For each Cut, give the one-word reason. Flag specifically:

• Stale commands — cross-check every command against scripts/Makefile/CI; mark ones that no longer exist.
• Context bloat — a file over ~150 lines almost always has cuttable filler. Report the line count and the top cuts.
• Contradictions — two rules that can't both hold; rules that fight the linter/formatter config.
• Vague directives — "write clean code", "be careful", "follow best practices" carry no information; cut or make concrete.
• Secrets/paths that shouldn't be committed.

Structure to aim for

Short imperative sections, most-violated rules first:

# <Project> — notes for Claude Code

## Commands
- Install: <cmd>   ·   Test (single): <cmd>   ·   Lint/format: <cmd>   ·   Build: <cmd>

## Layout
- <where source lives> / <where tests live> / <anything non-obvious>

## Conventions (only the enforced, easy-to-break ones)
- <e.g. "Use pnpm only — npm/yarn will corrupt the lockfile">
- <e.g. "All API handlers return the Result type; never throw across the boundary">

## Don't
- <hard rules with consequences>

Edge cases

• Monorepo: keep the root file thin; recommend per-package CLAUDE.md files near the code they govern rather than one giant root file.
• AGENTS.md coexistence: if the repo uses AGENTS.md, keep instructions in one canonical file and have the other reference it — don't maintain two that drift.
• Team repo: don't encode one person's personal preferences as team law; separate "house style" from "my preference."
• Nothing worth saying: if the repo is small and conventional, a 15-line file is the correct answer. Do not pad it.

Quality bar

• Every command is copy-pasteable and verified against the repo.
• Nothing generic survives ("uses git", "write tests" — cut).
• A new contributor's agent reads it and immediately stops making this repo's specific mistakes.
• Target well under 150 lines; shorter is better if signal is preserved.

Output

• Mode A: the finished CLAUDE.md in a fenced block, plus a one-line note on what you verified vs. assumed.
• Mode B: a Keep/Fix/Cut table, the resulting line-count reduction, then the rewritten file in a fenced block.