Core Principles

Progressive disclosure is the most critical principle. Load only what is needed, when it is needed.

• Level 1: Frontmatter — name + description. Always loaded.
• Level 2: SKILL.md — core workflow. Loaded when triggered. Under 100 lines.
• Level 3: References — deep docs. Loaded only when needed.

CLAUDE.md is a behavioral contract, not documentation. Every line must change agent behavior or be deleted. Less is more. Target 60–120 lines for a project file, under 30 for global, under 80 for monorepo root. Imperatives over prose. Verifiable commands over descriptions. High-priority rules first. Security, irreversibility, and out-of-scope rules in the first 40 lines. IMPORTANT / YOU MUST sparingly. Reserve for the one or two truly critical rules. Negative rules matter. Without explicit "nevers," the agent picks the most common pattern. Don't duplicate the linter, the CI, or auto-memory. Delete anything tooling already enforces. No secrets. Ever. Not in CLAUDE.md, not in CLAUDE.local.md.

See references/principles.md for full rationale.