Claude Md Rules Creator

CLAUDE.md and Rules Creator

You are about to write or edit a CLAUDE.md, CLAUDE.local.md, or .claude/rules/*.md file. At runtime these three shapes are the SAME content type: Claude Code's memory loader discovers them, concatenates them with a fixed MEMORY_INSTRUCTION_PROMPT prefix, and the API layer prepends the result as a single <system-reminder> user message before the conversation starts. The model treats them all the same; the file shape just controls when each loads and how a human maintains it.

This skill is the playbook for picking the right shape, choosing the right scope, writing content that actually changes behavior, splitting bloated files, using @path imports, and debugging "Claude is not following my CLAUDE.md". Target is Opus 5. Same rules work for Sonnet 5 at lower cost and for Haiku 4.5, which supports no effort parameter.

Three jobs, not one

Writing a CLAUDE.md or rule splits into three tasks. Conflating them is the most common authoring mistake.

1. Surrounding skill shape. None. CLAUDE.md and .claude/rules/*.md are not skills, not commands, not agents. They are plain markdown files the memory loader picks up. No frontmatter fields apply except paths: (only on .claude/rules/*.md). Route through ac:skill-creator ONLY if you are wrapping CLAUDE.md authoring inside a custom slash command or skill.
2. CLAUDE.md / rule shape. Where the file lives (managed / user-global / project-team / project-personal), what file name (CLAUDE.md / CLAUDE.local.md / .claude/rules/<topic>.md), paths: frontmatter for rules, @path imports, HTML comments. This file teaches that.
3. Body content. The markdown text the model reads. This is a standing instruction set, a prompt at runtime. Route through ac:prompt-writer for prompt architecture, snippets, and Opus 5 tuning.

A great body in the wrong file shape (oversized, wrong scope, missing paths:, leaks personal preferences into a team file) never produces consistent behavior. A modest body in the right shape, sized below the adherence cliff, changes behavior every session.

What CLAUDE.md actually is, mechanically

The lifecycle:

1. Discovery. At session start, the loader walks: managed → user → project (root → cwd) → local → AutoMem/TeamMem. Within each project directory: CLAUDE.md first, then .claude/CLAUDE.md, then .claude/rules/*.md (unconditional only - files without paths: or with paths: ['**']), then CLAUDE.local.md.
2. Frontmatter strip + HTML comment strip. Each file's content is processed: YAML frontmatter is parsed (only paths: is meaningful), and block-level HTML comments (<!-- ... -->) are stripped. Comments inside fenced code blocks survive. Inline HTML comments inside paragraphs survive.
3. Conditional rule deferral. .claude/rules/*.md files WITH a paths: frontmatter are held back from the initial concatenation. They activate later when Claude reads a file matching their glob.
4. Concatenation. Eligible files are formatted as Contents of <absolute-path><description>:\n\n<content> (description varies by type - "user's private global instructions for all projects", "project instructions, checked into the codebase", "user's private project instructions, not checked in", "user's auto-memory, persists across conversations"). All entries are joined with \n\n, prefixed with MEMORY_INSTRUCTION_PROMPT.
5. Injection into the API call. The concatenated string becomes the claudeMd field of the user context. The runtime wraps it together with currentDate inside a <system-reminder> block and prepends it as the first user message of the API call, with isMeta: true (the UI hides it; the model sees it). The trailing line softens the authority: "this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant to your task."
6. Compact behavior. On /compact or auto-compact, the runtime wipes the memory-file cache. The NEXT turn re-reads project-root CLAUDE.md, CLAUDE.local.md, and unconditional rules from disk and re-injects them. Path-scoped rules and nested-subdir CLAUDE.md files lazy-loaded into message history during the session are summarized away and reload only on the next matching file touch.

The model NEVER sees CLAUDE.md as the system prompt. It sees a <system-reminder>-wrapped meta-message that says "you can use the following context". This is the single most-misunderstood mechanic; debugging "Claude is not following my CLAUDE.md" always starts here.

Decision flow

Route by the user's request.

Is CLAUDE.md / rules the right tool at all?
├── Single fact never changes; behavior must hold every session → CLAUDE.md, continue.
├── Workflow with steps, invocable on demand → SKILL, route through `ac:skill-creator`.
├── User-typed `/name [args]` action → COMMAND, route through `ac:command-creator`.
├── Deterministic guarantee (must fire on every edit, no model judgment) → HOOK, configure in settings.json.
├── Custom-context worker → SUBAGENT, route through `ac:agent-creator`.
└── Standing rule, conventions, what-to-avoid, project facts → CLAUDE.md / rule, continue.

Which file shape inside the CLAUDE.md layer?
├── Universal rule, every session needs it, file stays under 200 lines → inline in `./CLAUDE.md` (project) or `~/.claude/CLAUDE.md` (user).
├── Personal override of a team rule → `./CLAUDE.local.md` (project-personal, gitignored).
├── Topic-focused team rule, want its own file → `./.claude/rules/<topic>.md` (no `paths:`, loads at session start).
├── Path-conditional rule (only matters in `src/api/`, only frontend, only migrations) → `./.claude/rules/<topic>.md` with `paths:` frontmatter.
├── Personal preference across all projects → `~/.claude/CLAUDE.md` or `~/.claude/rules/<topic>.md`.
└── Org-wide policy → managed CLAUDE.md (admin deploys).

Is this an audit or fix of an existing file?
├── YES → read `${CLAUDE_SKILL_DIR}/references/anti-patterns.md` first, then the specific reference as the symptom dictates.
└── NO → walk the Workflow below.

Frontmatter: only one shape takes any

CLAUDE.md and CLAUDE.local.md have NO frontmatter. They are pure markdown. Anything that looks like YAML at the top is treated as content.

.claude/rules/<topic>.md files accept ONE frontmatter field: paths:.

Everything else (name, description, model, effort, etc.) is ignored by the memory loader. Do not add fields that mean nothing in this context.

Escape convention used in this documentation. This SKILL.md is itself a skill body inside a plugin. The Claude Code loader substitutes plugin-context tokens before injecting the body. Real path references in this file using ${CLAUDE_SKILL_DIR}/references/<file>.md stay literal so the loader resolves them to actual files the model can Read. Documentation-context references that NAME the tokens without using them use the HTML entity $ so the docs survive intact. In CLAUDE.md and rule files you author, none of this applies, those files do not go through any substitution pass; tokens stay literal.

Where each file lives (verified paths)

The asymmetry to remember: USER rules live one level shallower than PROJECT rules. User: ~/.claude/rules/<topic>.md. Project: <dir>/.claude/rules/<topic>.md.

The four scopes

The runtime treats CLAUDE.md content identically regardless of scope. The scopes differ in WHO sees the file and WHEN it gets loaded.

The litmus test: if the team gets value from this rule, it is project-team. If it is yours alone, it is user-global (cross-project) or project-personal (this project only). Org-wide compliance and security rules go to managed policy.

Full scope deep-dive, AGENTS.md interop, worktree handling, monorepo claudeMdExcludes, and --add-dir behavior: ${CLAUDE_SKILL_DIR}/references/scopes.md.

Core principles

These nine rules drive every authoring decision. Detail and source in the references.

1. Concise wins adherence. Anthropic's docs target "under 200 lines per CLAUDE.md". Adherence drops as files grow; over 200 lines the model notices less of what is there. The hard cap is 40,000 characters per file (MAX_MEMORY_CHARACTER_COUNT in the loader).
2. Specificity beats vagueness. "Use 2-space indentation in TypeScript" beats "format code properly". "Run pnpm test before committing" beats "test your changes". "API handlers live in src/api/handlers/" beats "keep files organized". The instruction must be concrete enough for the model to verify and apply.
3. The "would removing this cause Claude to make mistakes?" test. Apply to every line. If the answer is no, cut it. CLAUDE.md is paid by the token on every request in the project; lines that do not change behavior are pure tax.
4. No aspirations. "We aim for 90% test coverage" is not a rule the agent can enforce, and trying to satisfy aspiration produces irrelevant work. Write what is actually true and enforced. If it is true in CI, say what runs in CI.
5. Standing instructions, not conversation echoes. CLAUDE.md is read once at session start (and re-injected after compact for project root). It must read sensibly cold. Avoid "as we discussed", "for this turn", "remember from last time".
6. Match the scope to the audience. Project-team CLAUDE.md is shared via git; write what the team agrees on. User-global is yours alone. Project-personal CLAUDE.local.md is your private fixture for this repo. Rules leaking into the wrong scope is the most common source of friction.
7. Point at sources of truth; do not duplicate them. A one-line @docs/architecture.md import beats a ten-line summary that drifts. Use @path imports for content that lives elsewhere. Never inline answers that change faster than the file.
8. No aggressive caps. "CRITICAL", "you MUST", "ALWAYS" wording produces compliance brittleness on modern Claude. The runtime already prepends MEMORY_INSTRUCTION_PROMPT which contains an explicit "IMPORTANT: These instructions OVERRIDE any default behavior and you MUST follow them exactly as written." Your file does not need to repeat that authority; state the rule plainly.
9. Audit the existing layered context before writing. Your new content does not land alone. It joins a stack: CC's built-in system prompt + managed CLAUDE.md + user-global + project + local + auto memory + path-scoped rules. Adding a rule that the CC system prompt already provides ("no comments unless non-obvious", "reference code as file:line") or that another layer already covers is pure tax. Do not add "be concise" to that list: it is built by the classic prompt shape only, and ${CLAUDE_SKILL_DIR}/references/layered-context.md records which model shapes reach it. Adding a rule that contradicts a higher-precedence layer creates a silent conflict. Before writing, run /memory to see what is already loaded, Grep the loaded files for the topic, and decide one of three actions: skip (already covered), edit in place (existing file is wrong/outdated), or move to the right scope. See ${CLAUDE_SKILL_DIR}/references/layered-context.md for the audit protocol and the "do not restate" cheat sheet covering ~12 CC built-in defaults.

Choosing the file shape inside the CLAUDE.md layer

A 400-line CLAUDE.md and four 100-line .claude/rules/<topic>.md files (all loaded unconditionally, no paths:) have identical token cost and identical model behavior. Splitting is for human maintainability, plus the option to add paths: to scope a rule to part of the codebase.

Two caveats worth front-loading:

• Path-scoped rules and nested CLAUDE.md files do NOT survive compaction the same way. They are injected into message history when triggered (not into the user-context message), so compact summarizes them away. They reload only when Claude next reads a matching file. If a rule MUST hold across compact, drop paths: or move it to project-root CLAUDE.md.
• Subdirectory CLAUDE.md (e.g., packages/web/CLAUDE.md when cwd is the monorepo root) loads on demand the same way. Useful for monorepo per-package rules without bloating root context.

Full splitting strategy, topic-file naming conventions, and paths: glob design: ${CLAUDE_SKILL_DIR}/references/rules-writing.md.

Five questions every project CLAUDE.md should answer

A pragmatic frame:

1. What is the stack? One paragraph: language, framework, runtime, package manager.
2. Where does code live? Top-level directories with one-line meanings - only when non-obvious.
3. How do I run things? Dev server, tests, lint, type-check, build, deploy. Exact strings.
4. What are the conventions? Style rules that differ from defaults, naming patterns, architectural rules.
5. What is off-limits? "Do not edit migrations/", "never push directly to main", "do not run npm install (use pnpm)".

If your CLAUDE.md does not answer these five, add the missing ones. If it answers more than five, audit whether the extras pull weight. Full INCLUDE/EXCLUDE coverage with examples: ${CLAUDE_SKILL_DIR}/references/content-rules.md.

@path imports

The loader recognizes a @path syntax for splitting content across files (four hops of importing):

• Syntax: @path, @./relative, @~/home, @/absolute. The regex requires whitespace or start-of-line before the @.
• Imports recurse up to four hops. The loader's MAX_INCLUDE_DEPTH = 5 (utils/claudemd.ts:537) is an exclusive bound on a zero-indexed depth (:630, depth >= MAX_INCLUDE_DEPTH), so levels 0 through 4 are processed and four levels of importing land; the docs state the same as "a maximum depth of four hops". Cycles are detected and broken via path tracking.
• Only text-file extensions (~70 are listed) - .md, .txt, .json, .ts, .py, etc. Binary files (images, PDFs) are silently skipped.
• Imports inside fenced code blocks and codespans are NOT followed (the marked lexer respects token boundaries).
• Imports inside block-level HTML comments are NOT followed (comments are stripped before lex).
• Fragment identifiers (@path#heading) are stripped before resolution.
• External imports (paths outside cwd) trigger a one-time approval dialog the first time the runtime sees them, except in User memory which always permits externals.

Use imports to point at sources of truth (@docs/architecture.md, @AGENTS.md, @README.md), share personal content across worktrees (@~/.claude/<project>-instructions.md), and avoid duplicating long content. Imports help organization - they do NOT reduce context cost; imported content lands in context the same as inlined content.

Full syntax, edge cases, and the claudeMdExcludes setting for monorepo path filtering: ${CLAUDE_SKILL_DIR}/references/imports-and-paths.md.

HTML comments for human-only notes

Block-level <!-- ... --> comments are stripped before injection. Use them for maintainer notes that should not consume tokens:

<!-- Maintainer note: keep this section under 30 lines, adherence drops past that. -->
## Testing

- Run `pnpm test` before committing.

Stripping rules: block-level only (CommonMark type-2 HTML block). Comments inside fenced code survive (they are part of code's literal content). Inline comments inside paragraphs survive. Unclosed <!-- is left intact so a typo does not silently eat the rest of the file.

Quick recipes

Common user requests mapped to the action this skill takes. Use these as pattern-match shortcuts before falling through to the full Workflow.

Workflow

Walk these in order.

1. Audit the existing layered context

Before any drafting, run /memory to list every CLAUDE.md, CLAUDE.local.md, and rule file currently loaded. Then for the topic of the new rule:

• Grep the loaded files for keywords related to the topic.
• Check the CC built-in system prompt list in ${CLAUDE_SKILL_DIR}/references/layered-context.md for overlap. If a default already covers it, skip.
• For each existing mention, decide one of three: skip (already covered at the right scope), edit in place (existing file is wrong/outdated), or move to the right scope (rule is in the wrong layer; e.g., team rule in user-global).
• Check for conflicts: does the new rule contradict any existing layer? If yes, either drop one, or explicitly call out the override in the higher-precedence file.

Concrete audit walkthrough. User says: "Add to CLAUDE.md that we always use pnpm not npm." Walk the audit:

1. Run /memory. See files loaded: ~/.claude/CLAUDE.md, ./CLAUDE.md, ./.claude/rules/testing.md, ./CLAUDE.local.md.
2. Grep them for pnpm and npm. Found in ~/.claude/CLAUDE.md: "Prefer pnpm over npm, uv over pip."
3. Cross-check CC built-in defaults: package-manager preference is NOT in the CC system prompt cheat sheet. Not a duplicate with CC.
4. Decision: user-global already covers it FOR YOU. But teammates may have different user-globals (or none). If the team needs ENFORCEMENT, the rule belongs in project ./CLAUDE.md (committed, every contributor gets it). If it is just your personal preference, user-global is enough.
5. Ask the user: "Your ~/.claude/CLAUDE.md already says 'prefer pnpm over npm'. Do you want this enforced for the whole TEAM (commit to ./CLAUDE.md), or is your user-global rule enough?"
6. Based on the answer: skip (user-global is enough), or write to ./CLAUDE.md with sharper wording ("Use pnpm. Do NOT run npm install.") + attribution comment + verify with /memory after.

Skipping this audit step is the single most common cause of "Claude is not following my CLAUDE.md" complaints later. The model is usually not ignoring the rule; two layers are saying different things and the model is reconciling badly.

2. Capture intent

Always-needed questions:

• What is the rule, in one sentence?
• Does the team need it, or just you?
• Universal, or only relevant when working on specific paths?
• Editing an existing file, or starting fresh?

Conditional questions (ask only when intent surfaces a need):

• Is this a multi-step procedure? If yes, route to ac:skill-creator instead - CLAUDE.md is not the right shape.
• Must this fire on every edit deterministically? If yes, this is a hook, not CLAUDE.md.
• Is it really a fact the agent already knows? (Language defaults, common framework idioms.) If yes, cut it; do not write.

Do not pre-ask every option; pull each in only when intent makes it relevant.

3. Pick the shape

Use the "Choosing the file shape" table above. Default to inline in ./CLAUDE.md until size or path-scoping pushes you toward .claude/rules/.

4. Pick the scope

Use the "Four scopes" matrix above. Litmus test: if the team gets value, project-team; otherwise user-global or project-personal.

5. Draft the file

Lead every generated file with a block-level HTML attribution comment so a human reader knows where the file came from and when. The comment is stripped at injection time (stripHtmlComments removes block-level <!-- ... -->), so it costs ZERO tokens for the model but stays visible when a human opens the file with Read or in an editor. Substitute the actual ISO date.

<!-- Generated by ac:claude-md-rules-creator on YYYY-MM-DD. This comment is block-level HTML, stripped before injection: zero token cost for the model, visible when a human opens the file. -->

Then for project-team ./CLAUDE.md, add the canonical preface (the /init command uses this exact form):

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Then the rules. Markdown headers (##) and bullets. One rule per bullet, specific and verifiable. Lead with the highest-value sections - they get the most weight when the file is read top-to-bottom.

For .claude/rules/<topic>.md, decide the paths: shape first:

<!-- Generated by ac:claude-md-rules-creator on YYYY-MM-DD. -->
---
paths:
  - "src/api/**/*.ts"
  - "tests/api/**/*.ts"
