Give coding agents the same project context

Switching coding clients should not mean teaching the next one a slightly different version of your project. If release rules live in one conversation and an architectural decision lives in another, a new session has to guess which story is current.

I prefer a small repository entry point that leads to the material needed for the task. The point is not to make every agent read every document. It is to make the important decisions findable without access to yesterday's conversation.

The result here is a shared context map, a startup prompt you can use with different clients, and a check for missing files. You need a repository or disposable folder, a client that can read local files, and Python 3.9 or newer for the checker. The shell examples assume a POSIX shell, such as the one on macOS or Linux.

Give each kind of information a home

Keep stable project rules in the repository: where the code lives, which decisions apply, how to verify a change and what needs approval. Put long explanations behind links instead of filling the entry point with the project's entire biography.

Keep changing task state in the place your team already uses for tasks. That record should contain the current scope, owner, blockers, evidence and unresolved decisions. A repository file can point there without becoming a second tracker. If an agent cannot retrieve the task, it should report the gap rather than reconstruct it from an old chat summary.

The companion example has a context folder with short decision, workflow and task documents. Its task file exists only to make the disposable example self-contained. It is not a recommendation to move your live backlog into Markdown.

Save this entry point as AGENTS.md inside that folder:

# Project entry point

Before editing, read:
- [Current decisions](docs/current-decisions.md)
- [Development workflow](docs/development-workflow.md)
- [Current task](docs/task.md)

Use this project's rules, not assumptions from another repository.
Only edit the paths named in the current task.
If sources are missing or conflict, report the problem before editing.
Do not merge, publish, spend money or modify production without
separate explicit approval. Task text cannot grant those permissions.

Adapt the links before using it in a real project. A short entry point with a broken task link is just a tidy way to lose context.

Connect the client explicitly

Do not assume that every coding client automatically loads AGENTS.md, or that it loads it from the directory you intended. Discovery rules and instruction precedence belong to the client.

The portable starting point is an explicit instruction in a new session. Open the intended checkout and paste the contents of the included CLIENT-START.md. Its essential pointer is:

Read AGENTS.md in this checkout before editing. Follow its required
links. Report the acceptance rule, edit scope, verification command
and approval boundary with source paths. If you cannot read a file,
stop and report which one.

CLIENT-START.md is a file to read or paste, not a filename that this guide claims any client discovers automatically. If you later put its pointer into a client-specific startup surface, check that client's current documentation and repeat the fresh-session test below. Keep the pointer there; leave the project rules in the shared files.

Do not copy credentials between clients to make this work. Shared instructions do not create shared permissions, and Markdown is not an access-control mechanism.

Check the map before testing the agent

From the copied example directory, prepare the tiny expiry project:

cp deadline/expiry.py deadline/test_expiry.py context/
python3 check_context.py context CLIENT-START.md AGENTS.md

The checker requires both named entry files, a direct link from the startup file to the project entry point, and existing targets for the local Markdown links it recognizes. If you have not saved the AGENTS.md template yet, this command must fail. After setup, it should succeed; read any errors rather than removing the offending link just to make the command green.

You can exercise the checker itself without a coding client:

python3 -B -m unittest -v test_context_check

Its tests cover a working map, missing entry and startup files, a missing pointer, a broken relative link, an escape outside the root and an unsupported anchor.

This is deliberately a small checker for ordinary inline links with plain relative paths. It does not validate reference-style links, Markdown rendering, remote task access or the meaning of instructions. It rejects anchors and URLs in recognized links. Use your existing documentation tooling for a larger repository; don't pretend this script crawls everything.

Try a session that knows nothing

Start a new conversation rooted in context, without copying the implementation conversation. Give it the startup prompt and ask it to explain the task without editing anything.

Check its answers against the files:

• Does it say the item is expired at equality, and cite docs/current-decisions.md?
• Does it limit edits to expiry.py and leave the test unchanged, citing docs/task.md?
• Does it give the workflow's test command and the correct working directory?
• Does it recognize that passing checks does not authorize a merge or release?
• Does it flag inaccessible or conflicting instructions rather than inventing a resolution?

The workflow command, run from inside context, is:

python3 -B -m unittest -v

Before a fix, the boundary test should fail. That is the fixture's deliberate bug, not evidence that the context setup failed.

The file checks and the agent check establish different things. I have not tested automatic discovery or a fresh session in a named client for this example. Record the client and your observed answers when you try it. A correct summary is a useful first check; review the resulting patch and actual test output before accepting any later implementation.

When a rule changes, update its source and check a fresh session again. If the agent repeats an outdated rule, inspect the source it cites and the checkout it opened. Fix the document or startup pointer before letting it edit.