Key Files

Every Playbook project has the same set of governing files. They fall into three groups by purpose.

Files that tell Claude Code how to behave

CLAUDE.md — project-level instructions Claude Code reads at session start. Holds the rules that should shape every prompt in this project. See CLAUDE.md for what belongs there.

.claude/settings.json — hard rules Claude Code cannot violate. Most important: the file-read denylist that blocks Claude Code from ever opening .env.local, even if you ask it to. This is the single highest-leverage file in the security model.

.claude/agents/ and .claude/skills/ — optional project-scoped homes for subagents and skills. Bootstrap doesn’t create them; add them when you need them. See Subagents and Skills for when each is the right primitive.

.claude/ is committed to the repo (it’s not a secret). .env.local is not (it is).

Files that capture intent and decisions

docs/prd.md — what to build, for whom, why. You write this. The Out of Scope section is the most operationally important part — it stops Claude Code building things you didn’t ask for.

PLAN.md — how to build it. Claude Code writes this at the end of the bootstrap and stops. Component tree, routes, file count estimate, deviations from spec. The Plan Gate sits here.

memory.md — running log of decisions made during the build. Claude Code can propose entries during a session; review them before they land. Useful when revisiting a project months later.

PRD vs PLAN — the distinction that matters

The PRD is the input; the PLAN is Claude Code’s interpretation of how to deliver it. The Plan Gate exists so you can catch misinterpretations before code is written.

File	Author	Answers	When
docs/prd.md	You (human)	What to build, for whom, why. Out of scope.	Before Prompt 02. Reference doc throughout.
PLAN.md	Claude Code	How to build it. Component tree, routes, file count.	End of Prompt 01. Approval gate.

Files that hold credentials

.env.local — real secret values. Gitignored. Lives only on your laptop and inside Vercel (where production values are held separately).

.env.example — same key names as .env.local, empty values. Committed. Acts as a template for anyone else cloning the repo.

.env vs .env.local

Use .env.local for real secret values. Next.js gitignores it by default. .env is conventionally for non-secret defaults and is committed by some setups. Don’t put secrets in .env.

The docs/ folder — two valid patterns

Pattern A — Empty scaffold (default). Bootstrap creates an empty docs/. You write docs/prd.md later as Prompt 02. Feature briefs land in docs/features/ as you go.

Pattern B — Pre-populated. You manually create docs/ and drop pre-written specs in before running bootstrap. Use when you have substantial prior context (multi-module specs, UX docs, prototypes) that Claude Code should read during orientation.

Most simple projects use Pattern A. Use Pattern B when you’ve already done meaningful design work that Claude Code needs to honour from the first prompt.

File reference

The full list of files a Full Bootstrap creates, who maintains them, and whether they’re committed.

File	Created by	Maintained by	Committed
CLAUDE.md	Bootstrap	You + Claude Code	yes
.claude/settings.json	Bootstrap	You (rarely)	yes
PLAN.md	Bootstrap	You (rarely)	yes
memory.md	Bootstrap	You + Claude Code	yes
.env.local	Bootstrap	You	no
.env.example	Bootstrap	You (adding keys)	yes
docs/	Bootstrap (full)	You + Claude Code	yes