← Library · Concept
Agent context contracts — local rules the model must not guess
A context contract states a project’s local rules: what an agent may change, how it should proceed, how to verify a change, and when to hand work to a person. It limits guesswork where a general prompt is insufficient.
Golden rule: An agent should not guess a project’s unwritten rules. If it can change a repository or data, it must find readable instructions, boundaries, and a way to verify work before acting.
Why a general prompt is not enough
An agent works in a specific environment. “Be careful” does not say that a directory is generated, that a person runs migrations, or which tests verify a change. OpenAI lists explicit instructions and guardrails alongside the model and tools as agent design foundations. Its practical guide to building agents recommends turning existing procedures into clear steps and covering common exceptions.
A context contract makes this local knowledge available before work begins. It may be an AGENTS.md file, a README in a subdirectory, tool rules, or a short checklist. The name is less important than placement, currency, and specificity.
What belongs in the contract
Keep it short and actionable:
- where to start reading and which instructions take priority;
- which files or systems the agent must not change;
- what counts as a small reversible change and what needs approval;
- exact commands or steps for verification;
- when to stop and hand work to a person.
Instead of “maintain quality,” write: “After editing this template, run the order test; do not create migration files without an approved ticket.” That rule gives both an action and a boundary.
Local rules need an order
A project can have shared rules as well as rules for a database, content, or infrastructure. Local instructions may refine a general rule, but must not quietly expand permissions or bypass a safety check. The Codex documentation for AGENTS.md describes an instruction-file hierarchy based on location in the project.
If rules conflict or information for an irreversible step is missing, guessing is not a valid outcome. The agent should surface the conflict and ask for a decision.
A practical example
A team asks an agent to fix copy in a web application. The contract for that area tells it where the source lives, that translations change together, how to run the template check, and that an editor publishes the result. The agent should prepare and verify a diff, leaving publication to the editor. If publishing must be prohibited, permissions—not contract text alone—must enforce that prohibition.
Limits of a contract
A contract does not guarantee that a model will make the right decision, and it does not replace tests, review, or limited permissions. It must not contain secrets or instructions for bypassing controls. It is an operating map: it reduces the room for guesses and gives a person a predictable place to intervene.