The thesis: most people install Claude Code and start prompting, then spend weeks repeating the same corrections. The setup below front-loads those corrections into files the agent reads 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
- Argue the agent has no memory across sessions, so anything you correct verbally you will correct again. Written context is the only durable form.
- Frame the setup as compressing your repeated instructions into the repo itself.
- Set the expectation: this is not configuration for its own sake, every item below removes a recurring class of mistake.
Step 1: the instruction file
What goes in it
- Stack summary, the commands to run, a directory map, one blessed pattern per concern, and an explicit do-not-touch list.
- Argue the do-not-touch list is the highest-value section and the one most often missing.
What to leave out
- General coding advice, anything the agent already knows, and aspirational rules nobody enforces. Long files get skimmed.
- Point to /templates/agents-md for a starting structure and /free-tools/agents-md-generator to draft one from an existing repo.
- Send readers to /blog/claude-md-vs-agents-md for the naming and precedence question.
Step 2: make verification runnable
- Argue this is the single biggest lever: give the agent a typecheck, a lint, and a test command it can run without asking.
- Explain the consequence of skipping it, that you become the compiler and throughput drops to your reading speed.
- Cover the minimum viable test suite for a young project: auth boundary, billing webhook, one core business rule.
Step 3: permissions and guardrails
- Argue for deliberately allowing the safe read-only and build commands so the agent stops interrupting, while keeping destructive operations gated.
- Name what should always require confirmation: production database access, deploys, force pushes, secret files.
- Make the point that a well-tuned permission list is what makes long autonomous runs tolerable.
Step 4: project-specific commands and skills
- Explain packaging repeated workflows so they are invoked rather than described: release steps, migration creation, adding a feature slice.
- Point to /claude-skills for reusable skills and argue that skills are how a convention becomes executable rather than aspirational.
- Warn against premature abstraction: package a workflow after the third time you have explained it, not the first.
Step 5: subagents and when they earn their keep
- Argue subagents are for parallel independent work and for keeping a noisy task out of the main context, not for making one task faster.
- Give the practical cases: broad codebase search, a focused review pass, and a long migration running alongside feature work.
- Reference /agents for the directory of agent tooling worth wiring up.
Step 6: the codebase itself is configuration
- Make the central argument: no amount of setup rescues a sprawling repo, and a clean repo needs less setup.
- Name the properties that matter most and defer detail to /blog/ai-agent-ready-boilerplate-checklist.
- For readers starting fresh, point at /categories/Agent-Ready and /blog/best-nextjs-boilerplate-2026 for foundations that already ship most of this.
The working loop, once set up
- Scope a vertical slice, let the agent implement and verify, review the diff not the transcript, commit.
- Argue for small commits and frequent checkpoints because the recovery cost of a bad long run is what kills trust in the workflow.
- Note the habit that matters most: when you correct the agent twice on the same thing, write it into the instruction file instead of correcting a third time.
Frequently Asked Questions
Do I need a CLAUDE.md if my project is small?
- Answer yes, and reframe: the file is short for a small project, and it is what stops the project growing inconsistently.
CLAUDE.md or AGENTS.md?
- Give the short practical answer and link /blog/claude-md-vs-agents-md for the full reasoning.
How long should the instruction file be?
- Answer with a range and the principle that specificity beats length, plus what to cut first when it grows.
Should I let Claude Code run commands without asking?
- Answer: yes for read-only and build commands, no for anything that touches production or rewrites history.
What is the fastest way to set this up on an existing repo?
- Answer: generate a draft with /free-tools/agents-md-generator, then correct it by hand, because the corrections are the valuable part.
