Spec, plan, handoff
Structure your work so the next session picks up smoothly
⏱ Est. ~4 min
01 · Read
Eventually, every Claude Code session ends. Maybe the context fills up. Maybe you close your laptop. Maybe you're handing the work off to a teammate.
The question is — can the next session pick up smoothly?
The answer depends on how well you've documented things. That's where specs come in. A spec is a markdown file describing a feature, bug fix, or task in enough detail that Claude (or a teammate) can pick it up cold.
Key points
- Sessions end — context is temporary, specs are permanent
- Specs let the next session (or person) pick up without re-explanation
- A spec is a markdown file describing what, why, and how
- Lives in your repo (often in a specs/ folder), committed to git
02 · Code example
A good spec answers: what are we building, which files are involved, and what does "done" look like? Here's a template.
Feature spec template
# Feature: OAuth Integration
## Requirements
- Support Google and GitHub OAuth
- Maintain session after page refresh
- Handle token refresh automatically
## Files to Modify
- src/auth/oauth.ts — OAuth client setup
- src/auth/session.ts — Session persistence
- server/routes/auth.ts — API endpoints
## Implementation Plan
1. Set up OAuth provider configuration
2. Add login flow UI components
3. Implement token refresh logic
4. Add integration tests
## Done When
- `npm test` passes
- Can log in with Google and GitHub
- Session survives page refresh
Look at the structure — requirements (what), files (where), plan (how), definition of done (when to stop). That's enough for Claude to start the feature in a new session. Point Claude at the spec file and say "implement this".
03 · Read
For complex changes, Claude Code has plan mode. Instead of jumping straight to writing code, Claude explores the codebase, understands existing patterns, and proposes a plan before implementing.
You can also checkpoint your work. Press Esc+Esc to open the rewind menu — you can restore code and conversation to any earlier point, or summarize from a checkpoint to free up context.
Think of checkpoints like a local undo — they track every change Claude makes, and you can always rewind.
Key points
- Plan mode: Claude explores and proposes a plan before implementing
- Checkpoints: created automatically before each change
- Esc+Esc opens the rewind menu — restore code, conversation, or both
- "Summarize from here" condenses everything before that point
- Checkpoints are local to the session (separate from git)
04 · Code example
Here's how experienced engineers structure complex work with Claude Code.
Phase 1 — Explore
You: "Read the auth module and explain how sessions work"
Claude: [reads files, explains architecture]
Phase 2 — Plan
You: "Write a spec for adding OAuth support"
Claude: [creates specs/OAUTH_SPEC.md with requirements, files, plan]
Phase 3 — Implement
You: "Implement the spec in specs/OAUTH_SPEC.md"
Claude: [implements against the spec, step by step]
Phase 4 — Verify
You: "Run tests and verify against the spec"
Claude: [runs tests, checks each "done when" criterion]
The spec becomes the bridge between sessions. If context fills up mid-implementation, start a new session and say "continue implementing specs/OAUTH_SPEC.md". Claude reads the spec, checks git to see what's done, and picks up the work.
05 · Quiz
You're halfway through a complex feature and the context fills up. What's the best way to continue in a new session?
- Point Claude at your spec file and ask it to continue
- Start over and re-explain everything from scratch
- Copy-paste the entire previous conversation
- Give up on the feature and do something simpler
06 · Fill in the blank
Press Esc twice to open the _____ menu, where you can restore code and conversation to an earlier point.
Other lessons in this chapter
⚠ The full interactive experience needs JavaScript. Please enable it and reload.
※ This is an independent Traditional Chinese teaching project — not an official Anthropic product. Claude™ is a trademark of Anthropic, PBC.