---

# API Conventions

- Endpoints validate input with Zod schemas in `src/api/schemas/`.
- Return errors as `{ error: { code, message } }`. Never bare strings.
- Log requests with `requestId`, `userId`, `endpoint`. Never log tokens.

For CLAUDE.local.md, no preface needed. Just rules. Personal preferences, sandbox URLs, test data overrides, communication preferences.

Templates at ${CLAUDE_SKILL_DIR}/assets/:

• CLAUDE.template.md - project-team starter with the canonical preface.
• CLAUDE.local.template.md - project-personal starter.
• global-CLAUDE.template.md - ~/.claude/CLAUDE.md starter.
• rule.template.md - .claude/rules/<topic>.md starter with optional paths: frontmatter.

Hand off the prose-writing details to /ac:prompt-writer. CLAUDE.md content is a standing instruction set; the prompt-writer principles all apply (no aggressive caps, specific verifiable rules, scope stated, structure with headers, no aspirations).

6. Verify

Before declaring it done:

1. Length under 200 lines (soft); 40,000 chars (hard). wc -l and wc -c. If over the soft cap, run the cut/move pass.
2. Every line passes "would removing this cause Claude to make mistakes?" Walk it line by line.
3. No aspirations, no platitudes, no secrets. Skim for "we aim", "always", "good code", credentials.
4. No file-by-file tours, no standard-language conventions. Skim for redundancy with what the model already knows.
5. Every rule is specific enough to verify. Skim for vague verbs like "format properly", "handle errors", "test thoroughly".
6. No conflicts with other CLAUDE.md files in the hierarchy. Run /memory after editing - every file the runtime sees is listed. If you have project-team + project-personal at the same level, scan for contradictions.
7. @path imports resolve. Every imported file exists; circular imports detected by the loader but messy in practice.
8. # CLAUDE.md preface present for project-team file.
9. CLAUDE.local.md in .gitignore for project-personal scope. The /init command adds this automatically when generating the file.
10. For .claude/rules/*.md with paths:, the glob actually matches. Mentally trace a representative file path through your glob.

7. Iterate

Deeper symptom-to-fix mapping and source citations: ${CLAUDE_SKILL_DIR}/references/anti-patterns.md.

Sibling skills (route the surrounding shape)

This skill stays focused on CLAUDE.md / rule files themselves. Route the surrounding work elsewhere.

When the user request implies any row above, do both: invoke the matching creator for shape, then keep this skill loaded for the parts still in the CLAUDE.md layer.

Pre-flight checklist

Always check:

• Layered audit done. /memory was run, loaded files were Grep'd for the topic, the CC built-in system prompt cheat sheet was consulted, and no duplicate or conflict remains with any existing layer.
• Block-level HTML attribution comment at the top: <!-- Generated by ac:claude-md-rules-creator on YYYY-MM-DD. --> with the real ISO date. Stripped at injection (zero token cost), visible when humans Read the file.
• Right scope (managed / user-global / project-team / project-personal).
• Right shape (CLAUDE.md / CLAUDE.local.md / .claude/rules/<topic>.md).
• File at the right path (user rules: ~/.claude/rules/ not ~/.claude/.claude/rules/; project rules: <dir>/.claude/rules/).
• Under 200 lines (soft cap, adherence cliff). Hard cap 40,000 characters. Sweet spot 60 to 120 lines for project-team CLAUDE.md, measured across eight production repositories at a pinned commit SHA: median 105 to 110 lines, six of eight above 80 (redpanda-data/connect 174, alibaba/spring-ai-alibaba 150, archtechx/tenancy 129, jrnl-org/jrnl 108, reidmorrison/semantic_logger 103, confluentinc/vscode 84). The short ones stay short by pointing one line at a deeper document, not by carrying less content.
• Every line passes the "removing this would cause mistakes" test.
• Specific, verifiable rules; no vague verbs.
• No aspirations ("we aim for X"); state what is actually enforced.
• No standard-language conventions or self-evident advice.
• No file-by-file tours; only non-obvious directory roles.
• No credentials, secrets, sensitive data (CLAUDE.md is committed to the repo).
• No aggressive CRITICAL / MUST / ALWAYS repetition (runtime already prepends MEMORY_INSTRUCTION_PROMPT).

Check the items that apply to your file's shape:

• (Project team CLAUDE.md) # CLAUDE.md canonical preface present.
• (CLAUDE.local.md) Listed in .gitignore.
• (.claude/rules/<topic>.md with paths:) Glob actually matches your intent; no paths: ['**'] (treated as no paths:).
• (.claude/rules/<topic>.md without paths:) Topic is universal and one focused subject; not a dumping ground.
• (Imports) @path references resolve; no chain deeper than four hops; external imports approved if needed.
• (HTML comments) Maintainer notes wrapped in <!-- ... --> are block-level (own line); inline comments survive injection.
• (Run /memory) The file appears in the loaded list. If not, the path is wrong, the scope source is disabled, or claudeMdExcludes is filtering it.
• (Hook command) No secret or credential appears in the hook command string.
• (Hook script) A path-containment guard is present, rejecting any target outside the intended directory.
• (Settings merge) A timestamped backup of the settings file was taken before the merge.
• (Post-write) claude doctor runs clean in the target directory after the write.

References

For the prompt-writing principles that apply to CLAUDE.md prose, invoke /ac:prompt-writer. For deciding between CLAUDE.md vs skill vs command vs agent vs hook, the decision flow above plus the matrix in features-overview cover it.

Canonical Anthropic documentation, served as raw markdown by appending .md to the URL:

• Memory page (CLAUDE.md, rules, auto memory): https://code.claude.com/docs/en/memory.md
• Features overview (CLAUDE.md vs skills vs rules vs hooks): https://code.claude.com/docs/en/features-overview.md
• Context window (what survives compaction): https://code.claude.com/docs/en/context-window.md
• Hooks (InstructionsLoaded event for debugging): https://code.claude.com/docs/en/hooks.md
• Settings (claudeMdExcludes, --setting-sources): https://code.claude.com/docs/en/settings.md

When canonical docs conflict with observed CLI behavior, trust the live binary.