Claude Code for Founders: The CLAUDE.md That Changes Everything

Most founders who install Claude Code try it for an afternoon, get a feel for the loop, and then wonder why it sometimes writes exactly what they wanted and sometimes produces a migration that drops a production table. The answer is almost always CLAUDE.md, or rather the absence of one. Claude Code is a generalist out of the box, and a generalist with admin rights over your repo is a hazard dressed up as a helper. The fix is a single file in your project root that tells the agent what your code looks like, what commands to run, what never to touch, and how to talk back to you. This article walks through the CLAUDE.md we set up for WitsCode founder clients, the loading hierarchy that almost nobody explains correctly, the AGENTS.md compatibility story, and the one line about commit messages that is worth the price of admission on its own.

What CLAUDE.md actually is

CLAUDE.md is a plain Markdown file that Claude Code reads automatically before every turn and injects into the model's context. There is no schema, no required sections, no validation. It is a prompt prefix dressed up as a file. That simplicity is why it works, and why most founders underuse it. You can write "the stack is Next.js 15 with React 19, use pnpm, do not touch the billing module without asking" and the agent will behave accordingly from that prompt onward.

Think of it as the contract between you and the agent. The agent has no memory of your project across sessions, no opinion about your conventions, and no way to know that the one API route under app/api/shopify/webhook must never be cached. CLAUDE.md is where you encode all of that once so you do not have to re-explain it on every task.

The payoff is compounding. Every rule you add to CLAUDE.md is a category of mistake the agent will not make again. Every command you document is a guessing loop the agent skips. Every guardrail is a destructive action you never have to undo. A well-maintained CLAUDE.md is the difference between an agent that helps and an agent that operates.

The loading hierarchy almost nobody explains

Claude Code does not just read one CLAUDE.md. It reads several, in a specific order, and the order matters because later files override earlier ones when instructions conflict. This is the hierarchy, from weakest to strongest precedence.

First, Claude Code loads ~/.claude/CLAUDE.md if it exists. This is your user-global file, the one that applies to every project on your machine. It is the right place for personal preferences that follow you everywhere, things like "prefer TypeScript over JavaScript", "write tests first", "explain what you did in three sentences before showing me the diff". Keep it short. Anything you put here applies to every repo you open, including ones you do not control.

Second, Claude Code walks up from your current working directory to the repo root, collecting any CLAUDE.md it finds along the way. In a monorepo, this means packages/web/CLAUDE.md and then the root CLAUDE.md are both loaded when you are working inside the web package. Nested instructions win against parent instructions for the same rule, which is exactly what you want. A React package and an API package can have different conventions, and the agent will pick the right one based on where you are.

Third, the project-level CLAUDE.md in your current working directory is loaded last, which means it has the strongest precedence. If your user-global file says "use npm" and your project CLAUDE.md says "use pnpm", the project wins. This is the rule that matters most, because it means you can have opinionated global defaults without worrying that they will bleed into a client project that does things differently.

The practical consequence is that you almost always want your project CLAUDE.md to be the source of truth for anything specific to that project, and your home-level CLAUDE.md to hold only things that are genuinely universal to you. The failure mode we see most often on founder audits is a bloated home CLAUDE.md full of project-specific rules from the last repo the founder worked on, polluting every new session with stale context.

The sections that move the needle

Most CLAUDE.md templates on the internet read like a corporate handbook. They include company history, a mission statement, a list of every library in package.json, and three paragraphs on code style that duplicate what the eslint config already enforces. None of this moves the needle. Claude Code is being billed by the token on every turn, and you are paying to re-read marketing copy on every prompt. Here are the sections that actually matter.

Start with a one-paragraph project description. What the product does, who it serves, and the one thing about the business that affects technical decisions. Two or three sentences. This orients the agent and costs almost nothing in tokens.

Follow with the stack, pinned to versions. Runtime, framework, package manager, database, and the two or three libraries that shape how code gets written. Versions matter because the API surface of React 18 is not the API surface of React 19, and the agent will happily write hooks that work in one and fail in the other if you do not pin it. A two-line stack section prevents a category of bug that is hard to diagnose when it appears.

