Skip to content
AK
All articles
2 min read

HANDOFF.md — The Easiest Way to Use Claude Code

As you work in Claude Code, your conversation gets longer and longer. Eventually, the context becomes too large. Claude may become less efficient, responses can slow down, and it's often better to start a fresh session.

  • Playbook
  • Claude Code
  • Course
  • AI

What is HANDOFF.md?

As you work in Claude Code, your conversation gets longer and longer.

Eventually, the context becomes too large. Claude may become less efficient, responses can slow down, and it's often better to start a fresh session.

Instead of losing all your progress, developers use a simple file called HANDOFF.md.

Think of it as a save file for your AI session.

Why use it?

A HANDOFF.md lets a brand-new Claude Code session instantly understand:

  • What you're building
  • What has already been completed
  • Important technical decisions
  • Current bugs
  • What to work on next

Instead of spending several minutes explaining everything again, Claude can continue from where the previous session ended.

What should go inside?

A good HANDOFF.md usually contains:

🎯 Project Goal

What you're building.

✅ Current Progress

What's already finished.

⚙️ Important Decisions

Frameworks, libraries, architecture choices, things that shouldn't change.

🐛 Current Issues

Known bugs or blockers.

📂 Files Changed

Helpful files Claude worked on recently.

📋 Next Steps

A short checklist for the next session.

When should you create one?

The best time is before ending a Claude Code session.

Simply ask Claude:

"Update my HANDOFF.md with everything the next session needs to know."

Claude will summarize the session into a clean handoff document.

Starting a New Session

When you open Claude Code again, simply ask:

"Read HANDOFF.md first."

Claude immediately understands the project and continues from where the last session stopped.

Why developers love it

  • 🚀 Start fresh sessions without losing progress
  • 🧠 Keep only the important context
  • 💰 Avoid wasting tokens re-explaining the project
  • 🔄 Easily switch between Claude Code, Cursor, Codex, or ChatGPT using the same handoff file
  • 📈 Better workflow for long-running projects
project/
├── CLAUDE.md      # Permanent project instructions
├── HANDOFF.md     # Current project state
├── README.md
├── src/
└── docs/
  • CLAUDE.md → Coding rules, architecture, conventions (changes rarely)
  • HANDOFF.md → Current progress, decisions, bugs, and next steps (updated before every new session)

Learn More

📖 Claude Code Documentation

https://docs.anthropic.com/en/docs/claude-code

📚 Memory & Context Best Practices

https://docs.anthropic.com/en/docs/claude-code/memory

These guides explain how Claude Code uses project memory, context, and files like CLAUDE.md, making them the perfect companion to a HANDOFF.md workflow.