Document Your Quirks: Why CLAUDE.md Changes Everything

Last week I spent 45 minutes asking Claude Code variations of the same question. “Can you fix the build?” Different wording each time. Different examples. Different error output. Thirty requests over 45 minutes.

I was asking Claude Code to solve the same problem I solve manually every time I work on the project.

Claude Code is the web interface at claude.ai/code. It loads a CLAUDE.md file from your project root at the start of every session.

Architecture is usually already visible in the repository. The useful additions are the gotchas, edge cases, and commands that only work from one directory.

Without Quirks Documented

Claude encounters pnpm typecheck failing from a package directory. Claude asks: “Are you in a monorepo? Are you using pnpm? Where should I run this?” You explain the architecture. Claude fixes it. Next task: same questions, same exploration, same delay.

With CLAUDE.md

Claude encounters the same error. Claude reads CLAUDE.md: “pnpm workspace puts binaries at root in node_modules/.bin/. Always run from project root.” Claude fixes it immediately, and the next task requires no questions.

Claude did not get smarter. I stopped re-teaching it the same lesson every session.

What Goes in CLAUDE.md

Field tip Document your quirks, not your features. Features are obvious. Quirks are invisible until they break.

A real pnpm monorepo CLAUDE.md:

## pnpm Monorepo: Critical Commands

pnpm install (from root - sets up workspace)
cd packages/web && pnpm install (breaks symlinks)

pnpm typecheck (from root)
cd packages/web && pnpm typecheck (binaries at root, not in package)

pnpm -C packages/web build (run specific package)
cd packages/web && pnpm build (different behavior, can fail)

pnpm --filter @workspace/utils test (run package by name)
pnpm --filter utils test (partial matches fail)

Why each matters:
- pnpm workspace symlinks binaries to root node_modules/.bin/
- Running from package directory breaks PATH lookup
- -C flag changes working directory safely
- --filter requires exact package name from package.json

When you open Claude Code and encounter a pnpm error, it reads this CLAUDE.md and knows what went wrong. No hypothesis needed and no questions asked.

The Multiplier

You already know these quirks. You solve them manually every time. The difference between wasting 45 minutes and shipping in 5 minutes is not Claude Code’s intelligence. You taught it to remember what you know.

The file does not give Claude perfect project memory. It does give each new session the small operational details that are expensive to rediscover.

This habit sits in the wider workflow writeup: Claude Code: what I actually use.