A coding assistant opens your project and runs a test command copied from an old conversation. The command fails. It then spends several turns looking for a tool your project does not use.

A project handover can prevent that particular confusion, provided its facts are current. It cannot promise correct code.

For a developer maintaining a small utility, the useful question is: which instructions should stay with the project, and which belong only to today’s task? You will finish two editable notes: a standing AGENTS.md file and a separate task brief. You can prepare both in a text editor without installing a coding assistant.

Here is the complete example in miniature:

Input to the handover Finished instruction
A plain-text hashtag utility, using Python’s standard library No package installation is required
Implementation in tags.py; checks in test_tags.py Run python -m unittest -q from the project folder
Today’s task: remove repeated tags without changing their order Keep that request in the task brief
Example input: #Beta #alpha #BETA Required result: beta, alpha

Original educational example. The optional local program below produced that result. No coding-agent product was connected or benchmarked.

The distinction matters when you return next week. “Use the standard library” may still be relevant. “Add duplicate removal” should not remain as an unfinished instruction after the feature is complete.

What AGENTS.md actually gives you

AGENTS.md is an ordinary Markdown file for project guidance, using readable headings and text. The open format’s documentation describes it as a place for coding-agent instructions alongside human-oriented documentation.

It is not a special executable file, an access-control system or proof that a model followed anything. The surrounding coding tool decides whether to discover and include it.

Support also varies by product and mode. GitHub’s custom-instructions documentation describes agent instruction files and their directory scope. Do not assume that an arbitrary chat window reads a file just because you saved it.

If you have one small task, pasting a short verified brief into your existing assistant may be sufficient. A standing file becomes useful when the same project requirements need to travel with future tasks or other contributors. That is a maintenance choice, not a reason to build an agent system.

The research does not support a magic template

Two studies make this a question worth testing rather than a formatting ritual.

Gloaguen and colleagues’ June 23, 2026 revision examines context files across coding-agent task-resolution experiments. It reports that adding context files did not generally improve success and increased cost in the studied settings. Its analysis also found no clear relationship between file length and success. “Shorter always wins” would misrepresent that evidence.

Lulla and colleagues’ March 30, 2026 revision reports lower runtime and output-token use in its paired experiments. But its methods explicitly place comprehensive correctness evaluation outside the study’s scope. A faster run and an accepted correct change are different outcomes.

These preprints use different designs and measures. Neither establishes that the sample below will improve your assistant. The practical aim here is narrower: write instructions whose commands, files and expected result can be checked.

1. Separate project facts from today’s request

Start by reading the project’s current files and existing instructions. Do not ask an assistant to turn every README paragraph into another document.

For this example, all the approved facts are visible:

  • The utility extracts ASCII hashtags from plain text.
  • Python 3.12 and its standard library are sufficient.
  • tags.py contains the implementation.
  • test_tags.py contains three behavior checks.
  • The checks run from the folder containing both files.
  • Inputs should remain unchanged. New dependencies or network calls need a separate decision.

These facts describe a deliberately small teaching program. It does not parse every Markdown construct, and it does not inspect private repositories.

Copy this complete standing file, then edit it for your own project:

# Project handover
This small Python 3.12 tool extracts ASCII hashtags from plain text.
Use the standard library; no package installation is required.
Run checks from this folder: python -m unittest -q
Implementation: tags.py. Behavior checks: test_tags.py.
Keep input read-only; ask before adding network calls or dependencies.
Report changed files, command results and anything not checked.

A real project may need different commands, a working directory, a required service or additional compatibility rules. Include those when they matter. Do not invent an installation command to fill a template’s empty heading.

The request about network calls expresses project policy. Actual tool permissions still require enforcement by the coding environment and human review.

2. Give the task a visible result

Save today’s request separately, or paste it into the assistant’s task message:

Add case-insensitive duplicate removal while preserving first-seen order.
Input: #Beta #alpha #BETA
Required result: beta, alpha
Keep the empty-input and numeric-start behavior.
Acceptance: all three tests in test_tags.py pass.

This is a feature request, not an instruction to recreate the whole project. “Preserving first-seen order” matters: alphabetically sorted output would be different even though it contains the same two words.

A complete copyable instruction for an assistant is:

Read the project handover and the task brief above. Before editing, identify the implementation file, working directory and test command. Report any missing file or disagreement with the current project instead of guessing. Propose the smallest change for the requested behavior. Show the resulting tag order and the actual check result. Do not report checks as passed unless they ran.

The files do not need to be called task.md in your own work. The important part is that a temporary request does not silently become permanent project policy.

A stale filename is a useful warning

Suppose the brief says the acceptance checks are in test_old.py. That file does not exist in the supplied project.

This is a seeded mistake. The repair is to inspect the actual files and update the brief to test_tags.py, not create an empty old file to make the instruction appear satisfied.

Likewise, a response that returns alpha, beta fails the required order. Keeping these two failures visible tests different things: whether the handover points to reality, and whether the implementation meets the task.

Optional: create the complete example and run its checks

The main route is the two editable notes above. This optional local route supplies the actual tiny utility, checks and handover files. It creates no new hosted service and calls no model.

