CLAUDE.md: where it goes, what to write, and how it works with AGENTS.md

What CLAUDE.md is

Claude Code starts every session without memory of the last one. CLAUDE.md is how you give it the context a new teammate would need: it's read at launch and sent to Claude as a message after the system prompt. That makes it context, not enforced configuration. Claude usually follows it, but anything that must always or never happen belongs in hooks or permission rules.

• Plain markdown, no required fields: headings and short bullets work best.
• Files are combined, not overridden: every CLAUDE.md that applies is loaded, so contradictory lines leave Claude to pick one.
• Check what loaded with /context all, under Memory files.

Where CLAUDE.md files go, and the order they load

Claude Code loads these from broadest to most specific, so the file closest to where you launched is read last. It also walks up from your working directory and loads a CLAUDE.md from every parent directory.

How to write a CLAUDE.md that works

1. Start with /init

   Run /init in your project. Claude Code reads the codebase and writes a starter CLAUDE.md; if one exists, it suggests improvements instead of overwriting it. It also picks up .cursorrules and Copilot instructions.

2. Cut it to what Claude can't find on its own

   Keep the exact build, test and lint commands (including how to run one test), the places where the code is misleading, decisions that aren't written down anywhere, and anything you've had to correct twice. Remove file trees and architecture Claude can read from the repo. Anthropic suggests staying under 200 lines.

   # Commands
   - Install: pnpm install
   - One test file: pnpm vitest run path/to/file.test.ts
   - Typecheck: pnpm tsc --noEmit
   
   # Conventions
   - Throw errors with the helpers in src/lib/errors.ts, never raw strings.
   - src/legacy/ is still live, but don't copy its patterns.
   
   # Gotchas
   - Integration tests need DATABASE_URL (see .env.example).

3. Be specific, without shouting

   Write "Use 2-space indentation", not "Format code properly". The current docs say IMPORTANT and ALL CAPS are outdated advice: they make Claude over-apply a rule. If a line keeps being missed, shorten the file or turn the rule into a hook.

4. Split it with imports and rules

   @path/to/file imports another file (relative to the importing file, up to four levels deep); an @ inside backticks stays literal. Rules that apply to part of the codebase go in .claude/rules/ with a paths glob, so they load only when Claude touches matching files.

   ---
   paths: ["src/api/**/*.ts"]
   ---
   - Every handler validates its input with the schema in src/api/schemas/.

5. Move procedures into skills

   Multi-step workflows, such as how to cut a release, belong in a skill (.claude/skills/<name>/SKILL.md), which loads only when it's relevant. CLAUDE.md is read on every task, so every line costs attention.

6. Keep it current

   Add a line when Claude repeats a mistake or a review catches something, and edit the file with /memory or by asking Claude to update it. /doctor proposes trims when the file grows too long.

Source: Claude Code docs, How Claude remembers your project

CLAUDE.md vs AGENTS.md

AGENTS.md is an open format for instructions to coding agents, used by Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, opencode and many others. Claude Code now reads it too, but by default only when the project has no CLAUDE.md.

Using one file for Claude Code and Codex

If your team runs both agents, keep the shared instructions in AGENTS.md and make CLAUDE.md import it, with Claude-only notes underneath. It never loads twice. A symlink (ln -s AGENTS.md CLAUDE.md) also works, but not for teammates on Windows, and a CLAUDE.md that only says "read AGENTS.md" in words isn't reliable.

• This website's own repository does exactly that: its CLAUDE.md is the single line @AGENTS.md.
• Codex reads AGENTS.md files from the repository root down to your working directory, and caps their combined size at 32 KiB by default.

Limits and gotchas

• A CLAUDE.md that loads at launch is read whole up to 4 MiB; a bigger file is skipped.
• Files that load on demand, such as subdirectory CLAUDE.md files and path-scoped rules, are cut off past a per-file limit (40,000 characters with a 200K context window).
• Imports organize a file but don't save context: imported text still loads.
• Imports outside the project ask for approval once; HTML comments <!-- --> are stripped and cost nothing.
• The project-root CLAUDE.md is read again after /compact.
• "Remember this" goes to auto memory (~/.claude/projects/<project>/memory/), not to CLAUDE.md.

CLAUDE.md says how to work. Crewmark says what to work on, and when.

A good CLAUDE.md makes every Claude Code session start informed, but the session still waits for your next message. Crewmark turns a Claude Code, Codex, DeepSeek Harness or OpenCode session into an AI employee with a role, a goal and working hours, and wakes it on a heartbeat to take the next issue from a board.

1. Turn a session into an employee

   Pick a role such as software engineer or SEO specialist, write its goal as a number, and run the setup command in your project, where your CLAUDE.md already lives.

2. Let the heartbeat start the work

   During its working hours the employee wakes every 15, 30 or 60 minutes in the same conversation; see how to make Claude Code proactive. Several can share one repository, as in multiple Claude Code agents.

3. Assign issues and answer its messages

   Put work on the board; the employee takes it, comments as it goes and messages you when it needs a decision. Read what an AI employee is.

CLAUDE.md FAQ