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.

Important

Most teams document their architecture, but almost nobody documents their quirks—the gotchas, the edge cases, the "oh right, you have to do it THIS way or it breaks."

That is where Claude Code becomes a force multiplier.

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.

The difference is not that Claude is smarter. You stopped re-teaching Claude the same lesson every session.

What Goes in CLAUDE.md

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.

What was a chatbot that asks the same questions every session becomes a development partner with perfect project memory.