# Hand off agent sessions with decision logs (free sample)

A free sample from Vibe Coding with AI Agents by PaperChaseWebb. Written for Claude Code, Codex and Claude.

Long agent chats get slow, expensive and forgetful. A new chat is fast but starts with no idea why the code looks the way it does. Two small files and one skill fix most of that. The idea comes from builders in our October 2026 research, including the author of the Kronograf watch firmware (u/cyberdinn on r/ClaudeAI), who kept a decision log and a blocker log so a fresh session could pick up the reasoning, not just the code.

## The rule

Add this to AGENTS.md or CLAUDE.md:

```text
Read DECISIONS.md and BLOCKERS.md before starting. Before you stop, add any new decision with its reason, and any failure with what you tried. When the chat gets long, write HANDOFF.md so a new session can continue.
```

## DECISIONS.md

```markdown
## D[n]. [Short title] ([date])
- Choice: [what we did]
- Why: [the reason, with the measurement if there was one]
- Rejected: [what else we tried]
```

## BLOCKERS.md

```markdown
## B[n]. [Symptom] ([date], open or solved)
- Seen: [exact error or behavior]
- Tried: [each attempt and result]
- Next: [what to try next, or the fix]
```

## The handoff-writer skill

Save as `.claude/skills/handoff-writer/SKILL.md` (Claude Code) or paste into AGENTS.md (Codex).

```markdown
---
name: handoff-writer
description: Use when a session is long, slow or about to end, so a fresh session can continue.
---
1. Write HANDOFF.md: current goal, done this session, open tasks in order, files changed, traps.
2. Add new decisions to DECISIONS.md with the reason and any measurement.
3. Add anything that failed to BLOCKERS.md with what was tried.
4. Summarize large logs and data files to their shape. Do not paste them.
5. Never copy secrets, tokens or personal data into these files.
```

The full pack adds the seven-step method, 18 prompts, four more skills, release and hardware checklists, cost notes and 24 project ideas.