Claude Code: setup & project structure

I have a folder of screenshots. Dozens of Claude Code setup posts, structure diagrams, and "best practices" threads I've saved off the internet over the last few months. A lot of it overlaps. Some of it is hype. A few patterns keep appearing from independent sources — including Boris Cherny, who built Claude Code in the first place.

This is me mining that overlap and turning it into one opinionated setup guide: how to structure a project, what belongs in memory vs. skills vs. hooks, and which picks are actually worth installing.

TL;DR

1. Run 3–5 sessions in parallel via git worktrees. The single biggest productivity unlock, cited by the Claude Code team itself.
2. Default to Plan Mode for anything non-trivial — 3+ steps or an architectural call. If it goes sideways, stop and re-plan rather than push through.
3. Treat [CLAUDE](https://claude.ai/referral/jQJrv36Dpw).md as a living memory file. After every correction, add a rule so the same mistake doesn't repeat.
4. Turn repeated prompts into Skills (.[claude](https://claude.ai/referral/jQJrv36Dpw)/skills/<name>/SKILL.md) instead of retyping them every session.
5. Delegate research, exploration, and narrow tasks to subagents to keep the main context window clean.
6. Gate risky operations with hooks (PreToolUse/PostToolUse) — cheap, deterministic, zero inference cost, and they run even when you forget to ask.
7. Wire MCP servers for anything Claude needs live access to (GitHub, a DB, Figma, a browser) instead of copy-pasting context by hand.
8. Have a second session — or a second model — review the plan and the diff before you call it done.
9. Manage context deliberately. /compact and /clear between tasks; offload large outputs to files or subagents instead of letting the window fill.
10. Write a spec before implementation on anything real. Vibe coding gets you a demo, not a product that survives users.

Recommended project structure

your-project/
├── [CLAUDE](https://claude.ai/referral/jQJrv36Dpw).md                 # team instructions, committed: overview, stack, conventions
├── [CLAUDE](https://claude.ai/referral/jQJrv36Dpw).local.md           # personal overrides, gitignored
├── .mcp.json                 # MCP server configs (GitHub, DB, Slack…), shared via git
├── .[claude](https://claude.ai/referral/jQJrv36Dpw)/
│   ├── settings.json         # permissions, tool access, model choice, hooks — committed
│   ├── settings.local.json   # personal permission overrides — gitignored
│   ├── skills/
│   │   └── <name>/SKILL.md   # auto-invoked workflow or knowledge pack
│   ├── agents/
│   │   └── <name>.md         # subagent persona: isolated context, own tools/model
│   ├── commands/
│   │   └── <name>.md         # custom slash command, run as /project:<name>
│   ├── rules/
│   │   └── <topic>.md        # modular instruction files (style, testing, api-conventions)
│   └── hooks/                # PreToolUse/PostToolUse guardrails and automation scripts
├── docs/                     # architecture decisions, specs
└── src/                      # application code

That's synthesized from four independent project-structure posts that mostly agreed with each other.

Here's a minimal [CLAUDE](https://claude.ai/referral/jQJrv36Dpw).md to start from:

# Project: <name>

## Stack
Next.js 15, TypeScript, Tailwind, Postgres (Prisma), deployed on <host>.

## Conventions
- Package manager: pnpm — never npm/yarn.
- Components: colocate tests, no barrel files.
- Reference full API conventions with @docs/api-conventions.md (don't paste them here).

## Workflow
- Plan Mode for anything 3+ steps or touching architecture.
- Never mark a task done without running lint + typecheck + tests.
- After any correction from me, add a rule here so it doesn't repeat.

## Gotchas
- `yarn typecheck` has pre-existing errors unrelated to most tasks — check the diff, not the full log.

CLAUDE.md and memory

What goes in:

• Project overview, stack, and architecture conventions Claude can't infer from the code alone.
• Gotchas: known pre-existing errors, non-obvious deploy steps, env quirks.
• Explicit workflow rules — plan-mode triggers, subagent strategy, "definition of done," your elegance bar.
• References to longer docs via @filename instead of inlining them.
• Rules distilled from real corrections, added right after the correction happens.

What stays out:

• Anything that changes often. It's loaded every single session and costs tokens — put it in rules/ or docs/.
• Long specs or API docs. Link them with @filename, don't paste them.
• Secrets or API keys. Use env vars, ideally scoped per-project (see direnv below). Never in [CLAUDE](https://claude.ai/referral/jQJrv36Dpw).md.
• One-off task instructions. Those belong in the prompt, not in memory.

The memory hierarchy runs ~/.[claude](https://claude.ai/referral/jQJrv36Dpw)/[CLAUDE](https://claude.ai/referral/jQJrv36Dpw).md (global, every project) → <repo>/[CLAUDE](https://claude.ai/referral/jQJrv36Dpw).md (team, committed) → [CLAUDE](https://claude.ai/referral/jQJrv36Dpw).local.md (personal, gitignored). Run /init first, then hand-edit. Don't treat the auto-generated version as final.

Skills, subagents, slash commands, hooks, MCP

Skills are markdown instruction packs Claude auto-invokes by description match. Use them for any workflow you'd otherwise re-type: review checklists, PRD writing, framework-specific docs. Matt Pocock's /tdd, /write-a-prd, and /grill-me are good examples of the shape. Best picks: Superpowers, which auto-enforces brainstorm → plan → TDD → review; Agent Skills, Anthropic's official repo; and book-to-skill approaches for turning a technical book into something queryable. Read a skill's SKILL.md before installing — quality and security vary wildly.

Subagents are personas in .[claude](https://claude.ai/referral/jQJrv36Dpw)/agents/*.md with isolated context and their own tools and model, launched with the Task tool or just "use subagents." Use them for research, exploration, and narrow well-scoped work you don't want polluting the main thread. The Everything Claude Code setup ships 64 of them — planner, architect, security reviewer, per-stack reviewers. Awesome Claude Code Subagents is the place to copy from.

Slash commands are reusable prompt templates in .[claude](https://claude.ai/referral/jQJrv36Dpw)/commands/<name>.md, run as /project:<name>, and they can shell out. Use them for multi-step workflows you run constantly — review, fix-issue, deploy, a spec flow. GitHub Spec Kit's /speckit.constitution → specify → clarify → plan → tasks → implement is the canonical example.

Hooks are scripts wired into settings.json (PreToolUse, PostToolUse, and friends) that run outside the model at zero inference cost. Use them to block dangerous commands, enforce lint/typecheck after edits, or route approvals to a stricter model. Spotify's PreToolUse hook intercepts large file reads and routes them to a cheap model — they report a 90% mean cost saving on bulk reads. Anthropic's own Claude Code Security plugin uses the same layer to catch eval(), SQL injection, and hardcoded secrets on every edit.

MCP — Model Context Protocol — lets a server expose tools and data to Claude over a standard interface, configured in .mcp.json and shared via git. Use it for anything Claude needs live access to instead of copy-paste: GitHub, a database, Figma, a browser, your own API. One pattern I keep seeing: a Figma MCP plus a Chrome screenshot loop that iterates until the built UI matches the design 1:1. Start with the official MCP servers; for iOS, Apple's native Xcode MCP plus XcodeBuildMCP.

Workflows

Plan → spec → implement → review. Enter Plan Mode for anything non-trivial. For real features, force a spec first — constitution → specify → plan → tasks → implement — before a single line of code exists.

Second-opinion planning. Have a separate session review the plan "as a staff engineer" before implementation starts. If things go sideways mid-build, switch back to Plan Mode and re-plan instead of pushing forward.

Parallel agents via worktrees. This is the team's own top productivity tip:

git worktree add .[claude](https://claude.ai/referral/jQJrv36Dpw)/worktrees/my-worktree origin/main
cd .[claude](https://claude.ai/referral/jQJrv36Dpw)/worktrees/my-worktree && [claude](https://claude.ai/referral/jQJrv36Dpw)

Run 3–5 of these at once, one Claude session each. Some people set up shell aliases to hop between them in a single keystroke.

Second model review. Add a line to your memory file like "Codex will review your output once you're done." A second model catches a different class of mistakes than the one that wrote the code.

Tests as harness. Write the failing test first, then fix it, feature by feature. Never mark a task complete without proving it works.

Context management. /compact and /clear between unrelated tasks. Push research and exploration into subagents so the main window stays clean. Tools like headroom, agentmemory, and Graft exist specifically to cut redundant re-exploration between sessions.

Cost control. Scope API keys per project with direnv instead of exporting everything globally. For cheap iteration, point Claude Code at a local model via Ollama (ANTHROPIC_BASE_URL / ANTHROPIC_AUTH_TOKEN) and escalate to a frontier model only for the hard parts.

Best picks catalog