# Claude Md And Folder Standards

> Standards for editing any CLAUDE.md (each repo's root CLAUDE.md included — it lives outside .claude/ but these rules still govern it) and any file under .claude/ (skills, settings.json, hooks). Invoke before modifying any of them.

- Skill: `prostdev/claude-md-and-folder-standards` (Agent Skill)
- Install (CLI): `npx skillmds@latest add prostdev/claude-md-and-folder-standards`
- Raw SKILL.md: https://api.skillmd.com/api/skills/prostdev/claude-md-and-folder-standards/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ProstDev (https://skillmd.com/u/prostdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/prostdev/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

For how to write the SKILL.md itself — frontmatter, descriptions, conciseness, progressive
disclosure, size — follow the [`writing-skills`](../writing-skills/SKILL.md) skill (the single
source of truth for skill craft). This section covers only Claude-Code-specific routing.

- Prefer skills over long CLAUDE.md sections for specialized knowledge.
- 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.