Codex Session Handoff

Codex Session Handoff

Purpose

Keep a project-local restart document current so a fresh coding agent can resume work without replaying the full conversation. Treat the handoff as an engineering checkpoint, not as a narrative recap.

When To Use

• handoff 만들어줘
• HANDOFF.md 갱신해줘
• 새 채팅으로 넘길 개발 요약 작성해줘
• continue in a new Codex chat
• leave a restart note for the next agent
• prepare a transfer artifact for this coding task

Do not use this skill for resumes, career documents, investing discussions, or casual conversation summaries.

Operating Model

1. Confirm the request is about preserving development context.
2. Choose the handoff location.
3. Read the current handoff file first if it already exists.
4. Rebuild the current state from the thread and the local repo.
5. Replace stale notes with current facts.
6. Write the refreshed handoff file.
7. Tell the user what file was created or updated and what still needs verification.

Target File Policy

• Default target: project root HANDOFF.md
• If docs/HANDOFF.md already exists, update that file instead of creating a second document
• If the user explicitly asks for a different location, use the requested path
• Never create both HANDOFF.md and docs/HANDOFF.md unless the user explicitly asks for duplicate copies

Source Material

Prefer confirmed local state over memory. Pull from:

• the latest user goal and scope changes
• files changed, inspected, or still pending
• repo status and recent command results
• test, build, lint, or runtime verification already performed
• blockers, rejected approaches, assumptions, and constraints
• currently relevant services, ports, and environment details

If local repo state is available, these checks are usually enough:

• git status --short --branch
• git diff --stat
• targeted reads of touched files
• fast verification commands only when they are already known, cheap, or necessary to avoid writing something false

Do not inflate the handoff with speculative details or expensive reconnaissance.

Writing Rules

• Prefer concrete facts over prose.
• If something is unknown, write unknown.
• Remove outdated next steps when they no longer match reality.
• Preserve decisions that matter for future work.
• Call out anything the next agent should avoid repeating.
• Never include secrets, tokens, passwords, or credential values.

Handoff Template

Write the handoff file in Markdown using these sections and this order.

OBJECTIVE

• Original user goal
• Latest user instruction or scope change

SESSION SNAPSHOT

• One of complete, in_progress, blocked, iterating
• One sentence on current progress

WORK COMPLETED

• Concrete completed work
• Important findings and conclusions
• Work explicitly ruled out
• Work that must not be redone

PROJECT SURFACE

• changed: path and what changed
• inspected: path and why it mattered
• pending: path and what still needs work
• Include line references when useful

REPO CHECKPOINT

• Current branch
• Staged changes
• Unstaged changes
• Recent commits if relevant
• Conflict, merge, or rebase state if relevant

VALIDATION

• Important commands run
• Build, test, lint, and runtime checks
• Separate verified from not_verified
• Include error text only when it affects continuation

DECISIONS

• Key technical decisions and rationale
• Rejected approaches that should not be retried without new evidence
• Constraints, assumptions, blockers, and risks

OPERATING CONTEXT

• Running dev servers, ports, background processes, and required services
• Local environment assumptions
• Never include credentials

RESUME HERE

• The exact first thing the next Codex turn should do
• Mention what remains unverified

Response To The User

After writing the file:

• Report the exact path written.
• Summarize whether this was a create or update.
• Mention any important unknowns or unverified areas.
• Do not dump the entire handoff file into chat unless the user asks.

Style

• Use short bullets, not long paragraphs.
• Prefer exact paths, commands, branch names, statuses, and ports.
• Be concise and operational.
• Preserve momentum and avoid reopening settled decisions.
• If code changed, explicitly state what changed, what was verified, and what still needs verification.