CLAUDE.md

Picture the binder a new hire finds waiting on their desk the first morning. Not the company-wide handbook. The rules for this specific job: where everything lives, how we do things here, the landmines to step around.

A CLAUDE.md is that binder, for your project. It's a plain text file (just Markdown, nothing fancy) you drop in a folder. Every time you or an AI agent opens that folder, it reads this file first, before doing anything else. So instead of re-explaining your setup at the start of every session, you explain it one time and the file does the talking.

The thing most people miss: there are two of them.

The system prompt is who the AI is everywhere. CLAUDE.md narrows that down. And it comes in two layers:

1. Global CLAUDE.md: how you want the AI to behave in every project. This is your personal operating manual. It lives in your home config folder, not in any one project.

2. Project CLAUDE.md: the rules for this one codebase. It lives in the project folder and gets shared with anyone (or any agent) who opens it.

The AI reads both and stacks them: global rules first, then the project rules on top. When they conflict, the more specific one (the project) usually wins.

What goes where. A quick gut check: if it's true no matter what you're working on, it's global. If it's only true for this project, it's project-level.

Global (about you and how you like to work):

• "Explain things in plain English. I'm not a developer."
• "When something's ambiguous, ask before you build. Don't guess."
• "No secrets in code. Keys go in the env file, always."

Project (about this codebase):

• "We use this database. Don't add a different one."
• "Brand voice is warm, never corporate."
• "Always run the tests before you say you're done."
• "Never touch the checkout file."

A real wrinkle worth knowing. People assume there's a global file sitting at ~/.claude/CLAUDE.md waiting for them. Often there isn't, you have to create it. And the ecosystem is quietly standardizing on a tool-neutral filename, AGENTS.md, so that Claude, Codex, and the rest all read the same house rules instead of each wanting its own. (My own global file is actually an AGENTS.md. Same idea, one file every tool respects.) If a tool asks for CLAUDE.md and you only have AGENTS.md, point it at the one you've got. The filename is just a label. The content is what matters.

Here's a good project-level CLAUDE.md you can copy and rewrite for your own thing:

# CLAUDE.md

## What this is

A Shopify store for a small product brand. A custom theme, plus a
couple of apps for reviews and email.

## How it's built

- Theme: Liquid and a little plain JavaScript. No React.
- Email: Klaviyo. Don't hardcode list IDs, read them from the env file.
- Images live in /assets. Keep them under 200kb.

## How we work here

- Brand voice is warm and human, never corporate. No exclamation spam.
- Mobile first. Most of our traffic is on phones.
- Always preview on a duplicate theme before touching the live one.

## Never touch

- checkout.liquid
- Anything in /vendor
- The live theme directly. Duplicate it, edit the copy, then publish.

And a global one (drop it at ~/.claude/CLAUDE.md, or name it AGENTS.md):

# Global rules (apply to every project)

- Explain things in plain English. I am not a developer.
- When something is ambiguous, ask before you build. Don't guess.
- Keep changes small. Only touch what I asked you to touch.
- No secrets in code. API keys go in the env file, always.
- Before you tell me you're done, run it and show me it actually works.

If those last two feel familiar, they should. Andrej Karpathy (ex-Tesla, OpenAI) posted his hard-won notes on where AI coding agents go wrong, and the community turned them into a now-famous CLAUDE.md: don't assume, keep it simple, make surgical changes, define what "done" means. It's worth lifting wholesale as a starting point. His original notes live in the X post, and the community packaged them into a copy-and-go file at multica-ai/andrej-karpathy-skills on GitHub.

My honest take after living in these files for months: the CLAUDE.md is the single highest-leverage thing a non-technical builder can write. Not the prompt you type today, the file the agent reads every single time. Get it right and the agent stops making the same dumb mistakes on a loop. It shows up already knowing the job.