CLAUDE.md

CLAUDE.md is the orientation packet for this job site — not the company-wide handbook, and not a tutorial.

Plain markdown. You drop it in the folder. Every time an agent opens the project, the harness reads it first, before the first tool. You explain the shop once. The file does the talking at the start of every session.

The filename is a label

Claude looks for CLAUDE.md. Cursor looks for AGENTS.md. This repo uses AGENTS.md: Bun, Turborepo, where tests live, don't invent a second ORM. Same job. If a tool asks for one name and you only have the other, point it. The content is what matters.

Two layers stack:

1. Global — how you like to work everywhere. Ask before building. No secrets in code. Keep diffs small.
2. Project — true only here. Package manager is Bun. Compatibility rules live in the engine. Don't touch apps/web/content unless asked.

The system prompt is who the model is in every room. These files narrow it to this room. A skill is still a one-job card. Don't dump the skill into the orientation packet. Point at it.

Keep it true. A stale rule is worse than no rule. "We use Yarn" in a Bun monorepo is how you get a confident intern installing the wrong world.

A generated app from the builder or the plugin should inherit the same idea: a short file that says how this stack is packed, so the next agent does not unpack it.

What this unlocks

The highest-leverage page you will write is not today's prompt. It is the file the agent reads every single time. Get it right and the same dumb mistake stops looping.

House rules on disk beat house rules in your head.