Document your commands explicitly. Install, dev, test, build, lint, typecheck, migrate. The exact invocation. If your test command is pnpm test --filter web, write that. Claude Code defaults to guessing, and its guesses are reasonable but not always right. When the commands are documented, the agent runs them instead of describing them, and the feedback loop tightens by an order of magnitude.

Next come conventions. Where new routes live, where components go, how files are named, where tests sit relative to the code they test. Be specific and short. "New API routes go in app/api/<resource>/route.ts. Component tests are colocated as ComponentName.test.tsx. Server-only utilities live in lib/server/, client-only in lib/client/." Three sentences here save a dozen turns of back-and-forth on a real feature.

Known pitfalls are where seniority shows. Every real project has two or three things that are not obvious and have bitten you in production. The webhook endpoint that must read the raw body before parsing. The one query that cannot run inside a transaction. The third-party API whose rate limit is per minute, not per second. Writing these down in CLAUDE.md is how you turn institutional knowledge into an agent that inherits it.

Finally, guardrails. The list of things the agent must ask before doing. "Do not modify files in lib/billing/ without confirming." "Do not run production migrations." "Do not add new top-level dependencies without asking which one and why." This section is doing the work of a senior engineer peering over the agent's shoulder, and it is cheap to write and astonishingly effective.

The commit-message rule that saves your future self

The single highest-ROI line in a CLAUDE.md is a commit-message format rule. Without one, Claude Code writes commits like "update", "fix stuff", "WIP", and "more changes". Your git log becomes useless, git bisect becomes impossible, and any tooling that parses commit messages for changelogs or release notes silently gives up. With one short block in CLAUDE.md, every commit it writes is useful for the rest of the project's life.

Here is the block we add to founder CLAUDE.md files.

Commit messages follow Conventional Commits.
Format: <type>(<scope>): <subject>
Types: feat, fix, chore, refactor, docs, test, perf, build.
Subject is imperative, lowercase, no trailing period, under 70 chars.
Examples:
  feat(checkout): add Shop Pay accelerated button
  fix(webhooks): verify Stripe signature on raw body
  refactor(auth): extract session helper from middleware
Never use WIP, update, fix stuff, or changes as a commit message.
If the change is genuinely trivial, use chore: with a real subject.

That is all it takes. From the next commit onward, your history becomes navigable, your changelog tooling starts working, and a future you opening git log six months from now can actually reconstruct what happened.

The same pattern works for branch names and PR titles. Add two more lines about the branch naming convention and the PR title format and Claude Code will follow them. This is the category of thing that feels too minor to write down and pays back every single week.

AGENTS.md compatibility and why you probably want both

A year into the agentic-coding era, the ecosystem realised that every tool having its own instructions file was absurd. Cursor had .cursorrules, Aider had .aider.conf.yml, Claude Code had CLAUDE.md, and keeping them in sync was a chore that everyone lost. AGENTS.md is the convention that emerged to fix this. It is a single Markdown file with the same purpose as CLAUDE.md, readable by every major agent. Cursor reads it. Aider reads it. Codex and OpenHands read it. Claude Code reads it too, in addition to CLAUDE.md.

If you already have AGENTS.md from another tool, you do not need to duplicate it. The pattern we use on founder setups is to put the real content in AGENTS.md and have CLAUDE.md be a single line that imports it.

@AGENTS.md

Claude-specific: when uncertain, stop and ask before editing. Explain the plan in three sentences before writing code.

The @path syntax inlines another Markdown file into CLAUDE.md. This gives you a shared source of truth plus a place for rules that only apply when the tool is Claude Code. If you only ever use Claude Code, you can skip AGENTS.md and keep everything in CLAUDE.md. If you use more than one agent or you expect to, write the shared content in AGENTS.md and import it.

Slash commands are the other half of the setup

CLAUDE.md tells the agent how your project works. Slash commands tell it how your workflow works. They live in .claude/commands/<name>.md and they are invoked in Claude Code by typing /<name>. A slash command is just a prompt template with a name, and the combination of a tight CLAUDE.md and a handful of slash commands is what turns Claude Code from a helpful tool into something that feels operational.

