Shift Notes

Shift Notes

The hard problem in long-running agents is not doing work in one session — it's bridging the context gap between sessions. Every fresh agent starts with zero memory. If it has to reconstruct project state from the code, it burns 5-10 minutes and a chunk of context before writing a line. If it has a well-shaped handoff file, that drops to 30-60 seconds.

That handoff file is claude-progress.txt (or equivalent). Prose, not JSON. The model writes prose more naturally, and the read is cheap.

The format — write into this shape

# Project: <name>
# Last updated: <ISO timestamp> by session <id>

## What's done
- <feature> [feature-list index: N]
- ...

## What's in progress
- <feature> [feature-list index: N]
  Status: <one paragraph — what works, what doesn't>
  Files touched this session: <list>
  Known open issues: <list>

## What's next (recommended)
- <feature> [feature-list index: N]
  Reason: <why this one>

## Notes for the next session
<free-form prose: gotchas, flaky tests, environment quirks>

Enforced softly by the prompt, not by validation. Free text is the point — the notes section is where the previous shift warns the next one about the thing that isn't captured anywhere else.

Writing the notes — at end of session

• Move the completed feature from "in progress" to "done".
• Recommend the next feature in "what's next" with a one-line reason (unblocks-N, low-risk, prerequisite-for-M).
• Notes-for-next-session is the highest-leverage field. Use it for: flaky tests you hit, dependencies that surprised you, spec ambiguities you resolved one way (so the next agent doesn't re-litigate), env vars that need to be set.
• Do not delete "done" entries. They're audit trail. If the section gets long, that's a signal to compact the whole notes file at v0.2 milestones, not to prune mid-project.

Reading the notes — at start of session