# Treat AGENTS.md as a delivery contract before you scale coding agents > Repository instruction files tell agents — and partners — how your codebase actually works. What to put in AGENTS.md, what to leave out, and how to review it like a living delivery contract. - Author: Ananya Desai - Published: 2026-10-27 - Canonical: https://www.threeindex.com/blog/agents-md-as-a-delivery-contract - Tags: AI, Delivery - Related: https://www.threeindex.com/services/dedicated-development-team ## Context failures beat model failures When coding agents miss the mark, the usual cause is missing context: the hidden coupling, the convention nobody wrote down, the reason a hack exists. Industry radar and agent platforms keep converging on the same fix — repository instruction files such as AGENTS.md or vendor equivalents. Folklore "AI skills" that expire in a quarter are not a delivery system. A short, owned file in the repo is. It travels with the code, survives tool churn, and applies to partners the same way it applies to agents. If your first viewport of the repo cannot tell an outsider how to run tests and what not to touch, neither a human nor an agent will ship safely at speed. ## What belongs in the contract State the stack, package managers and the one true way to run lint, tests and local apps. Link to deeper docs; do not paste a novel. Name forbidden zones: generated folders, production secrets paths, migrations that need a human DBA, vendor lock-in traps. Agents follow explicit "do not" lists better than vibes. Describe PR expectations: size, required checks, who owns security-sensitive paths (workflows, auth, billing). That is the same delivery discipline that matters when AI multiplies change volume. Keep voice practical. Prompt theatre ("you are an elite engineer") ages poorly; commands and constraints do not. ## What does not belong Do not dump the entire architecture into AGENTS.md. Point to ADRs and canonical modules. Duplication drifts within a week. Do not encode secrets, customer data samples or production URLs. Instruction files are often copied into prompts and logs. Do not treat the file as a substitute for review. Agents that open PRs still need humans on high-blast-radius paths — workflows, IAM, payments — just as before. Avoid vendor-only lock-in when you can. Prefer a portable AGENTS.md plus thin vendor overlays so switching tools does not erase your contract. ## One contract for agents and partners Dedicated teams and agencies fail the same way agents do: they invent local conventions because the repo never stated yours. Put the golden path in writing where onboarding starts. Client-owned repositories make the contract real. If the only copy of "how we ship" lives in a partner wiki you do not control, you do not own delivery. See why client-owned repositories matter. When you brief a partner, attach the instruction file and ask them to extend it — not to invent a parallel README that contradicts CI. ## Review the file like code Change AGENTS.md through PRs. A silent edit that removes a security constraint is a production incident waiting for an agent to obey it. Version the expectations with the stack. When you migrate package managers or test runners, update the contract in the same change set. Spot-check that agents actually read it. If your tool prefers another filename, symlink or mirror — do not maintain three conflicting sources of truth. Measure usefulness: fewer "wrong folder" PRs and fewer repeat explanations in review comments. Vanity prompt length is not a KPI. ## Tie it to golden paths and CI Instruction files work when the commands they advertise are true. Broken npm test docs train agents to improvise — and humans too. Platform golden paths — templates, Actions, lint rules — should match what AGENTS.md claims. Divergence is how vibe coding skips review and still looks green. Related: platform engineering golden paths and vibe coding without a review. As agent PR volume rises, keep workflow and auth paths human-gated even when the instruction file says "run the suite." Speed without validation is still a bottleneck elsewhere. ## A minimal starter outline Purpose (one paragraph). Stack and package commands. Test and lint. Branch and PR rules. Forbidden paths. Security-sensitive directories. Where to find ADRs. How to ask for help (owner channel). Ship that in a day. Expand only when agents or partners repeatedly miss the same rule — evidence-driven, not aspirational encyclopedias. Revisit quarterly. Tooling churns; a stale contract is worse than a short honest one. ## How Three Index uses repo contracts in delivery Our dedicated development teams work in repositories you own, with written scope and two-week increments. Instruction files are part of onboarding — for people and for the AI tools squads already run. We also audit vibe-coded or agent-heavy setups via vibe coding reviews so conventions, CI and ownership catch up with throughput. We will not pretend a markdown file replaces product judgement. We will help you write a contract agents and partners can follow without inventing risk. Send a brief with how you ship today and which agent tools are in play. We will propose an AGENTS.md outline and the CI checks that make it true. ## FAQ ### What is AGENTS.md for? A repo-root instruction file that coding agents (and humans) read for conventions, forbidden paths, test commands and review expectations — so automation follows how your team actually ships. ### Is AGENTS.md a substitute for architecture decisions? No. It points agents at the decisions you already made. Architecture still lives in ADRs, code and reviews. The file reduces context failures; it does not invent product judgement. ### How can Three Index help teams adopt agent-ready repos? We onboard in client-owned repositories with written scope, golden paths and review habits — including instruction files that keep AI-assisted and human delivery aligned. ## About Three Index Three Index builds web, mobile, cloud and AI software from Ahmedabad, India. Founded in 2020. - Site: https://www.threeindex.com/ - Contact: https://www.threeindex.com/contact - LLM index: https://www.threeindex.com/llms.txt