ai / context

updated October 21, 2026

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

I 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.

An example layout for an app component:

# ui / AGENTS.md

## Quick reference

go test ./ui/...
browse http://localhost:2000/ -o ui/screenshots/home.png

## Safety rails

Never commit operational secrets.

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 the Checkfile enforces it. An app's ui/AGENTS.md asks for a screenshot of a changed page and names the command that takes one: browse.

The Checkfile defines the gate:

test: go test ./...
private: if grep -rnE 'BEGIN (RSA|EC) PRIVATE KEY' .; then exit 1; fi

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.

docs/plans/
├── 001-code-block-guidelines.md
└── 002-cache-invalidation.md

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.

← All articles