Problem

Agent sessions start cold. Left alone, a long session either drifts once it gets big enough (losing track of earlier decisions and quietly re-doing work) or the next session re-derives project context from scratch. Neither is acceptable if you want to actually rely on the agent across a real project.

Solution

A layered set of context files instead of one giant prompt. CLAUDE.md sits at the repo root and loads automatically at the start of every session, onboarding notes for an engineer who's smart but has never seen the project: build and test commands, conventions, the gotchas that look wrong but aren't, and the boundaries the agent shouldn't cross without asking. Anything longer or more situational than that lives in a skill, loaded on demand instead of costing context every session. And handover.md is the piece that survives context resets: near the limit, the agent writes down where the work stands, what was decided and why, and what's next, so the following session reads it and continues instead of rediscovering everything.

The layering goes further than the root file. A global ~/.claude/CLAUDE.md holds preferences that apply everywhere, commit style, package manager, and repo subfolders that work differently from the rest can carry their own nested CLAUDE.md, so the root file stays general while each area owns its own rules. Everything project-specific lives under .claude/: settings.json for permissions and hooks (committed, so it becomes a team default), settings.local.json for the personal, uncommitted copy, skills/ for on-demand instructions, agents/ for custom subagents, and commands/ for slash commands.

Skills install with one command from a community registry (npx skills add <owner>/<skill>), but asking Claude to write or install what the repo actually needs beats browsing one in cold. A skill is also a set of instructions the agent follows with your permissions, which makes third-party skills a prompt-injection surface, so I read the SKILL.md before installing anything and stay wary of ones that want network access or touch credentials.

Thinking process

The core discipline is that every line in CLAUDE.md spends context on every session, so anything already discoverable from the code stays out of it. The harder problem was noticing when a session had quietly gone stale, since context can slide out of a model's attention without any obvious signal. I fixed that with a tell: a line in CLAUDE.md telling the agent to address me by name in every response. Early in a session it does. When my name stops showing up, that instruction has slipped out of attention, and so has the rest of the file, which means it's time to write the handover and start fresh.

Multi-agent work runs on the same logic at a bigger scale: subagents handle parallel research, a generator-verifier pairing catches plausible-but-wrong output before it ships, and a stronger model acts as orchestrator once a task is big enough to delegate. Loops extend that further, an overnight run restarts the agent with fresh context each round to close out one task from a plan file at a time, so I wake up to staged changes instead of a to-do list.

None of it changes who's responsible. If an agent ships a bug, that's my bug, so nothing merges, deploys, or leaves the sandbox without me reviewing it first.

Tech stack

• Claude Code as the agent runtime, since CLAUDE.md and skills load automatically at session start with no manual onboarding step.
• CLAUDE.md, kept short on purpose, everything in it is re-read every session.
• Skills, for anything too long or too situational to justify a permanent context cost.
• Git, staging every change for review, since keeping a human in the loop at the merge point was the one non-negotiable part of the design.

Architecture

CLAUDE.md and skills load once at session start. The session does the work. Near the context limit it writes handover.md, and the next session reads that (plus CLAUDE.md and skills again) to pick up exactly where the last one stopped.