Claude Md

CLAUDE.md authoring & maintenance

The meta-skill for keeping memory files load-bearing. Grounded in Anthropic's own docs (code.claude.com/docs/en/memory + /best-practices), not opinion. The one rule under all the others: CLAUDE.md loads in full every session as an advisory user message — every line costs tokens on every turn and competes for adherence. Smaller and sharper beats bigger.

The non-negotiables (from Anthropic)

1. Target under 200 lines. Over that "consumes more context and reduces adherence." Community sweet spot is ~300–600 tokens of contract. Our past failure mode is 800+ line files.
2. The per-line test. For every line ask: "Would removing this cause Claude to make a mistake?" If no → cut it or move it. This is the primary editing loop.
3. Only what is true EVERY session goes in CLAUDE.md. Sometimes-relevant → a skill. File-type-specific → a path-scoped rule. (See decision table below.)
4. @import does NOT save tokens. Imported files load in full at launch too. Imports are for human organization only. The real context-cutting levers are path-scoped rules and skills (both lazy-load).
5. Must-always-happen ≠ a sentence — it's a hook. CLAUDE.md is advisory (delivered as a user message, no guaranteed compliance). To enforce, use a PreToolUse/PostToolUse hook.
6. Be concrete and verifiable. "Use 2-space indent" not "format properly." "Run pnpm v BUILD before deploy" not "test your changes."
7. No contradictions. If two lines conflict (e.g. "bias to caution" vs "ship fast"), Claude picks one arbitrarily. Name the axis each governs, or cut one.
8. IMPORTANT/YOU MUST sparingly — only on rules that keep getting violated. Inflation kills it.
9. HTML comments <!-- --> are stripped before injection — zero token cost. Use for maintainer notes, dates, "why this rule exists." Never burn a visible line on meta-commentary.
10. Treat it like code. Prune when behavior drifts; the diagnostic is literally "if Claude keeps doing X despite a rule against it, the file is too long and the rule is getting lost."

Where each thing belongs (the decision table)

Path-scoped rule frontmatter:

---
paths: ["app/research/**", "lib/research/**"]
---
Research hub renders from lib/research/domains.ts. New domain = one ResearchDomain object…

The ideal CLAUDE.md skeleton (keep it to these)

# <Project> — one line of what it is
## Operating doctrine     # LEAD/ship rules + hard-stops (the contract)
## Guardians              # the green-light checklist (commands that gate a ship)
## Commands               # bash Claude can't guess (build/test/lint/deploy)
## Code style & workflow  # only what differs from defaults; branch/PR etiquette
## Brand voice            # the few do/don'ts that matter
## Architecture pointers  # "X lives in Y" + @import or links to rules/docs for depth

Everything thicker than that is a rule, a skill, a hook, or a doc.

Audit rubric (score 0–100, used by /claude-md-audit)

Score < 70 → refactor. Report the worst 3 axes with paste-ready fixes.

Tooling

• agnix — the linter for AI config files (CLAUDE.md, AGENTS.md, SKILL.md, hooks, MCP), 422 rules, flags vague/generic/conflicting instructions. npm i -g agnix → agnix . · agnix --fix-safe . (HIGH-confidence only) · playground at agent-sh.github.io/agnix. Run it as the mechanical pass before the judgment pass.
• /init — Anthropic's official generator (CLAUDE_CODE_NEW_INIT=1 for the interactive flow). Use to bootstrap a new repo's CLAUDE.md, then prune to the skeleton above.
• /memory — lists every loaded memory file; use it to confirm a rule is actually in context.

Refactoring a bloated CLAUDE.md (loss-less protocol)

Never delete good content — relocate it. Git + a snapshot guarantee nothing is lost.

1. Snapshot first. Copy the current file to backups/claude-md/CLAUDE.md.<YYYY-MM-DD>.bak and commit. (Belt-and-suspenders on top of git history.)
2. Classify every section against the decision table → keep / rule / skill / doc.
3. Move, don't rewrite. Cut each situational section verbatim into its new home (.claude/rules/*.md with paths:, or docs/architecture/*.md), leaving a one-line pointer.
4. Reconcile contradictions surfaced during the move (name the axis or cut one).
5. Verify nothing vanished: git diff should show content moved, not gone. Re-run the audit; confirm < 200 lines and score ≥ 85.
6. Confirm load: /memory shows the lean file; path-scoped rules appear when their globs open.

Public vs private (sharing best setups safely)

• Project CLAUDE.md is public-by-default (committed, team/world-readable). Treat as public text.
• Never commit: API keys, tokens, internal hostnames, private sandbox URLs, anything .env.
• Personal/private per-project notes → CLAUDE.local.md (gitignored) or @~/.claude/<file>.md (lives in home, not the repo — survives worktrees).
• Publish the best setups (this skill, the lean CLAUDE.md template, generic rules) to a public config repo. Keep brand-confidential strategy, client material, family notes, and financial ops private. When in doubt, it stays private.