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.

In this example, I used Claude Code’s web interface. 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: “This project’s aggregate typecheck script lives at the repository root. Run pnpm run typecheck there.” 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

Record the working commands Document your quirks, not your features. Features are obvious. Quirks are invisible until they break.

The instructions should describe this project’s scripts, not invent rules about pnpm itself:

## Workspace commands

- Install from the repository root with pnpm install.
- Run the root typecheck script: pnpm run typecheck.
- Build the web package: pnpm --filter @workspace/web run build.
- Test the utility package: pnpm --filter @workspace/utils run test.
- Check package.json for the exact script and package names.

pnpm also supports running scripts from a package directory and adds the workspace root’s binaries to script PATH. Its run documentation and filtering reference explain those rules. An exact package name avoids ambiguity; partial names do not universally fail.

Turn the next repeated failure into a short instruction. Record the error, the directory to run from, the working command, and what a successful result looks like. Use the project’s actual script names so the next session can verify the fix.

When you open Claude Code and encounter a pnpm error, it reads this CLAUDE.md and knows what went wrong. It still needs to verify the result, but it starts with the command the project actually expects.

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.