L06 · Leave instructions the next agent can use
Skill packs and prompts are provided in English so they work best with the AI tools. Use them as-is.
Leave instructions the next agent can use
Learning time: about 23.9–35.4 active minutes. Choose ONE presentation: the text (about 5.4 minutes, estimated) OR the lesson video (3:51, measured). Then 20–30 minutes of practice and checking (estimated). Do not count both presentations. Setup delays and optional extra study are separate; learner timing has not yet been piloted.
Where you are: Module 3, lesson 2 of 2. Your brief has a checkpoint. You will separate stable rules from changing project status.
What you will do
Create concise project instructions and a complete handoff, then check that another agent received the intended context. Outcomes O3 and O4.
Teaching
A new agent may see the files without knowing which decision you approved or which test failed. Give the next worker a short set of stable rules and a separate record of the latest work.
Stable rules belong in the project's instruction file. For this course, the shared file is AGENTS.md. It should describe the project purpose, allowed workspace, synthetic-data rule, actions requiring human decisions, how to run known checks and where current status lives. Keep temporary status and transcripts elsewhere. Existing organization instructions may apply above the project; inspect them before introducing a new file.
Codex discovers applicable AGENTS.md guidance through its instruction-loading rules. Current Claude Code behavior is version/configuration dependent and considers its own instruction files. Official Claude documentation describes an @AGENTS.md import in CLAUDE.md as a shared-file route. Do not claim Claude always ignores AGENTS or that simply naming a file guarantees it was loaded. Inspect the current documentation and actual environment before changing configuration.
A minimal compatibility file can contain @AGENTS.md if that documented route fits the verified setup. Do not overwrite an existing CLAUDE.md. Read it, identify conflicting or additional instructions and make only an authorized change. Prose instructions influence an agent's behavior; they do not replace runtime access controls.
The changing record, HANDOFF.md, should name the project version, completed work, tests actually performed, unresolved issues, current writer, next bounded task and prohibited actions. Include the working-tree state because uncommitted files may be newer than the last commit. A commit identifier alone does not describe those edits. Include active jobs before interruption; a new conversation must not duplicate a running job.
Worked example
A poor handoff says, “The calculator is mostly done. Continue.” The next agent cannot tell which folder, which version, what remains broken or whether “continue” includes publishing.
A useful handoff says, “Workshop Launch Kit; local teaching repository and current branch identified below. Brief checkpoint recorded. Calculator not built. No jobs running. Next: read the brief and propose a file-level build plan. No edits, remote writes, spending or deployment in this task. Verify location and status before planning.” It supplies exact observed identifiers in the record, rather than invented sample hashes.
GitHub stores the files you actually push. It does not transfer an uncommitted handoff or give another agent your account permissions. Ask the recipient to verify what it received before acting. A different version is a reconciliation problem; it is not permission to overwrite either side.
Do it yourself
Draft the two records in your teaching folder. Stable rules should fit on a short page. Your handoff should be complete enough for someone who has not seen the conversation. Use only actual observed paths and versions; mark unknown fields unknown.
Give the current agent this complete request:
Prepare a context handoff for the fictional Workshop Launch Kit in the current confirmed teaching repository. Read existing AGENTS.md, CLAUDE.md and HANDOFF.md if present before suggesting changes. Do not overwrite existing instructions. Separate stable project rules from changing status. Preserve the brief: local calculator and supporting evidence, synthetic inputs only, no payment, booking, sending, spending or deployment.
Report the actual repository path, branch or detached state, latest commit, uncommitted changes, work completed, checks actually run, unresolved issues, known active jobs and the next bounded task. Do not infer a passed test or approval. Draft concise replacement or addition text for my review; do not edit files or run another agent. Explain how the installed clients will receive the shared instructions, and mark any unverified loading behavior.
Review the draft, save only the agreed records and make an inspected checkpoint. Then open the other agent in the same confirmed learning project and ask it to read the handoff without editing. Have it state the version, scope, next task, restrictions and one unresolved item. Compare that response with the files yourself. This is a context-transfer test; it does not yet authorize a build.
Feedback and retry
Pause here. The recipient should identify the correct project and current work without relying on your old chat. If it describes a previous version or invents a test, inspect which record it read and correct the handoff or access route. Keep the failed attempt as evidence. Do not solve a missing-context problem by granting broad permissions.
Retry by adding a harmless status note: “Awaiting local calculator build plan; no implementation approved in this task.” Save it, checkpoint or explicitly identify the uncommitted change, and ask the recipient to report the new state. A successful response must match the actual version it received. If no second tool is available, label the cross-agent check pending and complete the record work independently.
Check your understanding
Choose an answer and write one sentence explaining why before you read the answers.
- Should every temporary error be copied into AGENTS.md?
- A. No: keep temporary status in HANDOFF.md.
- B. Yes, so every agent sees it.
- C. Yes, but only errors from the last session.
- Does an instruction saying “never publish” technically disable all publishing tools?
- A. Yes.
- B. No: verify runtime controls and action scope.
- C. Yes, if it is written in capital letters.
- If a handoff says tests passed but no record exists, what should the recipient report?
- A. That the tests passed, as the handoff says.
- B. That the tests failed.
- C. That the claim is unverified until evidence or a new authorised test exists.
Answers
- A. No. Keep temporary status in HANDOFF.md; AGENTS.md holds durable instructions.
- B. No. Verify runtime controls and action scope.
- C. The claim is unverified until evidence or a new authorised test exists.
Summary
Preserve stable rules once and keep current status explicit. Test what the next agent received before assigning work.
Sources
Anthropic, How Claude remembers your project; OpenAI, AGENTS.md; GitHub, GitHub flow. Reviewed 8 November 2026. Handoff fields are original course recommendations, not guaranteed cross-client behavior.
