claude-md

CLAUDE.md

Important — Writing rules

Apply these rules to emitted prose: docs, comments, commit messages, PR bodies, and release notes.

• Match surrounding punctuation, capitalization, and formatting.
• Every sentence changes the reader's understanding. Cut it otherwise.
• Lead with the action or outcome.
• Use concrete language and lists when they improve comparison or sequence.
• Assert positively. Reserve negation for real constraints (NEVER commit secrets).
• No marketing words: powerful, robust, seamlessly, leverage, unlock, comprehensive, delightful.
• No AI tells: delve, tapestry, intricate, pivotal, testament, underscore, crucial, garner, showcase, additionally, moreover, furthermore, indeed.
• For substantive English prose, use /humanize-en if installed with the existing scope and authorization. It adds no approval stage; skip redundant passes over short status text.

Core Principle

Memory files consume tokens every session. Keep high-value project conventions, commands and boundaries concise. Discoverability alone is not a reason to delete guidance that prevents a demonstrated mistake.

Three mechanisms carry knowledge across sessions:

• CLAUDE.md — single-file instructions you write. Always loaded.
• .claude/rules/ — modular rule files, optionally path-scoped. Load alongside CLAUDE.md.
• Auto memory — notes Claude writes itself per project. See Auto Memory below.

For most projects, CLAUDE.md and rules combine (hybrid pattern). See Workflow > Storage Strategy for the pick-which decision.

Quick Start

Run /init to auto-generate a CLAUDE.md. Or create manually:

# Project Name

## Tech Stack
- [Primary framework]
- [Key non-obvious libraries]

## Commands
- `npm run dev` - Dev server
- `npm test` - Run tests
- `npm run build` - Build

## Rules
- [2-3 critical project-specific rules]

• Run /memory to view all loaded files (CLAUDE.md, CLAUDE.local.md, rules), toggle auto memory, and open any file in your editor

File Hierarchy

Location	Scope	Notes
Managed policy (OS-specific path managed by IT)	All org users	Cannot be excluded by individual settings
./CLAUDE.md or ./.claude/CLAUDE.md	Team via git	Project-wide
./.claude/rules/*.md	Team via git	Modular, optionally path-scoped
~/.claude/CLAUDE.md	All your projects	Personal, applies everywhere
~/.claude/rules/*.md	All your projects	Personal rules, loaded before project rules
./CLAUDE.local.md	Just you (this project)	Add to .gitignore yourself (or use /init personal option)

All discovered files are concatenated, not overridden. More specific locations take precedence in conflicts. Within a directory, CLAUDE.local.md loads after CLAUDE.md, so personal notes win over team instructions at the same level.

Claude recurses UP from the CWD, loading all files found. Subtree CLAUDE.md files load on-demand when Claude reads files in those directories.

AGENTS.md is not read directly. If your repo uses it for other agents, import it from CLAUDE.md with @AGENTS.md so both tools share one source.

Managed CLAUDE.md ≠ managed settings. Enterprise deployments can push both, and they serve different purposes. Settings enforce (blocked tools, sandbox, auth, env); CLAUDE.md guides (coding standards, compliance reminders, behavioral instructions). Security-critical rules belong in settings — CLAUDE.md shapes Claude's behavior but is not a hard enforcement layer.

Monorepo strategy: Root file defines WHEN; subtree files define HOW.

root/CLAUDE.md           # Universal: tech stack, git workflow
apps/web/CLAUDE.md       # Frontend-specific
apps/api/CLAUDE.md       # Backend-specific

Rules Directory

The .claude/rules/ directory splits instructions into focused markdown files.

• Use .claude/rules/ when: many concerns, different rules for different file types, team maintains different areas
• Use CLAUDE.md when: tiny project, universal rules, single source of truth
• Combine both (hybrid) for most projects — CLAUDE.md stays slim and indexes conditional rules with ordinary links; use eager @ imports only for universal content. See Workflow > Storage Strategy below for when to pick which.

Path-scoped rules use YAML frontmatter:

---
paths:
  - "src/api/**/*.ts"
