How I Stopped Claude Code From Losing Context After Every Compaction

“We already discussed this.”

I said it. Claude didn’t remember. Thirty minutes of context-building—file locations, architectural decisions, progress updates—gone after compaction. We were starting over.

The dev docs workflow prevents context amnesia by persisting task state outside the conversation. Three files—plan.md, context.md, tasks.md—capture everything Claude needs to continue exactly where it left off. After compaction, say “continue” and the AI reads the docs automatically. No re-explaining. No lost progress.

Why Does Claude Forget Mid-Task?

Claude forgets mid-task because context compaction automatically summarizes older conversation history to free token space. When this happens, specific details disappear — file paths you located, decisions you made together, progress state on multi-step work, and errors you already debugged. The conversation continues, but the AI no longer has the context you built.

Context compaction is necessary. Conversations grow too long. The AI summarizes older messages to make room for new ones. Claude’s context window documentation details the token limits that make compaction inevitable on long tasks.

The problem is what gets lost:

• File paths you spent time locating
• Decisions you already made together
• Progress state on multi-step tasks
• Specific errors you already debugged

That specific frustration of “we already discussed this”—the kind where you want to rage-quit and start fresh—became my weekly experience.

I write more documentation. To write less documentation. Anthropic’s documentation describes how context management and structured prompting directly affect output quality across sessions.

The paradox resolves when you realize re-explaining is the most expensive documentation of all.

What Are the Three Dev Doc Files?

The three dev doc files are plan.md, context.md, and tasks.md. Each task gets its own directory containing all three. Plan.md holds the approved implementation strategy. Context.md tracks current state, key files, and blockers. Tasks.md is a granular checklist with completion status. Together they persist everything Claude needs to resume after compaction.

Every non-trivial task gets a directory:

~/dev/active/[task-name]/
├── [task-name]-plan.md
├── [task-name]-context.md
└── [task-name]-tasks.md

plan.md: The Approved Blueprint

The implementation plan, approved before coding begins.

# Feature: User Authentication

## Approach
JWT-based auth with refresh tokens. Store in httpOnly cookies.

## Files to Modify
- src/routes/api/auth/+server.ts (create)
- src/lib/auth/jwt.ts (create)
- src/hooks.server.ts (modify)

## Decisions Made
- Chose JWT over sessions for stateless scaling
- 15-minute access token, 7-day refresh token
- No third-party auth initially

This file doesn’t change during implementation. It’s the reference point.

context.md: The Living State

Current progress, key findings, blockers. Updated frequently.

# Authentication - Current Context

## Progress
- [x] JWT utility created
- [x] Login endpoint working
- [ ] Refresh token rotation
- [ ] Protected route middleware

## Key Files
- src/lib/auth/jwt.ts:45 - Token generation
- src/routes/api/auth/login/+server.ts - Working endpoint

## Current State
Stuck on refresh token rotation. The cookie isn't being
set correctly in the response. See error at line 78.

## Next Steps
1. Debug cookie setting in +server.ts
2. Test with browser dev tools
3. Implement rotation logic

This is what Claude reads after compaction. It knows exactly where you are.

tasks.md: The Checklist

Granular work items with status.

# Authentication Tasks

## Phase 1: Core Auth
- [x] Create JWT utility functions
- [x] Implement login endpoint
- [x] Add password hashing
- [ ] Implement refresh rotation
- [ ] Add logout endpoint

## Phase 2: Protected Routes
- [ ] Create auth middleware
- [ ] Protect /dashboard routes
- [ ] Add redirect to login

## Phase 3: UI
- [ ] Login form component
- [ ] Error handling
- [ ] Success redirect

Check items as you complete them. Claude sees progress at a glance.

What’s the Complete Dev Docs Workflow?

The complete workflow runs in seven steps: enter plan mode, review the plan thoroughly, interrupt before implementation begins, run /create-dev-docs, implement one or two sections at a time, run /update-dev-docs before compaction, then say ‘continue’ after compaction. Claude reads the saved docs automatically and resumes without any re-explaining.

Here’s the step-by-step process:

1. Enter Plan Mode

Start with planning, not coding. Always.

You: "I need to add user authentication"
Claude: [Enters plan mode, explores codebase]

2. Review the Plan Thoroughly

Catch mistakes before implementation.

You: [Read the plan carefully]
You: "What about rate limiting on login attempts?"
Claude: [Updates plan]

3. Hit ESC Before Implementation

Interrupt Claude before it starts coding.

Claude: "I'll start by creating the JWT utility..."
You: [Press ESC]