The commands we add to every founder setup are small and specific. A /ship command that runs tests, formats, typechecks, commits with a Conventional Commits message, and pushes. A /review command that diffs the current branch against main and writes a PR body. A /plan command that takes a feature description and produces a checklist of files to touch before any code gets written. Each of these is a ten-line Markdown file, and each one replaces a two-minute ritual with a single keystroke.

The pairing matters. A slash command assumes the agent already knows your conventions, your commands, and your commit format. That knowledge lives in CLAUDE.md. Without CLAUDE.md, /ship has to be a hundred lines and still gets it wrong. With CLAUDE.md, /ship is ten lines and works every time.

A founder-ready CLAUDE.md template

Before the template, a word on what to leave out. CLAUDE.md is loaded on every turn and counts against the context window, so a 2000-line file is a token tax on every prompt. Leave out long style guides because your .prettierrc and eslint config already encode them. Leave out company history and mission statements. Leave out the full dependency list, since the agent reads package.json on its own. The rule of thumb is that CLAUDE.md should fit on one screen with comfortable whitespace, and deeper detail belongs in docs/architecture.md referenced by a pointer sentence.

This is the shape we ship with our founder setup. Short, specific, and tuned to how a founder actually runs a product. Adapt the specifics, keep the structure.

# Project

Acme is a Shopify checkout optimisation tool for DTC brands. The technical
priority is checkout performance and webhook reliability.

## Stack

- Next.js 15, React 19, TypeScript 5.6
- pnpm 9 (never npm, never yarn)
- Postgres 16 via Prisma 5
- Stripe for billing, Shopify Admin API for the integration

## Commands

- Install: pnpm install
- Dev: pnpm dev
- Test: pnpm test
- Typecheck: pnpm typecheck
- Lint: pnpm lint
- DB migrate (dev): pnpm prisma migrate dev
- DB migrate (prod): never run directly, ask first

## Conventions

- New API routes: app/api/<resource>/route.ts
- Components: colocated with tests as Name.test.tsx
- Server-only code: lib/server/, client-only: lib/client/
- No default exports in library code, named only

## Known pitfalls

- The Shopify webhook route at app/api/shopify/webhook must read the raw
  body. Never JSON.parse before HMAC verification.
- Prisma migrate in CI requires DATABASE_URL with a pooler bypass.
- The /dashboard route must not be statically rendered (uses session).

## Commit messages

Follow Conventional Commits.
Format: <type>(<scope>): <subject>
Types: feat, fix, chore, refactor, docs, test, perf, build.
Subject imperative, lowercase, no trailing period, under 70 chars.
Never use WIP, update, or fix stuff.

## Guardrails

Ask before:
- Modifying anything in lib/billing/
- Adding a new top-level dependency
- Running a production migration
- Changing the webhook verification logic
- Rewriting code older than six months without being asked

## Tone

Explain the plan in three sentences before writing code. Flag assumptions
explicitly. If uncertain, stop and ask rather than guess.

That file is under a hundred lines, loads fast, covers the real failure modes, and sets the tone for how the agent behaves. Drop it in the root of a repo, run Claude Code, and the experience changes on the next prompt.

Where founders should spend the hour

If you have an hour to invest in making Claude Code useful, spend it writing the CLAUDE.md. Not reading about it, not copying a template verbatim, but sitting down and thinking hard about the three things that have bitten you in production, the five commands you run every day, and the two modules you never want touched without a conversation. That document is the contract that turns an agent from a risk into a teammate.

If that hour is not available, this is exactly the kind of work we do under the WitsCode founder CLAUDE.md setup. One file that encodes your stack, your conventions, your pitfalls, and your guardrails, a mirrored AGENTS.md so every tool you use reads the same rules, a starter .claude/commands/ set for shipping and reviewing, and a commit-message rule that ends WIP history for good. Fixed scope, one engagement, and your agent starts behaving like it works for you instead of for nobody in particular.

→ WitsCode founder CLAUDE.md setup