claude-md

name	claude-md
description	Create and optimize CLAUDE.md memory files or .claude/rules/ modular rules for Claude Code projects. Covers file hierarchy, content structure, path-scoped rules, best practices, and anti-patterns. Use when working with CLAUDE.md files, .claude/rules directories, setting up new projects, or improving Claude Code's context awareness — even when the user just says "memory file" or mentions Claude instructions without naming the filename.
when_to_use	When the user wants to create, clean up, or update Claude Code memory files. Routes via `$ARGUMENTS` — `init` (scaffold minimal CLAUDE.md), `optimize` (deep cleanup of bloat), `revise` (capture session learnings). Keywords — CLAUDE.md, memory file, instructions file, .claude/rules, optimize CLAUDE, init CLAUDE, revise CLAUDE, auto memory, MEMORY.md, subagent memory. Without a subcommand, treat the argument as free-form guidance about memory files. Skip for subagent system prompts and .claude/agents/ configs — use /agent-creator.
argument-hint	["init | optimize | revise | task description"]
license	MIT
compatibility	Optimized for Claude Code; degrades gracefully on any agent implementing the Agent Skills standard.
metadata	{"author":"coroboros","sources":["code.claude.com/docs/en/memory","github.com/anthropics/claude-plugins-official/tree/main/plugins/claude-md-management","github.com/Melvynx/aiblueprint"]}

CLAUDE.md

Important — Writing rules

These rules govern every prose artifact this skill emits — READMEs, CHANGELOGs, commit messages, PR bodies, release notes, doc paragraphs, non-trivial comments. Apply them at draft time, verify before output.

• Match the surrounding style — punctuation, capitalization, backtick conventions, em-dash vs parens, bullet style.
• Every sentence changes the reader's understanding. Cut it otherwise.
• Front-load the verb — "Creates", not "This helps you create".
• Concrete over abstract. Lists for ≥3 enumerable items.
• 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.
• After drafting English prose, invoke /humanize-en if installed.

Core Principle

Memory files consume tokens every session. Keep them minimal — include only what the agent cannot discover on its own or what a tool doesn't already enforce (linter, TypeScript, tests).

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 @-imports the active rules, giving humans a visible TOC while the rules carry the 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

The 6 sections every CLAUDE.md should have and the 6 bloat categories to avoid (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. Longer files consume more context and reduce adherence — directives start getting lost.

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 5 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

ALWAYS ASK FIRST: Storage Strategy

Before creating or updating memory files, use AskUserQuestion:

• Option 1: Single CLAUDE.md — tiny project, one file carries everything
• Option 2: Hybrid (CLAUDE.md slim + .claude/rules/) (recommended default) — CLAUDE.md stays small: intro + @-imports of the active rules + a short At a glance for repo-specific divergences. Rules carry the actual content and can be path-scoped. Zero duplication, since rules load eager and CLAUDE.md doesn't repeat them.
• Option 3: Mostly .claude/rules/ — every rule is path-scoped and CLAUDE.md has nothing universal worth stating at the top level.

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 /clear, split 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 --append-system-prompt for strict-compliance automation, or push rules into permissions.deny/sandbox.enabled settings

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, draft the file, write after user approval; the Rules section starts empty. 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 hit-list is your fix list. 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 — research-backed bloat checklist, 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 — full production SaaS CLAUDE.md
• 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 is your hit-list; revise consults it when drift is suspected. Python 3.7+.
• scripts/validate_rule_file.py — YAML frontmatter + paths: glob validator for .claude/rules/*.md. Python 3.7+.
• scripts/init_structure.sh — idempotent scaffold for the three storage strategies (single, hybrid, rules-only). Never overwrites.

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 reserved substring claude. This is intentional: the agentskills.io open standard reserves anthropic / claude in skill names but permits a narrow exception for first-party filename conventions, declared in the skill body. This skill operates directly on the first-party CLAUDE.md filename; alternatives (memory-md, ctx-md) lose essential semantic clarity.