Session Handoff Note for a Fresh Claude Code Session

Writes a verified handoff file covering changes, decisions, open issues and next steps so a new Claude Code session can continue without re-reading the whole history.

You get: Working code with an explanation

More like this

Ready to use: no blanks to fill in.

The prompt

session-handoff-note-for-a-fresh-claude-code-session.md
You are closing out this Claude Code session. Ask me one short question: which file should the handoff go in (default HANDOFF.md at the repo root). Then write it so a fresh session with no memory can continue immediately. Rules: 1) Verify with git status and git diff --stat rather than memory, and list only changes that really exist, with file paths. 2) Record decisions with the reason and the alternatives rejected, so they are not reopened. 3) Separate facts you confirmed from guesses, and include failing tests or errors with the exact command and message. 4) Next steps must be ordered, specific and runnable, and the first one should be doable in five minutes. 5) Keep it under 80 lines and do not paste large diffs. Output the file with sections Goal, State of the Work, Changes Made, Decisions and Why, Open Issues, Next Steps, and Commands to Resume, then a two-line summary for me and any files you left uncommitted.

Example output

AI-written example
# HANDOFF.md

## Goal
Replace the in-memory rate limiter in `orders-api` with a Redis-backed one so limits hold across multiple instances. Target: all `/v1/*` routes limited to 100 req/min per API key.

## State of the Work
- Confirmed: new limiter is implemented and wired into `src/app.ts`.
- Confirmed: 41/42 unit tests pass; 1 integration test fails (see Open Issues).
- Not started: config docs, load test, removal of the old limiter.
- Branch: `feat/redis-rate-limit` (2 commits ahead of `main`, plus uncommitted work below).

## Changes Made
Verified with `git status` and `git diff --stat`:
- `src/middleware/redisRateLimiter.ts` (new, 88 lines): sliding-window limiter using a Lua script.
- `src/middleware/rateLimiter.ts` (modified): now exports a deprecation warning only.
- `src/app.ts` (modified): swaps the limiter and reads `REDIS_URL`.
- `src/config/env.ts` (modified): adds `REDIS_URL` and `RATE_LIMIT_PER_MIN` (default 100).
- `test/rateLimiter.test.ts` (modified): rewritten against `ioredis-mock`.
- `package.json`, `package-lock.json`: add `ioredis`, `ioredis-mock`.

## Decisions and Why
- **Sliding window via Lua, not fixed window.** Fixed windows allow 2x bursts at boundaries. The Lua script keeps the check and increment atomic. Rejected: `INCR` + `EXPIRE` (race on expiry).
- **Use `ioredis`, not `node-redis`.** The team already uses `ioredis` in the `jobs` service. Rejected: adding a second client library.
- **Fail open when Redis is down.** Requests pass and an error is logged, because an outage should not take down the API. Rejected: fail closed (returns 503s on every route).
- **Key by API key, fall back to IP.** Matches the existing behavior.

## Open Issues
- Confirmed failing:
  `npm run test:integration -- rateLimit`
  `Expected: 429  Received: 200` in `test/integration/rateLimit.int.test.ts:34`
- Guess (unverified): the integration setup still mounts the old limiter via `test/helpers/buildApp.ts`.
- Guess (unverified): `ioredis-mock` may not fully support `EVALSHA`, so the Lua path might behave differently from real Redis.
- `rateLimiter.ts` still exists, and nothing else imports it (checked with `grep -rn rateLimiter src test`).

## Next Steps
1. (5 min) Open `test/helpers/buildApp.ts` and check which limiter it imports. Switch it to `redisRateLimiter` if needed, then rerun the failing command above.
2. Run the integration test against real Redis: `docker run -d -p 6379:6379 redis:7` then `REDIS_URL=redis://localhost:6379 npm run test:integration`.
3. If step 2 passes but the mock does not, switch the unit tests to `testcontainers` or stub `eval`.
4. Add a "Rate limiting" section to `docs/configuration.md` covering both new env vars.
5. Delete `src/middleware/rateLimiter.ts` once nothing imports it.
6. Run `npx autocannon -c 50 -d 20 -H "x-api-key: test" http://localhost:3000/v1/orders` and confirm 429s begin near 100 req/min per key.
7. Commit in small pieces and open a PR against `main
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Use it at the end of a long session, before running /clear or closing the terminal. Start the next session by telling Claude Code to read the handoff file first.

Questions about this prompt

More in Claude Code

Typed Phase Handoff Contracts and Validator for Multi-Agent Pipelines

Has Claude Code define schema-based handoff contracts between agent phases, generate a validator, and add contract tests. Supports the decision of which phase boundaries need strict contracts versus lightweight checks.

Conventional Commit and PR Description Writer Skill (SKILL.md)

A ready-to-save SKILL.md that makes your coding agent write Conventional Commits messages and pull request descriptions from the staged diff, never from guesses.

Agent Run Post-Mortem: Trace Root Cause and Prompt or Tool Fixes

Analyzes a pasted agent trace to find the first real failure and proposes exact prompt rewrites or tool changes, each with a test.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Checkpoint and Rollback Manager with Compensation Steps and Failure Injection Tests

Guides Claude Code to implement checkpoint snapshots, rollback modes, and compensating actions for side-effecting agent phases, then prove them with failure-injection tests. Helps you decide the rollback strategy per phase.

Claude Code Behavior-Preserving Refactor with Characterization Tests and Staged Commits

Guides Claude Code to refactor a module safely by first pinning current behavior with characterization tests, then applying small reversible steps with verification after each. Delivers a diff, risk register, and rollback plan.

Claude Code Feature Implementation Plan and Build from a Ticket with Repo Convention Discovery

Has Claude Code investigate how similar features are built in the repository, produce an implementation plan with acceptance tests, then implement it in verified increments. Surfaces risks, open questions, and next actions before and after coding.

Claude Code Hook Writer: Auto-Run Lint, Typecheck or Tests After Edits

Produces a PostToolUse hook entry for settings.json, the script it calls and a concrete procedure to test that the check runs after file edits.

Claude Code Plan-Then-Implement a Feature With Approval Checkpoints

Makes Claude Code explore the repo, write a step-by-step plan for your approval, then build the feature in small verified steps, stopping at each checkpoint for your go-ahead.

Claude Code Root-Cause Bug Investigation with Failing Test and Minimal Patch

Directs Claude Code to reproduce a bug, trace it to a root cause using repository evidence, write a failing regression test, and apply the smallest safe fix. Ends with a verified diff, risks, and next actions.

Codebase Tour for a Specific Task

Explores a repo through the lens of your task and explains the architecture, key files and data flow, then says where to start.

Coding Agent Task Brief with Guardrails, Test Plan, and Rollback Steps

Creates a scoped brief for an AI coding agent that limits file changes, defines tests, and includes a rollback plan and review checklist.