DEV Community

Cover image for How I Stopped Claude Code From Losing Context After Every Compaction
Chudi Nnorukam
Chudi Nnorukam

Posted on • Edited on • Originally published at chudi.dev

How I Stopped Claude Code From Losing Context After Every Compaction

#claudecode #ai #workflow #context

Originally published at chudi.dev

"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?

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?

Every non-trivial task gets a directory:

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

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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

What's the Complete Dev Docs Workflow?

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]
Enter fullscreen mode Exit fullscreen mode

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]
Enter fullscreen mode Exit fullscreen mode

3. Hit ESC Before Implementation

Interrupt Claude before it starts coding.

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

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]
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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]
Enter fullscreen mode Exit fullscreen mode

7. After Compaction, Say "Continue"

The magic moment:

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

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

How Does Multi-Root Workspace Structure Help?

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/
    └── ...
Enter fullscreen mode Exit fullscreen mode

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?

Hooks enforce the workflow without manual intervention:

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

When Should I Skip Dev Docs?

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?

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
Enter fullscreen mode Exit fullscreen mode

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:

Top comments (0)