I've been using Claude Code heavily, and along the way I settled into a setup that makes agent sessions noticeably better. This is the short version of what works for me.

CLAUDE.md

CLAUDE.md is a markdown file at the root of your repo that Claude Code loads into context at the start of every session. Think of it as onboarding notes for an engineer who is smart but has never seen your project. Mine covers only four things. It lists the commands to build, test, and run the project. It describes the conventions the codebase follows. It points out the gotchas that look wrong but are intentional, and it marks the boundaries the agent should not cross without asking.

Keep it short. Every line spends context on every session, so anything already discoverable in the code or the README should stay out. If you run /init in a repo, Claude drafts the file for you, and your job is mostly to trim it down.

The file also works at two other levels. A global one at ~/.claude/CLAUDE.md holds preferences that apply everywhere, like your commit style or your package manager. And the files nest. If part of your repo works differently from the rest, say a mobile/ folder with its own build system, you can drop another CLAUDE.md inside that folder. Claude picks it up when working in that subtree, so the root file stays general and each area carries its own rules.

How Claude structures files

Everything project-specific lives in a .claude/ directory, and each piece has a clear home.

• settings.json holds permissions, hooks, and environment variables, and travels with the repo through git
• settings.local.json is the personal version of the same file, kept out of git
• skills/ holds the skills, one folder each with a SKILL.md inside
• agents/ holds custom subagent definitions
• commands/ holds custom slash commands

The separation matters because whatever you commit becomes a team default. A new contributor clones the repo and their agent already knows the rules.

Skills

A skill is a SKILL.md file with a short description at the top and a body of instructions below it. Claude loads the skill on demand when a task matches the description, so it costs almost nothing until it's needed. That makes skills the right home for anything too long or too situational for CLAUDE.md.

The useful ones tend to fall into a few groups. Review and verification skills give Claude a code review rubric tuned to your codebase, or a verify routine that actually runs the app instead of trusting green tests. Workflow skills capture deploy checklists and commit conventions. Anthropic also maintains open skills for generating documents like PDFs, Word files, and spreadsheets. Design skills deserve special mention, because you can extract the design system you want into the skill itself. Put your colors, spacing, typography, and component patterns in there, and every interface Claude generates follows your system instead of framework defaults.

Installing from the community registry at skills.sh takes one command.

npx skills add <owner>/<skill>

But the approach I'd actually push is simpler. Don't browse, ask. Describe the project to Claude and tell it to install or write the skills the repo needs. It can search the registry, pull in what fits, and scaffold the rest itself. A skill written against your actual repo usually beats a generic one, and ten minutes of setup pays off every session after.

One caution before you install anything. A skill is a set of instructions your agent will follow with your permissions, which makes third-party skills a prompt injection surface. Read the SKILL.md before installing, prefer sources you trust, and be suspicious of anything that wants network access or touches credentials. The registry runs security scans, but the final review is on you.

handover.md

Context windows end and sessions crash. The fix is boring and effective. Have the agent maintain a handover.md that records where the work stands, which decisions were made and why, and what comes next. When context runs low, the agent updates the file, and the next session reads it and continues instead of rediscovering everything. It works like a shift handover at a hospital, and it turns long projects into a relay instead of a series of cold starts.

There's a simple trick for knowing when to rotate. Put a line in CLAUDE.md telling Claude to address you by name in every response. Early in a session it will. When your name stops appearing, that instruction has slid out of the model's attention, which means the rest of your instructions are slipping too. The session has gone stale, so have it write the handover and start fresh.

Agents and loops

Single-agent chat is the floor, not the ceiling. Subagents let you spawn parallel workers with fresh context for research or exploration and then synthesize what they bring back, which works well for anything that splits into independent pieces, like crawling a set of sources in parallel while you review what comes in. The pattern most production write-ups converge on is called orchestrator-workers, where a lead agent breaks the task down, delegates the pieces, and stitches the results back together. Another useful pairing is generator-verifier, where a skeptical second agent tries to poke holes in the work before anything ships. It's cheap insurance against plausible-but-wrong output. And the ralph loop restarts the agent with fresh context each round to take one task off a plan file, finish it, and stage the change for approval, repeating until the plan is empty.

If your token budget allows it, overnight loops are where this setup earns its keep. Queue the boring batch work before you sleep, things like regression suites, coverage backfill, migrations, and dependency bumps, and wake up to staged changes instead of a todo list. The caveat is cost. Multi-agent runs burn several times the tokens of a single session, so start with one loop and scale to what your plan can absorb.

For anything beyond a single loop, put a stronger model in charge. Your most capable model becomes the orchestrator that plans the work, spawns smaller and cheaper agents for the narrow tasks, checks what they return, and stops or redirects the ones going sideways. The strong model spends its capability on judgment, the small ones spend their cheapness on volume, and your goal keeps them all pointed in one direction.

The common thread through all of it is that fresh context beats bloated context, verification beats trust, and the human stays in the loop at the merge point.

Where to start

• Run /init, then cut the generated CLAUDE.md down to commands, conventions, gotchas, and boundaries
• Add a settings.json with the permissions your team is comfortable with
• Ask Claude to install or write the skills your repo actually needs, starting with its most repeated workflow
• Keep a handover.md on anything longer than one session, and use the name trick to know when to rotate
• When a task splits cleanly, reach for subagents before reaching for a bigger prompt

None of this is complicated. It's mostly the discipline of writing things down where the agent will actually read them.

You still own it

A final note, and the most important one. You are the owner of the project. If an agent ships a bug, that's your bug. If an overnight loop breaks the build, that's your build. The agent is leverage, not liability transfer, and the bottom line for anything it produces sits with you.

In practice that means a few habits. Verify manually, because tests passing is not the same as the feature working, so run the app and click through the flow before you merge. Be skeptical of hard-to-read code, because code you can't read is code you can't own, and code you don't understand is a bug you haven't found yet. Keep files short and well structured. A single file with a thousand lines is bloated for you and for the model, since long files burn context, hide bugs, and quietly make agents worse. Watch for strange occurrences too, like duplicated logic, dead code, or a helper that already exists two folders over. Agents drift toward these when nobody is looking, and catching them early is far cheaper than untangling them later.

And the old conventions still apply. Keep the codebase DRY. Keep modules small and names clear. Keep functions honest the way functional programming taught us, meaning a function works with what it's given and returns a result instead of reaching outside its scope to mutate shared state. Push side effects to the edges, prefer pure functions in the middle, and avoid hidden global state that makes behavior impossible to trace. None of this became optional because an agent writes the code. If anything it matters more, because the agent imitates the codebase it sees. A clean codebase is itself a prompt.

Since these rules aren't tied to any one project, they belong in your global CLAUDE.md, the base file at ~/.claude/CLAUDE.md mentioned earlier. Write them down once there and every session in every repo starts with them, so you never have to repeat "keep functions pure" or "split files before they sprawl" project by project. Save the project-level files for what's genuinely specific to each codebase.

Above all, supervise. However good the loops get, keep a human in the loop before anything gets committed, deployed, or taken outside your test environment. Agents can draft, build, and stage all night, but the moment work leaves your sandbox it carries your name, because you are still responsible for what ships.