# CLAUDE.md (/academy/claude-md)



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

Plain [markdown](/academy/markdown). You drop it in the folder. Every time an [agent](/academy/agent) opens the project, the [harness](/academy/harness) reads it first, before the first tool. You explain the shop once. The file does the talking at the start of every [session](/academy/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](/academy/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](/academy/secret) 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](/academy/system-prompt) is who the model is in every room. These files narrow it to *this* room. A [skill](/academy/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](/builder) or the plugin should inherit the same idea: a short file that says how *this* [stack](/academy/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.