CLAUDE.md / AGENTS.md — give Claude memory across sessions
Two markdown files Claude reads on every session start. The single biggest leverage point in your setup.
CLAUDE.md / AGENTS.md
Claude Code, Cursor, and Codex all support a markdown file that gets injected into every session as system context. CLAUDE.md is the Claude Code convention. AGENTS.md is the cross-tool convention (Codex reads it, Cursor reads it). Same content, two filenames — symlink one to the other and you're set for all three.
This is the single biggest leverage point in your whole setup. Without it Claude starts every session from scratch. With it, every session starts already knowing your stack, your conventions, your project layout, and your standing rules.
Step 1: Decide the scope (project vs global)
There are two locations:
- Project-level:
<your-project>/CLAUDE.md— applies only inside that repo. Use this for project-specific things (build commands, schema notes, deploy scripts). - Global:
~/.claude/CLAUDE.md— applies in every session everywhere. Use this for cross-project conventions you always want loaded (writing voice, default tools, "always run tests after a change").
Most setups need both. Start with global if you don't have one yet.
Step 2: Create the file
Run this in a shell:
mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md
For a project file:
touch /path/to/your-project/CLAUDE.md
Step 3: Write the content
Keep it short. Long files get summarized away by the model. Aim for 200-500 lines max.
Good structure:
# Project Name (or "Global Rules")
## What this is
One paragraph on what the project does or what these rules cover.
## Stack
- Language / framework / runtime
- Database
- Deploy target
## Conventions
- Test framework + how to run them
- Code style preferences (no comments unless WHY-explaining, etc)
- Branch / commit / PR workflow
## Standing rules
- Always X before Y
- Never use Z
- When asked about W, default to V
## Commands you'll need
- `npm run dev` — start dev server
- `npm test` — vitest run
- `npm run build` — production build
For inspiration look at real CLAUDE.md files on GitHub (site:github.com filename:CLAUDE.md). The good ones are 100-300 lines and read like a technical brief, not a manual.
Step 4: Symlink for cross-tool support
If you want Codex and Cursor to read the same file:
cd ~/.claude
ln -s CLAUDE.md AGENTS.md
Or for project-level:
cd /path/to/your-project
ln -s CLAUDE.md AGENTS.md
Both files now show the same content. One source of truth, three tools.
Step 5: Verify
This recipe has an automatic check. Run aiguide_validate_step and the validator will confirm one of the candidate locations exists. Or pass manual: true if you've already verified yourself.
When the file is in place, every fresh session of Claude Code, Cursor, or Codex will load it as system context before reading your first message. You only have to write it once.
ls -la ./CLAUDE.md ./AGENTS.md ~/.claude/CLAUDE.md ~/.codex/AGENTS.md 2>/dev/null || true