Build a Handoff File Claude Can Debug From

Last updated: August 2026

We are going to build a handoff file: a markdown record of how your setup was put together, written by Claude Code itself, stored where a future session can read it. By the end you will be able to open a brand new session, point it at one file, and have it pick up exactly where the last one stopped. In a session last month a student built one of these, and roughly forty minutes later her connection broke. Pointed at its own notes, Claude read them, pulled its debug logs, correctly identified two separate faults, and walked her through the fix while she watched.

What you need before starting

• Claude Code installed and authenticated (install docs)
• A real project folder, in a plain local directory that syncs nowhere
• Something already configured that would be annoying to redo: a connection, a set of preferences, a working build
• About twenty minutes

Step 1: Make a reports folder inside the project

The file has to live with the project, not in your notes app. A future session can only read what is inside the folder it opens.

cd /path/to/your/project
mkdir reports

The folder name matters less than the fact that it sits at the top level of the project rather than buried inside a hidden configuration directory. I have watched a student open a project from inside the .claude folder by mistake and lose access to everything above it.

Checkpoint: Running ls in your project root shows reports alongside your actual work.

Step 2: Have Claude write the first handoff

Do not write this yourself. The whole point is that the tool records what it actually did, including the parts you did not notice it doing.

Start Claude Code in the project folder and give it this:

Write a detailed markdown file at reports/setup.md that documents how this
project is currently configured. Include: every tool or service connected
and how, the exact commands used, where credentials are stored (the file
path only, never the values), any version or package requirements, and
anything that surprised you or needed a workaround.

Write it for a future session that has no memory of this conversation.
Assume the reader knows nothing about what we did today.

That last paragraph is the one that changes the output. Without it you get a summary. With it you get instructions.

Checkpoint: Open reports/setup.md. If you can read it and understand how to rebuild the setup from scratch, it is good enough. If it reads like a changelog, tell Claude it is writing for someone with no context and have it redo it.

Step 3: Add the credential paths, never the credentials

This is where people either make the file genuinely useful or turn it into a liability.

The handoff needs to say where secrets live so a future session knows what to look for. It must never contain the secrets themselves, because this file is going to be read, copied, and quite possibly committed.

## Credentials

- API token: stored in `.env` as `SERVICE_API_TOKEN`
- Second token: stored in `.env` as `OTHER_SERVICE_TOKEN`
- Both excluded from version control via `.gitignore`
- Expiry: 90 days from 2026-08-20, renew before 2026-11-18

That block tells a future session everything it needs and nothing an attacker could use. If you are unsure where your secrets currently are, the five ways beginners leak credentials covers the checks first.

Checkpoint: Search your handoff file for any string that looks like a key. There should be zero matches.

Step 4: Generate verification scripts

A handoff that describes the setup is useful. A handoff that can test the setup is what turns a fifteen minute debugging session into a two minute one.

Ask for the checks as real scripts, not as prose:

Create scripts in reports/ that verify this setup is working. One script
per thing that can independently break. Each should print a clear pass or
fail and, on failure, print the specific error rather than exiting silently.

In the session I mentioned at the top, this produced three small diagnostic scripts. They are still in her project, and they are now the first thing run whenever anything looks wrong. That is the durable asset from the whole exercise.

The reason to insist on one script per failure mode is that it turns a vague symptom into a specific answer. When her setup broke, the useful information was not "the connection is down." It was that one service authenticated and the other returned a 401, which immediately ruled out half the possible causes. A single script that checks everything and prints one pass or fail would have told her nothing she did not already know.

It is also worth asking for the failure output to be verbose, because the default instinct of generated scripts is to fail quietly:

On failure, print the full error including any status code, and print which
command produced it. Do not swallow errors or exit silently.

Checkpoint: Run each script. They should all pass right now, while everything is known to be working. Then deliberately break one thing, run them again, and confirm the right script fails with a useful message. A verification script you have never seen fail is not a verification script either.

Step 5: Prove it works from a cold session

This is the step people skip, and skipping it means you find out whether your handoff works on the day you least want to.

Close Claude Code entirely. Open it fresh in the same folder. Then:

Read reports/setup.md and the scripts in reports/. Report back on how this
project is configured and what state it should be in. Do not change anything.

If the fresh session can describe your setup accurately from the file alone, the handoff works. If it asks questions you thought you had answered, those gaps are exactly what to add.

Checkpoint: A session that has never seen your project can explain your project back to you.

Step 6: Write the handoff before you need it

The habit matters more than the file. Context degrades as it fills, and when it fills completely the tool compacts the conversation automatically and loses detail in the process. You want to control that moment rather than have it happen to you.

Check how full you are:

/context

My rule, which I now teach to every student regardless of level, is to stop at around seventy percent. Not when things start going wrong. At seventy percent, while everything is still clean:

Update reports/setup.md with everything we changed this session, then write
reports/handoff-2026-08-20.md describing exactly where we stopped, what is
half-finished, and what the next session should do first.

Then start a fresh session and point it at the new handoff.

Checkpoint: You have a dated handoff file and a fresh session that knows what to do next.

Where this breaks

The folder gets opened from the wrong place. If you launch Claude Code from inside a subdirectory, or from a hidden configuration folder, it cannot see the reports. Everything appears to have vanished. Check your working directory before assuming the file is gone.

The handoff describes intentions rather than actions. If you write the file yourself, or write it before doing the work, you get what you meant to do rather than what happened. The value is entirely in it being written after the fact by the thing that did the work. Anything else is a plan, not a handoff.

It goes stale silently. A handoff written three sessions ago and never updated is worse than none, because a future session will confidently follow instructions that no longer apply. Update it at the end of every session that changed anything, or delete it.

Secrets creep back in. When you ask Claude to document a connection, it will sometimes helpfully include the token it used. Grep the file after every update. Once a secret is in a file you are committing, it is in the history permanently, even after you delete it. Basic markdown is all this file needs, so there is no reason for anything sensitive to end up in it.

What to build next

The natural extension is a context file that ships with the project so every session starts knowing your standards, not just your setup. What a CLAUDE.md file is covers that, and it pairs with this: the context file says who you are and how you work, the handoff says where you stopped. Together they remove almost all of the "remind me what we were doing" overhead that eats the first ten minutes of a session.

If you want to build this on your own project with someone catching the mistakes in real time, that is literally what my sessions are. Book a free Discovery Call and bring whatever setup you are afraid of losing.

These tutorials come from the actual curriculum I teach 1-on-1. Every command above was run in a real session before it shipped.