ai / context
Context is what an agent reads before it acts. Most of it is already on disk. For a coding agent, that is the code. For a personal assistant such as Instinct, that is the notes it wrote about past work. The rest is a small set of files I write for the agent. This article covers the coding case.
AGENTS.md
We check AGENTS.md files into the repo. The root file covers
architecture and quick reference. A subdirectory file
(db/AGENTS.md, ui/AGENTS.md) holds the rules for that directory.
An agent that edits a template reads the template rules and not the
database rules.
Useful sections:
- Quick reference. Runnable commands for build, test, lint, and migrate.
- Safety rails. Explicit rules like "never commit secrets."
- Conditional checks. "Run X if Y files touched" to keep feedback fast. See go / checks.
- Style guides. Commit message conventions and naming patterns.
- Environment context. Available tools, port numbers, and file paths.
Rules with a check
A rule holds when a script checks it. This blog's articles/AGENTS.md
keeps private details out of an article, and a scan in bin/pre-push
enforces it. An app's ui/AGENTS.md asks for a screenshot of a changed
page and names the command that takes one: browse. A
rule with no check drifts.
Plans
For a change larger than a fix, I draft a plan in the project's
docs/plans with the agent and commit it. The plan is context for the
agent that implements and a record for me. See
git / workflow.
What I keep out
The agent sends a context file to a model provider in a prompt, and the file stays in the repo history. So the files hold none of these:
- Credentials. A token, key, or password. The file names the environment variable instead.
- Personal data. A customer's name, email, or record. A test fixture uses made-up values.
- Operational identifiers. A host name, IP address, account ID, or bucket name. These identify a live resource and help an attacker map the system. The file describes the architecture and points at where the value comes from, such as a config key.