Most people install Claude Code, open a repo, and start prompting. Then they spend the next three weeks repeating the same five corrections: use pnpm not npm, put server logic in the load function, stop touching the generated migration files. The setup below front-loads those corrections into files the agent reads at the start of every session. It takes about an hour, and it is the difference between an agent that guesses your conventions and one that follows them.
Why the first hour compounds
The agent has no memory across sessions. Whatever you fix by typing it into the chat is gone the moment that session ends, so you will fix it again tomorrow and again next week, paying the same cost in attention every time plus the cost of noticing the mistake. Written context is the only durable form of instruction.
The correct mental model for setup is compression. You take the instructions you would otherwise repeat forever and put them into the repository, where they get read once per session at zero marginal effort. The payoff scales with how long the project lives: on a weekend script it barely matters, on something you will work on for a year it is the highest-leverage hour you will spend.
None of what follows is configuration for its own sake. Every item removes a recurring class of mistake, and if you cannot name the mistake an item prevents, skip it. A setup you built because a blog post told you to is a setup you will not maintain.
Step 1: the instruction file
What goes in it
The instruction file is a briefing for a competent engineer who joined this morning and has never seen your codebase. That framing tells you what belongs in it. A stack summary, so the agent does not infer your framework version from lockfiles. The exact commands for dev, build, typecheck, and test, written as commands you can copy rather than descriptions. A short directory map explaining what lives where and why, because layout encodes decisions invisible from any single file. One blessed pattern per concern: data fetching, error handling, migrations, each with a pointer to the file that does it best.
Then the section most people leave out, which is the one that pays for the whole file: an explicit do-not-touch list. Generated files, vendored code, the legacy module you are strangling, the config that looks wrong but is load-bearing. An agent will confidently improve any of these unless told not to, because from inside the code they look like oversights. Naming them costs four lines and prevents the change that is hardest to catch in review, the one that looks like a cleanup and quietly breaks production.
Do not touch:
- `src/generated/**` is emitted by `pnpm db:generate`. Edit the schema instead.
- `vercel.json` routes are load-bearing for the www redirect. Ask before changing.
- Never edit migration files after they have been applied. Add a new one.
What to leave out
Leave out general coding advice. "Write clean code" and "handle errors properly" are tokens the agent spends attention on and learns nothing from. Leave out anything the model already knows, which includes most of how your framework works. Leave out aspirational rules nobody enforces, because a rule the codebase violates throughout teaches the agent that your file is unreliable, and it will start weighting the code over the document.
Length is the enemy. Long instruction files get skimmed, by models and by humans, and the sections at the bottom stop getting applied. If you want a starting structure rather than a blank page, our AGENTS.md templates give you a skeleton for a typical web stack, and the AGENTS.md generator drafts one from an existing repository so you are editing rather than inventing.
On naming: Claude Code reads CLAUDE.md from the project root and from subdirectories, picking up nested ones when it works in those folders. Most other agents read AGENTS.md. The maintainable answer is one real file with the other symlinked to it, so there is a single source of truth and no chance of drift. The precedence details are in CLAUDE.md vs AGENTS.md.
touch AGENTS.md
ln -s AGENTS.md CLAUDE.md
Step 2: make verification runnable
This is the single biggest lever in the setup, larger than the instruction file. Give the agent a typecheck command, a lint command, and a test command it can run on its own without asking, and write them into the instruction file. The agent then closes its own loop: write code, run the checks, read the failures, fix them, run again. You see the result after it converges instead of after every step.
Skip this and you become the compiler. Every change comes back unverified, you run the build yourself, you paste the error back in, and throughput drops to your reading speed. That is the actual bottleneck in most people's setups, and it is usually mistaken for the model being bad at coding.
Young projects often have no tests and the temptation is to defer this. Do not. The minimum viable suite takes an afternoon: one test on the auth boundary proving an unauthenticated request to a protected route is rejected, one on the billing webhook proving a subscription event actually flips the entitlement in your database, and one on whatever your core business rule is. Those three cover the failures that cost money. The rest can wait until the product's shape settles.
pnpm typecheck # tsc --noEmit
pnpm lint
pnpm test # vitest run
Step 3: permissions and guardrails
Out of the box the agent asks before running things, which is correct and also unusable for long sessions. If you approve ls for the fortieth time you are not supervising, you are clicking. Deliberately allow the commands that cannot hurt you: reads, greps, typecheck, lint, tests, build, git status and git diff. The agent stops interrupting for trivia and you start reading the prompts that remain, which is the entire point.
What should always require confirmation: anything touching a production database, deploys, git push --force, rm -rf, and reads of secret files. A two-second pause is cheap insurance against a wrong call measured in hours or in customer trust. The asymmetry makes the list easy to draw. If the worst case is a wasted minute, allow it. If the worst case is an incident, gate it.
A well-tuned permission list is what makes long autonomous runs tolerable. It is not a security boundary and you should not treat it as one, since a determined agent can usually route around a rule. It is an attention budget: you can absorb a limited number of interruptions before you start approving on autopilot, and you want to spend all of them on things that matter.
Step 4: project-specific commands and skills
Once you have used the same workflow three times, package it instead of describing it. Cutting a release, creating a migration and its rollback, adding a feature slice with its route, server load, test, and nav entry: these are procedures whose steps do not change, and explaining them from scratch each time introduces a chance to explain them slightly differently. Packaged, they get invoked by name and run the same way every time.
That is what skills are for, and our skills directory has reusable ones worth starting from. The deeper argument is that a skill is how a convention stops being aspirational and becomes executable. A rule saying "always add a rollback with every migration" is a hope. A migration skill that generates both files is a guarantee, because the wrong path stops being the convenient one.
Resist packaging early. Abstraction before the pattern is stable encodes one guess about how the workflow goes, and then you maintain the guess. Package a workflow the third time you explain it, not the first. By the third time you know which parts are fixed and which parts you were improvising.
Step 5: subagents and when they earn their keep
Subagents are widely misunderstood as a speed feature, as though splitting one task across three agents makes it finish three times faster. It does not. Coordination and context transfer eat the gain, and a task with internal dependencies gets slower and less coherent when split. Subagents are for two things: genuinely parallel independent work, and keeping a noisy task out of your main context.
The cases where they pay off are concrete. A broad codebase search belongs in a subagent because you want the conclusion, not the four hundred lines of file dump, and the dump never enters your context. A focused review pass over a finished diff belongs in one, because a reviewer that did not watch the code being written is a better reviewer. A long migration grinding through fifty files can run alongside feature work, because neither needs to see the other's output.
The failure mode is spawning subagents for work that needs shared understanding, then spending longer reconciling their output than the work would have taken. If you cannot state what each agent owns in one sentence, it is one task. Our agents directory covers the surrounding tooling worth wiring up.
Step 6: the codebase itself is configuration
Here is the part no amount of setup rescues. If the repository sprawls, if the same concern is implemented three ways in three folders, if the naming is inconsistent and the boundaries are mush, your instruction file describes a place that does not exist. The agent reads it, reads the code, finds the contradiction, and follows the code. A clean repository needs less configuration precisely because the conventions are visible in the files.
The properties that matter most are consistency, small clear modules, explicit server and client boundaries, and typed edges where data enters the system. Each reduces how much the agent must hold in context to make a correct change. We broke those down in the AI agent ready boilerplate checklist, which doubles as a refactoring plan for an existing repo.
If you are starting fresh, begin from a foundation that already has these properties instead of imposing them later. The kits in our Agent Ready category are scored on exactly this, and our best Next.js boilerplate roundup for 2026 covers the ones shipping a usable instruction file and a real test suite on day one.
The working loop, once set up
The loop is simple and does not change much once you have it. Scope a vertical slice, small enough to describe in two sentences and complete enough to verify end to end. Let the agent implement and verify it. Review the diff, not the transcript. Commit.
Reviewing the diff instead of the transcript is the habit that takes longest to build. Watching the agent work feels like supervision and is mostly theater, since what lands in the repository is the only thing that matters. The diff is also where you catch the changes nobody asked for: the reformatted file, the dependency bump, the helpful refactor of a module you were not touching.
Commit small and checkpoint often. The reason is not tidiness, it is recovery cost. A bad thirty-minute run you can throw away with git reset costs thirty minutes. A bad three-hour run tangled up with two hours of good work costs an afternoon of untangling, and after two of those you stop trusting the workflow entirely.
The habit that matters most: when you correct the agent twice on the same thing, do not correct it a third time. Open the instruction file and write the rule down. That single reflex is what turns the setup from a one-time chore into something that gets better every week.
Frequently Asked Questions
Do I need a CLAUDE.md if my project is small?
Yes, and a small project makes it easier rather than optional, because the file will be twenty lines instead of two hundred. The reason to write it early is not that a small project is hard to navigate, it is that the file is what stops the project growing inconsistently. Every session the agent works without one is a session where it picks a pattern by guessing, and by the time the project feels big enough to need conventions you have three competing ones to reconcile.
CLAUDE.md or AGENTS.md?
Write one real file and symlink the other to it. Claude Code reads CLAUDE.md from the project root and from subdirectories; most other agents read AGENTS.md, so a project that works with more than one tool needs both names to resolve. A symlink gives you that with a single source of truth and no chance of two copies drifting into disagreement. The full reasoning, including nested files and precedence, is in CLAUDE.md vs AGENTS.md.
How long should the instruction file be?
Somewhere between fifty and two hundred lines for a typical project, and if you are well past that you are probably writing documentation rather than instructions. Specificity beats length every time: one line naming the exact file that shows your blessed data-fetching pattern does more work than three paragraphs describing the pattern in prose. When it grows too long, cut the general advice first, then anything the model already knows about your framework, then any rule the codebase itself already violates.
Should I let Claude Code run commands without asking?
Yes for read-only and build commands, no for anything that touches production or rewrites history. Allow reads, greps, typecheck, lint, tests, builds, and read-only git commands, because the worst case is a wasted minute and constant interruptions train you to approve without reading. Keep production database access, deploys, force pushes, destructive deletes, and secret file reads behind confirmation, where a wrong call is an incident rather than an inconvenience.
What is the fastest way to set this up on an existing repo?
Generate a draft with the AGENTS.md generator, then correct it by hand. The generated draft gets the mechanical parts right, the stack summary, the commands, the directory map, which is the boring half of the work. The corrections are where the value is, because the things a generator cannot see are exactly the things worth writing down: which pattern is blessed and which is legacy, what must never be touched, and which parts of the code are wrong on purpose.