This prevents “gun-blazing” implementation without documentation.

4. Run /create-dev-docs

Create the three files from the approved plan.

You: "/create-dev-docs"
Claude: [Creates task directory with plan.md, context.md, tasks.md]

5. Implement 1-2 Sections at a Time

Don’t do everything at once. Review between sections.

You: "Let's implement Phase 1: Core Auth"
Claude: [Implements, updates tasks.md]
You: [Review the code]
You: "Good, continue to Phase 2"

6. Run /update-dev-docs Before Compaction

When you sense context is getting long:

You: "/update-dev-docs"
Claude: [Updates context.md with current state, next steps]

7. After Compaction, Say “Continue”

The magic moment:

[Context compacted]
You: "continue"
Claude: [Reads dev docs automatically, knows exactly where you are]

No re-explaining. No lost context. Just continuation.

How Does Multi-Root Workspace Structure Help?

Multi-root workspace structure separates context by repository so frontend knowledge doesn’t pollute backend work. Each repo holds its own claude.md for repo-specific instructions, a PROJECT_KNOWLEDGE.md for architecture details, and a TROUBLESHOOTING.md for recurring issues. Claude reads only the files relevant to your current work, keeping context lean and accurate.

For projects with multiple repos:

~/git/project/
├── CLAUDE.md                  # Root config (~100 lines)
├── dev/active/[task-name]/    # Dev docs location
├── frontend/
│   ├── claude.md              # Repo-specific (50-100 lines)
│   ├── PROJECT_KNOWLEDGE.md   # Architecture details
│   └── TROUBLESHOOTING.md     # Common issues
└── backend/
    └── ...

Each repo has its own context files. Claude reads the relevant ones based on which files you’re working with.

Benefits:

• Separation of concerns: Frontend context doesn’t pollute backend work
• Reusable knowledge: PROJECT_KNOWLEDGE.md persists across sessions
• Troubleshooting history: Common issues documented once, used forever

What Do the 16 Automation Hooks Do?

The 16 automation hooks enforce workflow quality without manual intervention. UserPromptSubmit analyzes prompts and activates relevant skills. PreToolUse validates operations before they run. PostToolUse logs every file change. Stop-BuildChecker runs builds automatically on modified repos. Stop-ErrorReminder scans for missed error patterns. Together they catch problems throughout the session without any extra commands.

Hooks enforce the workflow without manual intervention:

The pipeline runs automatically. You just work. The system catches problems.

When Should I Skip Dev Docs?

Skip dev docs for quick questions, simple single-line fixes, and one-off tasks that fit entirely in a single conversation. Use them for any task taking more than 30 minutes, work spanning multiple sessions, complex features touching multiple files, or anything you would hate to re-explain from scratch after a context compaction event.

Not every task needs the full workflow:

Skip for:

• Quick questions (“How do I X?“)
• Simple fixes (typo, single-line change)
• One-off tasks that fit in one conversation
• Exploration without implementation

Use for:

• Any task taking more than 30 minutes
• Multi-session work
• Complex features with multiple files
• Anything you’d hate to re-explain

The overhead of creating dev docs pays off the first time you avoid context loss.

How Do I Get Started?

Start with the minimum viable setup: create a dev/ directory in your project root, create template files for plan, context, and tasks, then add ‘continue’ handling to your CLAUDE.md so Claude knows to read dev docs on that command. The full setup with hooks and workspace structure adds a few more hours but pays off quickly.

Minimum Viable Setup

1. Create a dev/ directory in your project root
2. Create template files for plan, context, tasks
3. Add “continue” handling to your CLAUDE.md:

