Home › Agent workflows › Context management for long agent sessions CLAUDE.md

Context management for long agent sessions CLAUDE.md

CLAUDE.md practices for keeping Claude Code effective in long sessions: lean memory, notes files, subagents, and resets.

Claude Code (CLAUDE.md)Agent workflows

Copy CLAUDE.md

How to use

Save this as CLAUDE.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# CLAUDE.md: Working in long sessions

## Keep this file lean
- This file loads every session. Keep it under ~100 lines: commands, architecture map, conventions, and gotchas. Move topic-specific rules into `.claude/rules/*.md` with `paths:` so they load only when relevant, or link docs with `@docs/architecture.md` imports.
- When you learn a durable fact about the project (a command, a pitfall), propose a one-line addition here rather than relying on chat history.

## Manage context
- Before big tasks, read only the files you need; use search (Grep/Glob) instead of opening whole directories.
- Delegate broad exploration ("find all callers", "how does auth work") to a subagent and keep its summary, not the raw output.
- Keep a working notes file for multi-step work: `notes/<task>.md` with the goal, decisions, done/next checklist, and commands that worked. Update it at milestones.
- When switching to an unrelated task, suggest `/clear`. Before compaction or a reset, make sure the notes file is current so work can resume.
- Prefer small diffs and frequent test runs over long chains of unverified edits.

## When context is getting stale
- Re-read files before editing them if they may have changed (don't edit from memory).
- If you're unsure what was already done, check `git status`/`git diff` and the notes file instead of guessing.

## Project
- Commands: `npm test`, `npm run lint` (edit me)
- Architecture notes: `@docs/architecture.md` (edit me)