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

<!-- canonical:writing-rules:start -->
## 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.
<!-- canonical:writing-rules:end -->

## 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:

```markdown
# 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:

```yaml
---
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](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](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](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/`:

```markdown
# 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](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](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](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](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](references/optimize-guide.md) — research-backed bloat checklist, 6 removal categories, before/after examples
- **Rules directory**: [references/rules-directory-guide.md](references/rules-directory-guide.md) — complete `.claude/rules/` guide with path-scoping, YAML syntax, symlinks, migration
- **Prompting techniques**: [references/prompting-techniques.md](references/prompting-techniques.md) — emphasis strategies, clarity techniques, constraint patterns
- **Section templates**: [references/section-templates.md](references/section-templates.md) — copy-paste templates for each section type
- **Full example**: [references/full-example.md](references/full-example.md) — full production SaaS CLAUDE.md
- **Project patterns**: [references/project-patterns.md](references/project-patterns.md) — Next.js, Express, Python, Monorepo patterns
- **Auto memory**: [references/auto-memory.md](references/auto-memory.md) — layout, loading caps, settings keys, env overrides, subagent memory
- **Script schemas**: [references/schemas.md](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.