How CLAUDE.md Works

Every One Shot app ships a CLAUDE.md file at the repository root, and it is the first thing Claude Code reads before writing any code in the project. It isn't documentation in the usual sense; it's a map. It tells an agent the one obvious way to do each kind of task, and points at the specific files that are the source of truth, so the agent builds your product on top of the kit's plumbing instead of re-deriving auth, billing, or tenancy from scratch.

What it actually contains

• Step 0, telling a fresh project to run the bootstrap-app skill before building any feature. See Making It Yours.
• The one rule that keeps the app safe: every model is account-scoped, every query goes through Current.account, every controller authorizes with Pundit. See Accounts and Tenancy.
• The anatomy of a vertical slice, pointing at the example Project resource as the template to copy for any new feature. See Adding a Resource.
• A list of what's already built, so an agent doesn't accidentally rebuild auth, billing, email, or mobile shells that already exist and work.
• Conventions: code style, the adapter+fake pattern, the CSP gotchas around off-site redirects, and where app identity is centralized.

AGENTS.md, alongside it

A companion file, AGENTS.md, exists for coding agents other than Claude Code that follow the emerging AGENTS.md convention. It's short on purpose: it redirects to CLAUDE.md and summarizes the essential rules, rather than duplicating the whole map.

Why this file, and not a wiki or a set of comments

An agent that hasn't read a wiki page doesn't know it exists. CLAUDE.md sits exactly where every agent looks first: the repository root, read automatically before the first tool call. Keeping the map there, rather than scattered across code comments, means the guidance survives refactors and travels with the repository itself, including into a forked product directory.

Next

See what each individual skill does: The bootstrap-app Skill.