How to Prevent Claude from Forgetting Your Task (Dev Docs Method)

“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.

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.

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

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?

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?

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?

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

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.

---

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.

---

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