## On "continue" command
1. Check for dev/active/*/context.md
2. Read the most recent context file
3. Resume from documented state

Full Setup

1. Install the dev docs commands (slash commands or aliases)
2. Configure hooks for automatic skill activation
3. Set up build checking on Stop events
4. Create workspace structure for multi-repo projects

The full system takes a few hours to configure. But it saves that time on every long task thereafter.

FAQ: Context Management for Claude Code

What is context compaction in Claude? When conversations get too long, Claude summarizes older messages to free up space. This ‘compaction’ loses details—specific decisions, file paths, progress state. The AI continues but forgets what you already discussed.

What are dev docs in Claude Code workflow? Dev docs are three files created for each task: plan.md (approved implementation plan), context.md (key files, decisions, current state), and tasks.md (checklist of work items). They persist outside the conversation.

How does the dev docs workflow prevent context loss? Before compaction, run /update-dev-docs to save current state. After compaction, say ‘continue’ and Claude reads the dev docs automatically, picking up exactly where you left off with full context.

When should I use dev docs vs regular conversation? Use dev docs for any task taking more than 30 minutes or spanning multiple sessions. Skip for quick questions, simple fixes, or one-off tasks that fit in a single conversation.

How do 16 automation hooks fit into this workflow? Hooks automate quality control throughout: UserPromptSubmit activates skills, PostToolUse tracks file edits, Stop-BuildChecker runs builds automatically, Stop-ErrorReminder checks for missed errors. They enforce the workflow without manual intervention.

---

The Failure That Caused This

The context amnesia problem came to a head on a specific afternoon.

I was 3 hours into implementing a multi-step authentication flow. We’d made specific decisions—JWT over sessions, 15-minute access tokens, httpOnly cookies, no third-party auth libraries. All of this was in conversation history.

Then context compaction hit.

I typed “continue” and Claude started implementing—but with a completely different approach. Sessions instead of JWT. localStorage instead of cookies. Not because it was ignoring my instructions. It genuinely didn’t have them anymore.

I spent 45 minutes figuring out what had changed and re-explaining the decisions we’d already made. Some of those decisions were subtle—the 15-minute token lifetime had a specific reason tied to our security requirements. I had to reconstruct the reasoning from scratch.

That night I built the first version of the dev docs system. Three files, 30 minutes to set up. The next session I ran into compaction again—this time I typed “continue” and Claude picked up exactly where we were. The cookies decision. The token lifetime. The files already modified. All of it.

The 30-minute setup has paid off dozens of times since. Context compaction is still annoying. But it’s no longer a crisis.

I thought I could just re-prompt after compaction. Well, it’s more like… I thought my memory was the backup, when I needed an actual backup.

Maybe the goal isn’t longer context windows. Maybe it’s better context persistence—and systems that make “we already discussed this” impossible to say. Retrieval-augmented approaches are another direction entirely; the RAG research by Lewis et al. explores how external knowledge retrieval can supplement limited context windows.

Advanced Patterns: Context Files for Different Work Types

The three-file structure is the baseline. For complex or long-running projects, these variants handle situations the baseline doesn’t cover.

API Design Work

When working on API design—endpoints, data schemas, contracts—context.md needs different sections than implementation work.

Add a current endpoint inventory: list every endpoint you’ve defined or are working toward with method, path, and status (designed, implemented, tested). This prevents the duplication problem where you design an endpoint in session one and Claude proposes a slightly different version in session three because it doesn’t know the first one exists.

Add a schema decisions section: capture data shape choices and the reason for them. “Using string for userId instead of number—consistent with Clerk’s user IDs” takes five seconds to write and prevents an hour of confusion when Claude suggests integer IDs.

UI and Component Work

For frontend work, tasks.md needs visual acceptance criteria, not just functional ones. Add a column: “Visual check: [what it should look like at mobile/desktop].” This forces you to define the visual bar before implementation, not after.

Also add a design decisions section to context.md: color tokens used, responsive breakpoints that apply to this component, and any interaction states (hover, focus, disabled) that need to be handled. These are the details that get lost between sessions and cause inconsistency.

Multi-Session Bug Investigation

Bugs that take more than one session to diagnose need a different structure. Replace plan.md with investigation.md: a hypothesis log. List every hypothesis you’ve tested, what you tried, and what you learned. “Hypothesis: race condition in auth middleware. Tested with logs. Result: not the issue—logs show auth completes before the error.”

This prevents testing the same hypothesis twice across sessions—which is more common than it sounds when you’re working on a complex bug over several days.

Keep context.md but focus it on the error signature: exact error message, stack trace, files involved, reproduction steps. Update it every session with what changed.

Team Projects

When multiple people work with the same context files, context.md needs a contributor section: “Last updated by [name], [date], summary of changes.” This isn’t bureaucracy—it’s the minimum information that prevents one person from undoing another’s documented decisions.

Also agree on update frequency. Individual projects, you update whenever it’s useful. Team projects, agree on a rule—“update before ending every session involving more than one file change.” Shared files need shared maintenance norms.

The baseline three-file structure handles 80% of sessions. These patterns handle the other 20%—the long-running, multi-person, investigative, and visually-complex work where the baseline creates gaps.

---

Related Reading

This is part of the Complete Claude Code Guide. Continue with:

• Quality Control System - Two-gate enforcement that blocks “should work”
• Evidence-Based Verification - Why confidence without proof fails
• Token Optimization - Save 60% with progressive disclosure