What “set up right” actually means
A correctly set up Claude Code project is not a folder with a CLAUDE.md in it. It is four layers, each one trusted by the layer above:
- A substrate the agent and a human can both work in - a sane repo structure with a toolchain that builds, lints, type-checks, and tests from the first commit.
- Configuration that steers the agent - a lean
CLAUDE.md, deterministic hooks, and scoped subagents, so behavior is shaped on purpose rather than hoped for. - Context discipline - a way to carry decisions and progress across sessions, so the agent does not start from zero every time.
- Conventions and reasoning in files - the why of the project, written down where the next session (and the next person) can read it.
Skip any one of these and you feel it within a day: the agent reformats files no linter guards, forgets a decision you made an hour ago, or invents a structure you have to undo.
Start with the substrate
Most setup advice jumps straight to prompting. The real foundation is the repository itself. A Turborepo and pnpm monorepo gives agents and humans clear boundaries to work within, and a toolchain that is green from commit one - TypeScript, ESLint, Vitest, Prettier, and CI - means the agent gets immediate, honest feedback on every change instead of shipping code that nothing checks.
This is the difference between “it ran” and “it is correct.” A project with real gates catches the agent’s mistakes for you, at the moment they happen.
Make the conventions explicit
Claude follows what it can read. That is why CLAUDE.md best practices matter so much: a lean, well-structured instruction file the agent actually reads beats a sprawling one it half ignores. Pair it with a small docs system so the reasoning behind your decisions lives in files - not in a chat that gets compacted away the moment the context window fills.
Anything that must happen every time - linting after an edit, blocking a destructive command - belongs in a hook, not an instruction. Hooks run deterministic code that cannot hallucinate, which is exactly why they are part of a setup done right.
Solve context before it bites you
The most-felt pain in Claude Code is that every new session starts from zero - it forgets your codebase, your decisions, and your context, and you re-explain the same things again. The fix is not a memory plugin bolted on after the fact; it is context management built into the project from the start. A gated session handoff writes durable state to disk and verifies it, so the next session boots without you rebuilding the picture by hand.
Why not just use a free template?
Free templates exist, and some are fine. But a starter template hands you files you still have to understand and a repo you only hope works. Getting setup right is less about having the files and more about knowing why each one is shaped the way it is - which is the part a template cannot give you.
The one-command version
Everything above is what claudesetup does in a single command: it scaffolds the whole foundation - the monorepo, the green toolchain, the context handoff, and the conventions - and ships the reasoning for every choice alongside the files. You start correct, not just fast, and you own all of it.