What is CLAUDE.md?

Recipe Book for Claude

Just like a recipe book tells a chef what to do, CLAUDE.md tells Claude how to work on your project.

Recipe Book tells Chef:

1 What ingredients to use (tools, frameworks)

2 How to prepare dishes (coding standards)

3 Kitchen rules (what to avoid)

CLAUDE.md tells Claude:

1 Project context (tech stack, structure)

2 Coding standards (naming, patterns)

3 Workflows (how to plan, test, deploy)

Note: Rules are guidance, not enforcement — Claude may miss them. For guaranteed behavior (auto-format, block dangerous commands), use Hooks or Permissions in settings.json.

Config Hierarchy

How Config Files Stack

Claude loads config in 4 steps. All files are concatenated (not overridden).

1

Global user config ~/.claude/CLAUDE.md

Global user config — applies to all projects

2

Project config (walk-up) <project>/CLAUDE.md + CLAUDE.local.md

Project config (walk-up from CWD to git root)

3

Rules (user → project) ~/.claude/rules/*.md → .claude/rules/*.md

User rules first, then project rules (concatenated)

4

Auto-memory ~/.claude/projects/<project>/memory/MEMORY.md

Auto-memory from past sessions (persistent)

Order: Global → Project → Rules → Memory

All files are concatenated — not overridden. Later files add context, they don't replace earlier ones.

Path-specific rules (advanced)

Place a CLAUDE.md inside a subfolder so its rules apply only when Claude edits files in that folder. Great for monorepos where frontend/backend have different conventions.

project/
├── CLAUDE.md           # Applies to entire project
├── frontend/
│   └── CLAUDE.md       # Loaded only when Claude edits in frontend/
└── backend/
    └── CLAUDE.md       # Loaded only when Claude edits in backend/

`ck init` — What It Creates

$ ck init --kit engineer

When you run ck init, ClaudeKit downloads and installs a complete kit to your project.

project/

CLAUDE.md Template (customize after)

AGENTS.md Agent definitions

.gitignore

.repomixignore Repomix ignore patterns

release-manifest.json Kit version manifest

plans/ Plans directory

.opencode/ OpenCode compatibility

.claude/ ClaudeKit config

.ck.json Kit metadata

settings.json Claude Code settings

metadata.json Deletion patterns

statusline.cjs Statusline config

.env.example Environment template

.mcp.json.example MCP config template

agents/ 14+ definitions

hooks/ 22+ hooks

rules/ Workflow rules

skills/ 90+ commands

scripts/ Utility scripts

schemas/ JSON schemas

output-styles/ Response formats

session-state/ Session tracking

✓ Kit installed successfully

Common Flags:

--kit engineer Which kit to install

-g, --global Install to ~/.claude/ — applies to ALL projects on your machine (instead of just the current one)

--fresh Reset CK files in .claude/ (agents, skills, rules, hooks) + settings.json.
• Project-mode: root CLAUDE.md preserved.
• Global-mode (-g): ~/.claude/CLAUDE.md replaced.

Kit Config vs Your Config

ClaudeKit Files

Don't edit directly!

Managed by ClaudeKit

.claude/skills/*
.claude/hooks/*
.claude/agents/*
.claude/settings.json

Your Files

Safe to edit!

Your customizations

CLAUDE.md (your additions)
.claude/rules/*
CLAUDE.local.md
.env (gitignored)

Common Confusions

By default, ck init merges configs and doesn't overwrite existing files. Only --fresh flag does full reset.

Create files in .claude/rules/ directory. ClaudeKit won't overwrite these. Or add to CLAUDE.local.md for personal, gitignored preferences.

ck init -g → ~/.claude/ (applies to ALL projects). ck init → ./.claude/ (this project only). Start with local, use global only for truly universal preferences.

No. Rules are guidance — Claude tries to follow them but may miss some. For 100% guarantees (blocking dangerous commands, auto-formatting before commit), use Hooks or Permissions in .claude/settings.json.

Under 200 lines is ideal. The shorter and more specific, the easier for Claude to follow. Move longer content into .claude/rules/*.md and link from CLAUDE.md via @-references.

Still confused? Check out the "How ClaudeKit Works" guide for a deeper dive into how skills and hooks work together.

Claude Mechanics