With Python 3.12 and a text editor, create an empty folder. Save the following complete file as example.py; no package installation or other input file is needed.

from pathlib import Path
import os
import subprocess
import sys

root = Path("tag-demo")
if root.exists():
    raise SystemExit("Keep tag-demo; use a clean folder.")
root.mkdir()
files = {
    "tags.py": """import re

def extract(text):
    words = re.findall(r"(?<!\\w)#([A-Za-z][A-Za-z0-9_]*)", text)
    return list(dict.fromkeys(word.lower() for word in words))
""",
    "test_tags.py": """import unittest
from tags import extract

class TagsTest(unittest.TestCase):
    def test_order_and_duplicates(self):
        self.assertEqual(extract("#Beta #alpha #BETA"), ["beta", "alpha"])
    def test_empty(self):
        self.assertEqual(extract("No tags here"), [])
    def test_numeric_start(self):
        self.assertEqual(extract("#123 #ready"), ["ready"])
""",
    "AGENTS.md": """# Project handover
This small Python 3.12 tool extracts ASCII hashtags from plain text.
Use the standard library; no package installation is required.
Run checks from this folder: python -m unittest -q
Implementation: tags.py. Behavior checks: test_tags.py.
Keep input read-only; ask before adding network calls or dependencies.
Report changed files, command results and anything not checked.
""",
    "task.md": """Add case-insensitive duplicate removal while preserving first-seen order.
Input: #Beta #alpha #BETA
Required result: beta, alpha
Keep the empty-input and numeric-start behavior.
Acceptance: all three tests in test_tags.py pass.
""",
}
for name, content in files.items():
    (root / name).write_text(content, encoding="utf-8")
run = subprocess.run([sys.executable, "-m", "unittest", "-q"],
    cwd=root, env={"PATH": os.defpath}, capture_output=True, text=True)
assert run.returncode == 0, run.stderr
assert "Ran 3 tests" in run.stderr and "OK" in run.stderr
assert not run.stdout
probe = subprocess.run([sys.executable, "-c",
    "from tags import extract; print(', '.join(extract('#Beta #alpha #BETA')))"],
    cwd=root, env={"PATH": os.defpath}, capture_output=True, text=True)
assert probe.returncode == 0 and probe.stdout == "beta, alpha\n"
assert not probe.stderr
assert not (root / "test_old.py").exists()
print("CREATED: tags.py,test_tags.py,AGENTS.md,task.md")
print("CHECKS: 3 tests passed")
print("RESULT: " + probe.stdout.strip())
print("SEEDED MISTAKE: test_old.py is absent; use test_tags.py")
print("MODEL EXECUTION: none; local example only")

Run python -I example.py from that empty folder. The program creates a new tag-demo folder containing all four files and runs the local checks. It was executed with Python 3.12.14 and a credential-free environment.

Expected complete stdout:

CREATED: tags.py,test_tags.py,AGENTS.md,task.md
CHECKS: 3 tests passed
RESULT: beta, alpha
SEEDED MISTAKE: test_old.py is absent; use test_tags.py
MODEL EXECUTION: none; local example only

The internal test runner writes a variable-duration summary to its own captured error stream. The wrapper verifies that three tests passed and prints the stable summary above. Match the wrapper’s complete stdout, then inspect the four files.

For a meaningful negative case, edit tag-demo/tags.py and replace list(dict.fromkeys(word.lower() for word in words)) with sorted(set(word.lower() for word in words)). Run python -m unittest -q inside tag-demo. One test must fail because the order changes. Restore the original expression and rerun: all three must pass. This failure and repair were executed during technical review.

These tests check the teaching utility, not whether an instruction file makes a coding agent better. The implementation and notes are same-session AI-authored educational material, not a separate model trial.

Check discovery before judging obedience

For your own coding tool, consult its current instructions documentation. VS Code’s guide describes checking applied instructions and discovery settings. JetBrains’ guide distinguishes agent files from its chat-specific project rules.

Those interfaces were inspected in documentation, not operated for this article. No screenshots or successful loading receipt from either product are claimed.

If instructions seem ignored, first check the selected tool, supported filename, workspace and directory scope. Do not keep enlarging the file before establishing that the intended text was loaded.

Troubleshooting the example: preserve an existing tag-demo folder and use a clean folder for another run. If Python is unavailable, use the manual notes. If the test command fails, read the error before changing instructions or adding packages.

What you can verify before handing over work

The finished artifact is a current project handover plus a concrete task brief. Independently confirm that their filenames exist, the command runs in the named folder and the example preserves beta, alpha rather than sorting it.

The author performed technical and editorial checks in the same AI authoring session. Independent reader testing and a controlled coding-agent comparison remain outstanding. Setup, review, repair, failed attempts, maintenance and provider charges were not measured; no savings or model-performance claim follows.

On your next real task, record which instructions the tool actually loaded, the raw proposed change, failed checks and human corrections. Compare accepted results as well as total effort before deciding whether to keep the handover.

This adapts the journal’s context-pack lesson to coding work. The start guide places context, tools and human review within the broader assistant learning path.