I do most of my scripting and server work these days with an AI coding agent in the terminal. It is excellent until the context window fills up, the session gets summarised, or I come back the next morning and the agent has forgotten what it was doing. After losing the same half hour a few too many times, I settled on three files per project that fix it. This is the protocol I now bootstrap into every project folder.
Three files, three jobs
AGENTS.md holds stable instructions: what the project is for, which servers and accounts it touches, which tools to use and which to avoid, and any rules that never change. It is read first on every resume and it rarely changes.
HANDOFF.md is the resumable state. It is short and it is always current. It answers five questions:
- Current goal: what are we trying to finish right now
- Done: what has been completed, with dates
- Next exact step: the very next command or edit, specific enough to run blind
- Files touched: so nothing gets edited twice by accident
- Risks and blockers: anything that needs a human decision
SESSION-TAIL.md is a rolling log of the last ten to twenty meaningful entries: an investigation result, a decision and the trade-off behind it, a validation that passed, a blocker found. It is a summary, never a transcript, and old entries get trimmed.
When to refresh
The rule I give the agent is to refresh HANDOFF.md after any discrete task, after a batch of file changes, before any risky operation, before stopping, and whenever the context is getting tight. SESSION-TAIL.md gets an entry when something was learned or decided. On resume it reads AGENTS.md first, HANDOFF.md second, and SESSION-TAIL.md only if it needs more detail.
The “before any risky operation” rule turned out to be the most valuable. If a solution import or a firewall change goes wrong, the handoff file already says what was about to happen and why.
Bootstrapping
A short shell script creates the three files from templates and drops the protocol text into the project’s instructions file so the agent knows the rules without being told.
bootstrap-ai-project.sh ~/projects/new-thing
# creates AGENTS.md, HANDOFF.md, SESSION-TAIL.md with headings
Because the rules live in a file the agent reads, the same protocol works with Claude Code, Codex and anything else that reads instructions from the repository.
What changed
Resumes went from “let me look around” to a one-line summary of where we are and the next command. Projects I had not touched for three months came back in a minute. And when I hand a problem to a colleague, HANDOFF.md is the briefing. The files are plain Markdown, they live in the repository, and they cost nothing. Start with HANDOFF.md if you only adopt one.