---
# API Rules
- All endpoints must include input validation

Supported patterns: **/*.ts, src/**/*, src/**/*.{ts,tsx}, {src,lib}/**/*.ts

Rules without paths frontmatter load unconditionally.

See references/rules-directory-guide.md for the complete guide including symlinks, user-level rules, and migration.

Content Structure

Optional sections and six candidate bloat categories to review (linter rules, agent-discoverable, marketing/vision, redundant specs, verbose prose, generic best-practices): references/optimize-guide.md.

CLAUDE.md-specific writing rules

The canonical Writing rules block above carries the universal prose rules. The rules below add what is specific to authoring CLAUDE.md and .claude/rules/ files — directive phrasing, emphasis discipline, HTML-comment behavior under context injection.

Golden rule: If someone with zero project context reads your CLAUDE.md and gets confused, Claude will too.

Be specific, never vague:

❌ "Format code properly" / "Write good tests" / "Follow best practices"
✅ "Run `pnpm lint` before committing" / "Tests in `__tests__/` using Vitest"

Be directive; reserve prohibitions for real constraints:

❌ "Try to use TanStack Form for forms"
✅ "Use TanStack Form for all forms (not native form/useState)"

Lead with the action. Keep NEVER for genuine constraints — secrets, data loss, breaking changes — not ordinary preferences.

Show, don't tell: When format matters, show a concrete example (3–5 lines max).

HTML comments: Block-level <!-- comments --> are stripped from CLAUDE.md before injection into context. Use them for human-only maintainer notes without spending tokens. Comments inside code blocks are preserved.

Emphasis, sparingly: Reserve bold + a single keyword for non-negotiable rules (**Never commit secrets**).

• Put critical rules first in each section — placement beats emphasis.
• Don't stack CRITICAL/MUST/ALWAYS on ordinary guidance. Current models follow instructions literally, so over-emphasis dilutes the rules that matter and can overtrigger.

See references/prompting-techniques.md for advanced techniques.

Size Limits

Target under 200 lines per file. This official guideline is a review signal, not a measured universal adherence threshold.

When exceeding, split via @path imports or .claude/rules/:

# API patterns
@docs/api-patterns.md

# Testing
@docs/testing-guide.md

Imports load eagerly at launch alongside the referencing file. Relative and absolute paths work, ~ expands to home, maximum depth is four hops. External imports (outside the project) trigger a one-time approval dialog on first encounter.

Auto Memory

Auto memory layout, loading caps, settings keys, env overrides, and subagent memory: references/auto-memory.md.

Workflow

Storage strategy: Preserve the established owner and layout for an authorized update. For a new file, use the simplest layout that fits the brief: a single file for universal guidance, or a slim index plus .claude/rules/ for conditional concerns. Ask only when a material storage migration or user-owned decision is unresolved. An audit request remains read-only; explicit memory permissions still apply.

Use ordinary links for path-scoped rules so they remain conditional. Eager @ imports load universal content and do not provide progressive disclosure.

