You already have README.md, CONTRIBUTING.md, and CODEOWNERS. But your LLM agents still guess. That guesswork is now a production risk. This week’s HN thread asking for “AGENTS.md” is right: you need a simple, enforceable contract in the repo that tells bots what they can touch, what they must not, how much they can spend, and how to escalate when unsure.
If you think this is overkill, recall the last time a well-meaning bot opened a “quick fix” PR that broke infra or exploded a token budget. The cost wasn’t the revert—it was the lost confidence. Teams throttle or ban bots after one bad incident, then quietly reintroduce them without structure. That cycle wastes quarters.
What changed: bots aren’t assistants anymore—they’re actors
Two signals landed recently:
- Feature requests for a standardized AGENTS.md surfaced on HN, reflecting real pain: agents lack a shared, repo-local contract.
- Agent harnesses like OneCLI and emerging native agents (including “fx” on HN) make it trivial for teams to wire bots into CI/CD and repos. That’s great for velocity, terrible for consistency if every bot plays by different rules.
Meanwhile, your compliance posture didn’t get simpler. Your agents touch regulated data, ephemeral secrets, third-party APIs, and production workflows. Without a contract, every PR is a negotiation.
AGENTS.md: the minimal contract
Think of AGENTS.md as robots.txt for your repo—but with budgets, escalation paths, and risk tiers. Keep it crisp. One page that an LLM can parse and a human can own.
What to include (opinionated baseline)
- Scope and intent: What problems agents are allowed to solve in this repo. Example: “Documentation fixes, lint rule updates, test flakiness triage, safe refactors under 100 lines.”
- High-risk zones: Paths that are guarded or banned without explicit human approval. Example: “infra/ and migrations/ require CODEOWNERS approval even for bot-created PRs.”
- Data classification: What data agents may read or generate; what’s off-limits. Example: “Never include production PII in PRs or test fixtures. Use synthetic data only.”
- Tooling and endpoints: Allowed external tools, MCP servers, and internal services. Example: “May call internal test-runner MCP, must not call payment gateways.”
- Budget and rate limits: Per-PR and per-day spend caps with hard stops. Example: “Cap $10/PR model spend, $100/day per repo. Abort and escalate if exceeded.”
- Secrets and credentials: How short-lived tokens are provisioned; never ask humans for secrets in PRs. Example: “Use ephemeral, scoped tokens from CI vault. No static tokens.”
- Safe defaults: Classes of changes that can auto-merge under tests. Example: “Regenerate lockfiles + pass CI + under 50 LOC = eligible for auto-merge after 2 green builds.”
- Unsafe changes: Changes always requiring human review. Example: “Database schema, auth flows, payment logic, infra IaC, dependency adds/upgrades over patch level.”
- Observability and logs: What will be recorded, for how long, and where to inspect. Example: “All agent tool calls logged to observability/agents with 30-day retention.”
- Escalation path: Who to page and how when confidence is low. Example: “Open a draft PR with label needs-human and tag @team-leads within 30 minutes.”
- Model and quantization hints: Guidance that preserves determinism. Example: “Use GPT-4.1-mini for drafts, move to Sonnet for final; avoid aggressive quantization on tool-call heavy tasks.”
- Memory policy: Retention, authority, and provenance for agent memory. Example: “Weight memories with source and age; treat human comments in CODEOWNERS as higher authority than model self-notes; purge memories after 14 days.”
That’s it. One page. If you need more, link to deeper policy docs, but keep AGENTS.md as the high-signal interface—what an agent can ingest in a single context window and act on without ambiguity.
Make it enforceable: a tiny, machine-readable twin
AGENTS.md is for humans and LLMs. You also need a minimal machine-readable file (agents.yaml or agents.json) so CI and harnesses can enforce budgets, rate limits, path restrictions, and escalation rules. Keep the schema tiny, or it will rot.
A concrete minimal schema (expressed as bullets, not code)
- version: 1
- allowed_paths: ["docs/**", "src/**", "tests/**"]
- guarded_paths: ["infra/**", "migrations/**", "auth/**"]
- deny_paths: ["secrets/**", ".github/workflows/prod-deploy.yml"]
- max_loc_change: 100
- budget_usd_per_pr: 10
- budget_usd_per_day: 100
- allowed_tools: ["test-runner-mcp", "lint-mcp"]
- denied_endpoints: ["/payments/*"]
- memory_ttl_days: 14
- escalate_labels: ["needs-human"]
- escalate_mentions: ["@team-leads"]
Whether you use OneCLI, a homegrown harness, or a marketplace router, this file can gate behavior. If a PR exceeds max_loc_change or touches a guarded path, CI flips auto-merge off and requires CODEOWNERS. If the model burns through budget_usd_per_pr, the run aborts and labels the PR for human triage.
How to plug AGENTS.md into your stack
1) CI check: No AGENTS.md, no bot PRs
Block agent-originated PRs unless AGENTS.md and agents.yaml exist and validate. This is a one-hour gate to implement. If you can’t block by origin, detect PRs created by bot tokens or with typical agent metadata and apply the check. Failing the check should add a helpful comment pointing to a template.
2) Enforce budgets in the harness
Wrap your LLM client in a budget-aware proxy. For GitHub Actions, you can calculate spend by multiplying token usage by per-model cost (log both). Hard-stop at caps. Expose spend in a PR comment so reviewers see a simple ledger: $2.35 draft, $1.90 refine, $0.65 tests, total $4.90. If you’re nearshore and share cycles across pods, this transparency prevents the “mystery cloud bill” syndrome.
3) Path-aware policies
Integrate path rules into your PR policy bot. If a PR touches guarded_paths, it must have CODEOWNERS approval and can’t be auto-merged. If it touches deny_paths, the bot must close the PR with an explanation and escalate. This turns “guidance” into behavior, not promises.
4) Tool call allowlists
Most damaging incidents come from unexpected tool calls. If you use MCP servers, wire an allowlist from agents.yaml and audit actual calls. A denied call should generate a PR comment with the call, purpose, and a link to AGENTS.md. Treat tool-call diffs like you treat dependency diffs.
5) Weighted memory and TTL
One of the smarter critiques in the community: “Everything an agent remembers has the same authority, and that is the bug.” Build a weighted memory layer: human-authored project docs and CODEOWNERS are high authority; transient LLM self-notes are low. Decay memory by age. Enforce memory_ttl_days. Store provenance (who/what wrote it, when) with every entry. A single day of engineering prevents months of subtle drift.
6) Observability: tool-call and spend traces
Store every tool call with inputs, outputs, duration, and cost. Put them in a simple folder in the repo (for non-sensitive traces) or your observability backend. Keep 30 days by default; extend to 90 for regulated repos. If your agents run in Brazil and the US, label traces with region for data residency audits.
Rollout plan: 30-60-90 days
First 30 days: land the contract
- Draft a one-page AGENTS.md template. Keep it under 25 lines of policy plus links.
- Define the minimal agents.yaml schema (the bullets above). Publish a JSON Schema if you need validation.
- Add a CI check that blocks bot PRs in repos without both files. Provide a “Create from template” button in the failure message.
- Instrument your LLM client with budget caps and tracing. This is a 1–2 day task.
Days 31–60: enforce and tune
- Roll to your top 10 repos by PR volume. Expect 5–10 small policy exceptions that need explicit handling (e.g., migrations in a feature branch).
- Turn on path-aware auto-merge for safe changes under 50 LOC and green CI. Measure cycle time reduction. Teams usually see 20–30% faster merges for low-risk changes.
- Publish a support path. 6–8 hours overlap with Brazil-based pods is enough to settle policy disputes quickly.
Days 61–90: scale and measure
- Expand to 50+ repos. Triage “policy drift” weekly. The most common drift is guarded_paths missing a newly added infra/ subtree.
- Set quarterly targets: fewer than 1 revert per 100 bot PRs; sub-$5 median spend per bot PR; under 24 hours median time-to-merge for safe classes.
- Schedule a quarterly fire drill: intentionally violate a deny_path and confirm CI blocks and escalates.
Common objections—and answers
“This will slow us down.”
It speeds up the right changes. Safe classes auto-merge faster because reviewers aren’t scanning for surprises. Unsafe classes get faster because the rules are visible. You eliminate negotiation PR by PR.
“It will rot.”
It will if it’s long. Keep AGENTS.md short and plug rot-sensitive details into agents.yaml with CI validation. Make CODEOWNERS the owner of both files. If nobody owns it, it’s not policy.
“Our agents differ too much to standardize.”
That’s why the schema is minimal. Scope, paths, budgets, tools, escalation. Everything else can live in deeper docs per bot. The point is a contract the repo enforces, not an encyclopedia.
“We already wrote a Notion page.”
Docs not in the repo are invisible to agents and unenforceable by CI. Put the contract next to the code. Reference long-form policy in Notion if you must; the gate stays local.
Brazilian nearshore angle: who does the unglamorous plumbing?
The hard work here isn’t the paragraph you write in AGENTS.md. It’s the enforcement plumbing—budget caps, path-aware auto-merge, tool-call allowlists, memory TTLs, traces. If your platform team is underwater, a nearshore pod can land this in weeks:
- Standing up the CI gate and schema validation: 1–2 days.
- Wrappers for LLM spend tracking and hard caps: 2–4 days per language/runtime.
- MCP/tool allowlist + audit logging: 3–5 days.
- Path-aware PR policies tied to CODEOWNERS: 2 days.
- Org-wide rollout (50+ repos), training, and dashboards: 2–3 weeks.
You get 6–8 hours time zone overlap with US teams, and a clean handoff to your platform team after the first quarter with runbooks, not a black box.
Real-world numbers to aim for
- Token spend: Cap at $10/PR and $100/day/repo initially. Mature teams sit around $3–$7 per bot PR with clear scope.
- PR velocity: With safe-class auto-merge, expect 20–30% cycle time reduction for docs, lint, and small refactors.
- Incident rate: Reverts under 1% for bot PRs after the first month of tuning.
- Coverage: Top 50 repos covered in 60 days is achievable with a 2–3 person platform or nearshore pod.
Don’t overfit to a vendor—keep it portable
Vendors will change terms, throttle features, or gate capabilities. We’ve seen this story with model access and program shifts. AGENTS.md and agents.yaml should not reference proprietary features as hard dependencies. Treat the harness as pluggable: OneCLI today, your in-house runner tomorrow. The contract lives in the repo; the executor can change.
A minimal template you can copy today
Keep this under a page in AGENTS.md. Link out to details instead of bloating it.
- Scope: Docs edits, lint rules, tests, small refactors under 100 LOC.
- High-risk: infra/, migrations/, auth/ require CODEOWNERS approval. Do not touch prod deploy workflows.
- Data: No PII in PRs or fixtures. Use synthetic data only.
- Tools: Allowed MCP servers: test-runner, lint. Denied: any payment or secrets endpoints.
- Budgets: $10/PR, $100/day repo cap. Abort and label needs-human if exceeded.
- Secrets: Use ephemeral CI tokens only. Never commit credentials.
- Safe merges: Under 50 LOC, pass CI twice, no guarded paths: eligible for auto-merge.
- Unsafe: DB schema, auth, payments, infra—always human review.
- Memory: Weight human-authored docs highest, decay self-notes; purge after 14 days.
- Escalation: Label needs-human and tag @team-leads if unsure or blocked.
This isn’t ceremony—it’s an SLO for behavior
At some point this year you’ll run more bots than you have staff engineers. Without a contract, every one of those bots negotiates behavior at runtime. With a contract, you turn intent into code: budgets enforced, paths gated, memory bounded, and humans looped in when the machine is uncertain.
Add AGENTS.md and its tiny twin file. Treat them as part of your build bar. If a repository is unfit for a bot to read and follow, it’s unfit for a human to maintain without tribal knowledge.
Key Takeaways
- AGENTS.md is a one-page, repo-local contract that tells LLM bots what to do, what not to touch, how much to spend, and how to escalate.
- Pair it with a tiny agents.yaml so CI and harnesses can enforce budgets, path rules, and tool allowlists.
- Start with five essentials: scope, guarded/deny paths, budget caps, tool allowlists, and an escalation path.
- Instrument spend and tool calls; aim for $3–$7 median spend per bot PR and under 1% revert rate after tuning.
- Keep it portable across vendors and harnesses; the contract lives in the repo, not in a SaaS control panel.
- Roll out in 90 days: gate new bot PRs, cover top repos, and measure velocity and incident rates.
- If your platform team is stretched, a nearshore pod can land the plumbing in weeks, with 6–8 hours overlap and lower TCO.