Claude md and folder standards

Standards for CLAUDE.md & .claude/ files

Follow these rules when creating or modifying any CLAUDE.md — each repo's root CLAUDE.md included; it lives outside .claude/, but these rules still apply to it — or any file under .claude/ (skills, settings.json, hooks).

CLAUDE.md Rules

• Max 200 lines. If it exceeds this, move content to skills.
• Only include instructions Claude would get WRONG without. Delete anything obvious.
• Never duplicate what can be inferred from project files (tsconfig, package.json, etc.).
• No frequently changing info (versions, team members, URLs that rotate).
• No self-evident advice ("write clean code", "follow best practices").
• Structure: Overview > Setup > Code style > Testing > Git workflow > Gotchas.
• Don't inline detailed or occasional content — reference it. For subsystem detail you read only sometimes, use a plain [link](path) to a repo-local doc — it's read on demand, so it costs nothing until a task needs it (cheapest). Reserve @path imports for the rare doc you genuinely need every session.
• @path imports are ALWAYS-ON — expanded into context at launch (up to 4-hop nesting), so they cost the same as inlining, every session. They organize; they DON'T defer. NEVER @-import a big doc — link it with a plain path instead.

Deciding Where Content Belongs

If the instruction...	Put it in...
Applies every session, prevents mistakes	CLAUDE.md
Is specialized to one workflow/domain	A skill
Is a personal/machine-specific override	CLAUDE.local.md or settings.local.json
Must execute deterministically (not advisory)	A hook
Defines a reusable subagent with scoped tools	agents/

Skills Rules

• Prefer skills over long CLAUDE.md sections for specialized knowledge.
• Keep each skill focused on one workflow or domain.
• Name the folder descriptively with kebab-case.
• Include name and description in the frontmatter.
• Target 50-80 lines per skill. Under 120 max.
• Ask per skill: could a cheaper model run it? Only if the workflow is mechanical (judgment spelled out in the body) AND self-contained — then set frontmatter model: haiku/sonnet (optionally effort:), ideally with context: fork. Otherwise inherit: the override lasts the rest of the turn (downgrading whatever task invoked the skill) and a mid-turn model switch busts the prompt cache both ways. Judgment-heavy or high-stakes skills (prod migrations, shared-config edits, session summaries) always inherit.
• Pick the tier by task SHAPE, not just "cheaper": haiku = mechanical AND terminal (runs at the turn's end — a commit, a final formatting pass). sonnet = high-VOLUME batch that still carries light editorial judgment (a playlist-scale copy-edit Haiku would flatten). inherit = rare (savings ≈ 0) OR judgment-heavy. A mid-turn (non-terminal) skill stays inherit even when mechanical — the cache-bust outweighs the token saving. The real routing wins are subagents (own context, no cache cost).

settings.json Rules

• Project-level settings.json is shared (checked in). No secrets, no personal paths.
• Personal overrides go in settings.local.json (must be in .gitignore).
• Permissions: prefer specific patterns (Bash(npm test *)) over broad wildcards.
• Set model and effort at session start to preserve prompt cache.

Token Awareness

When adding ANY content to .claude files, consider token cost:

• Every line of CLAUDE.md costs ~2-4 tokens PER TURN, every turn, every session.
• Ask: "Is this worth paying for on every single message?"
• If the answer is "only sometimes" — it's a skill, not CLAUDE.md.
• Prefer terse, imperative rules over explanatory prose.
• Use bullet points, not paragraphs.

Anti-Patterns to Reject

• Adding "use TypeScript" when tsconfig.json exists
• Listing every file in the project
• Pasting entire style guides (link them instead)
• Adding instructions "just in case" — if it's not causing errors, don't add it
• Duplicating content already in another file (README, CONTRIBUTING, etc.)

Before Saving Changes

1. Count lines. Is CLAUDE.md still under 200?
2. Could this be a skill instead? If yes, make it one.
3. Is this already inferrable from project files? If yes, skip it.
4. Read it as if paying per-word. Cut filler.