CLAUDE.md and non-path-scoped .claude/rules/*.md load at launch; path-scoped rules (paths: frontmatter) load on-demand when Claude reads matching files. Either way the slim-hub pattern doesn't lose content, it places it in focused files instead of one long CLAUDE.md.

Creating new memory:

1. Start with /init or minimal template
2. Add tech stack and commands first
3. Add rules only as you encounter friction
4. Test with real tasks, iterate based on Claude's behavior

Maintaining:

1. Review quarterly or when project changes significantly
2. Remove outdated instructions
3. Add patterns that required repeated explanation
4. Ask Claude to edit CLAUDE.md directly, or open it via /memory

Troubleshooting:

Problem	Solution
Claude ignores instructions	Check specificity and placement first — move the rule to the top of its section; add one emphatic marker only for a genuine constraint
Context overflow	Use host compaction and recover task state; split conditional guidance into .claude/rules/
Instructions conflict	Consolidate, use hierarchy (root vs subtree)
Path rules not applying	Verify glob pattern matches target files
Debug which instructions load	Use the InstructionsLoaded hook to log files, timing, and reasons
Monorepo picks up irrelevant files	Add claudeMdExcludes glob patterns in .claude/settings.local.json
Memory files not loading from --add-dir	Set CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 — --add-dir alone gives file access, this env var adds CLAUDE.md/rules loading
CLAUDE.md guidance ignored for security-critical rules	CLAUDE.md is guidance, not enforcement. Use applicable permission, sandbox or hook enforcement; adding system-prompt text does not enforce a security boundary

Tips:

• Set CLAUDE_CODE_NEW_INIT=1 before /init for an interactive multi-phase flow (explores codebase with subagent, asks follow-up questions, presents reviewable proposal)
• Instructions survive /compact — project-root CLAUDE.md is re-read from disk and re-injected. Nested CLAUDE.md files reload on-demand the next time Claude reads a file in that subdirectory.

Subcommands

The skill supports three argument-driven workflows via $ARGUMENTS. $SKILL_DIR = this skill's folder — ${CLAUDE_SKILL_DIR} in Claude Code, the directory containing this SKILL.md elsewhere. Load the matching step file when the argument is present:

• init — Scaffold a minimal CLAUDE.md: detect the project, preserve established rules, then draft and write within the user's authorized scope. See steps/init.md. Optional layout scaffold: bash "$SKILL_DIR"/scripts/init_structure.sh <mode> writes starter rule stubs — use only when the user asks for a pre-seeded layout.
• optimize — Deep cleanup of a bloated CLAUDE.md. See steps/optimize.md. Always start with python3 "$SKILL_DIR"/scripts/audit_claude_md.py <path> — the JSON report contains candidates requiring semantic review. Read references/optimize-guide.md for the WHY behind each category.
• revise — Capture session learnings into CLAUDE.md. See steps/revise.md.

Without a subcommand, treat the argument as free-form guidance about memory files and answer from the sections above.

Reference Guides

• Optimization guide: references/optimize-guide.md — evidence-guided bloat review, 6 removal categories, before/after examples
• Rules directory: references/rules-directory-guide.md — complete .claude/rules/ guide with path-scoping, YAML syntax, symlinks, migration
• Prompting techniques: references/prompting-techniques.md — emphasis strategies, clarity techniques, constraint patterns
• Section templates: references/section-templates.md — copy-paste templates for each section type
• Full example: references/full-example.md — compact project-specific CLAUDE.md example
• Project patterns: references/project-patterns.md — Next.js, Express, Python, Monorepo patterns
• Auto memory: references/auto-memory.md — layout, loading caps, settings keys, env overrides, subagent memory
• Script schemas: references/schemas.md — JSON / RESULT shapes for the three deterministic scripts (audit, validate, init)

Deterministic scripts

• scripts/audit_claude_md.py — line-count + 6-category bloat scan + @import resolver. Run first for optimize — the JSON output proposes review candidates; revise consults it when drift is suspected. Python 3.7+.
• scripts/validate_rule_file.py — frontmatter delimiter + supported YAML paths: glob subset validator for .claude/rules/*.md; other YAML keys are not validated. Quote globs beginning with *, ! or other YAML indicators. Python 3.7+.
• scripts/init_structure.sh — idempotent scaffold for the three storage strategies (single, hybrid, rules-only). Preserves existing files by default; --force replaces them and requires applicable authorization.

See also

• /agent-creator — subagent configuration and orchestration. A CLAUDE.md that defines project-wide instructions often pairs with .claude/agents/*.md files; use /agent-creator to author those.

About

claude-md contains the substring claude, reserved by this repository's naming policy. The local exception covers first-party filename conventions: this skill operates directly on CLAUDE.md. The restriction and exception are repository policy, not agentskills.io requirements.