How to Set Up Claude Code with a Custom CLAUDE.md (5 Minutes)

Hey guys, Mr. Technology here.

Claude Code reads one file at the repo root: CLAUDE.md. Most teams never write one. The model guesses your stack on every prompt, hallucinates imports, edits files you told it not to touch in Slack, and explains "this is a common TypeScript pattern" to you for the fourteenth time today. A 12-line file fixes 90% of this. Here is the version that works.

The Setup

Drop the file at your repo root: ~/code/your-app/CLAUDE.md. Commit it. That is the install. Claude Code reads it automatically on every session, every subagent, every /init reindex. The model treats the contents as binding project knowledge — higher priority than chat history, lower than anything you say in the active session.

The 12 Lines

```markdown

Project Rules for Claude Code

Stack

• TypeScript strict, Node 22, pnpm, Next.js 15 App Router. PostgreSQL via Drizzle. No Prisma.
• Tests: Vitest. E2E: Playwright. Lint: Biome.
• Auth: Lucia. Stripe for billing. Resend for email. S3 for uploads.

Conventions

• TypeScript: no any outside generated code. No default exports. Named exports only.
• Imports: relative for siblings, @/ for cross-folder. Group: stdlib → external → internal → types.
• Errors: Result<T, E> in lib/, throw at the edge. No try/catch in components.
• Naming: camelCase TS, snake_case JSON. Mappers live in src/lib/case.ts.
• Tests live next to the file as *.test.ts. No __tests__/ dirs.

Hard Rules (do not violate)

• Do not edit package.json without asking. Do not add dependencies without a stated reason.
• Do not modify files under migrations/ or src/db/schema/.
• Do not run pnpm db:reset or rm -rf node_modules without confirming.
• No console.log in committed code. Use the logger from src/lib/log.ts.

Done means

• pnpm test, pnpm typecheck, pnpm lint all pass.
• No new TODOs in the diff.

`

The Three Gotchas Nobody Mentions

Gotcha 1: order matters more than word count. Claude Code parses CLAUDE.md greedily — the first instruction it sees on a topic tends to "win" when uncertain. Stack and conventions go at the top. Hard rules go at the bottom. If you mix them, the model picks the wrong rule under pressure. Order equals priority.

Gotcha 2: explicit "do not" beats "always do" by roughly 2x. Same A/B I ran for Cursor rules. Prohibitions (Do not edit package.json, No console.log) get respected roughly twice as often as positive phrasings (Always use the logger). LLMs were trained on corrective feedback. Tell them what is forbidden. They infer the rest.

Gotcha 3: the file is read once, not re-read mid-session. If you edit CLAUDE.md while a session is running, the model will not see the change until you /clear or start a new session. There is no live reload. Edit, save, restart the session. The single biggest source of "the rules are not working" bugs is editing the file mid-conversation and expecting it to apply.

The Trick Most People Miss: @import

Break the file into pieces and @-import them:

```markdown

Project Rules

@./docs/claude-code/conventions.md @./docs/claude-code/hard-rules.md @./docs/claude-code/architecture.md ```

Each section lives in git, gets code-reviewed, survives team turnover. New hire opens Claude Code Monday, model already knows the stack. Five minutes of writing, one file at the repo root, and your editor AI stops inventing your stack from scratch.

— Mr. Technology