AGENTS.md Examples from Open Source

The fastest way to understand AGENTS.md is to read good examples. Not perfect examples. Good ones. The kind that make a repo legible to an agent in the first 60 seconds: what this project is, how to run it, what not to touch, where the truth lives, and what local traps have already hurt someone.

This post walks through representative AGENTS.md patterns I would expect to see in real open-source repos. Some are modeled after public conventions, including OpenAI's Codex repo and the broader AGENTS.md ecosystem. Others are synthesized from audit patterns: Vercel-style frontend apps, Rust backends, Python uv projects, and monorepos. Treat the snippets as copy-paste starting points, not sacred templates.

The point is not that every project should look the same. The point is that a good AGENTS.md makes the important differences obvious.

Example one: Codex-style repository guidance

Large agent-facing repos tend to need rules about code shape, review discipline, generated artifacts, and tests. The useful pattern is specificity without turning the file into a handbook.

# AGENTS.md

## Repository guidelines
- Prefer small modules. If a Rust file is already over 800 lines, add new
  behavior in a new module unless there is a documented reason not to.
- Avoid helper functions that are referenced only once.
- When adding or changing a public API, update the docs in docs/ in the same PR.
- Use existing test helpers before adding new fixtures.

## Rust style
- Prefer exhaustive match statements. Avoid wildcard arms unless the type is
  intentionally open-ended.
- Avoid bool parameters in new APIs. Use enums, named methods, or newtypes when
  the callsite would otherwise read like `foo(false)`.
- Prefer comparing whole values in tests over asserting one field at a time.

## Validation
- Run cargo test for the crate you touched.
- UI text or snapshot output changes require updated snapshots.

Why it works: every rule changes an edit. "Avoid bool parameters" affects API design. "Update docs" creates a reviewable artifact. "Run cargo test for the crate you touched" scopes validation without pretending every contributor can run the whole world every time.

The file is also honest about what AGENTS.md can do. It does not say "ensure quality." It names behaviors that reviews and tests can catch.

Example two: Vercel-style frontend project

Frontend AGENTS.md files fail when they become design manifestos. The agent needs stack facts, component boundaries, and validation commands.

# AGENTS.md

## Project facts
This is a Next.js marketing and docs site. App routes live in app/.
Shared UI primitives live in components/ui/. Content lives in content/.

## Commands
- Install: pnpm install
- Dev server: pnpm dev
- Build: pnpm build
- Lint: pnpm lint
- Typecheck: pnpm typecheck

## UI rules
- Use components/ui primitives before adding new visual primitives.
- Keep cards to repeated content items, modals, or tool panels. Do not wrap
  entire page sections in cards.
- Do not introduce a new color scale without updating tailwind.config.ts.
- Images used above the fold must have explicit width/height or aspect-ratio.

## Content rules
- Blog slugs come from content/blog filenames.
- Each new post needs a title, description, canonical URL, and OG image entry.
- Do not edit generated .next/ or out/ output by hand.

Why it works: the rules are concrete enough to prevent common agent mistakes. The agent knows where content lives, what commands are real, and what design system to reuse. The "cards" rule is opinionated, but it is falsifiable. A reviewer can point at a page section wrapped in a card and say the rule was violated.

The content section is the highest leverage part. Agents often add a markdown post and forget sitemap, metadata, or OG images. A good AGENTS.md names the coupled files so the change lands complete.

Example three: Rust and Cargo backend

Rust repos need a different AGENTS.md. The agent needs crate boundaries, migration policy, and test expectations.

# AGENTS.md

## Project facts
This is a Rust backend workspace. Crates live under crates/.
Database migrations live in migrations/. The public HTTP API lives in
crates/api/.

## Commands
- Format: cargo fmt --all
- Lint: cargo clippy --workspace --all-targets -- -D warnings
- Test touched crate: cargo test -p <crate>
- Test workspace: cargo test --workspace

## Workspace rules
- Do not add new workspace dependencies without checking workspace Cargo.toml.
- Keep crate boundaries explicit. Shared code belongs in crates/core only when
  it has at least two consumers.
- Do not use wildcard imports outside tests.
- New public errors must implement thiserror::Error and include a stable code.

## Database rules
- Migrations must be forward-only in production.
- Every migration needs a comment explaining the rollout assumption.
- Schema changes require an integration test or a documented reason in the PR.

Why it works: Rust agents often overgeneralize. They add shared utilities too early, hide errors in strings, or run only a local unit test. This file makes the pressure points explicit. It also avoids teaching Rust itself. AGENTS.md is not where you explain ownership or lifetimes. It is where you explain this repo's choices.

The "shared code" rule is especially useful. Agents love extracting helpers. The rule sets a bar: at least two consumers. That prevents abstraction churn.

Example four: Python project using uv

Python projects often fail through environment ambiguity. The agent sees requirements.txt, pyproject.toml, maybe a poetry.lock, maybe a uv.lock, then guesses. AGENTS.md should remove the guess.

# AGENTS.md

## Project facts
This is a Python 3.12 service. Dependency and environment management use uv.
Application code lives in src/service/. Tests live in tests/.

## Commands
- Install: uv sync
- Run service: uv run python -m service
- Unit tests: uv run pytest tests/unit
- Full tests: uv run pytest
- Lint and format: uv run ruff check . && uv run ruff format --check .
- Typecheck: uv run pyright

## Python rules
- Do not use pip, poetry, or conda commands in this repo.
- Do not edit uv.lock by hand. Run uv lock when dependency metadata changes.
- Public functions require type annotations.
- New external HTTP calls must set an explicit timeout.
- Do not catch Exception unless the handler re-raises or logs enough context.

## Configuration
- Environment variables are documented in docs/configuration.md.
- Never print secret values. Refer to secrets by environment variable name only.

Why it works: it eliminates the package-manager branch. "Use uv" is not enough; the file shows the exact commands. The error-handling and timeout rules are concrete. The secret rule is operational and reviewable.

The important part is that uv.lock is not treated as a normal text file. Agents are comfortable editing anything they can open. AGENTS.md should say which files are tool-owned.

Example five: monorepo with apps and packages

Monorepos are where AGENTS.md earns its keep. The root file should be a map, not a dumping ground.

# AGENTS.md

## Repository map
This is a TypeScript monorepo.
- apps/web: customer-facing Next.js app
- apps/admin: internal admin app
- packages/ui: shared UI primitives
- packages/api-client: generated API client
- packages/config: shared lint, TypeScript, and test config

## Root commands
- Install: pnpm install
- Build all: pnpm build
- Lint all: pnpm lint
- Test all: pnpm test
- Build one package: pnpm --filter <name> build

## Cross-package rules
- Do not import from one app into another app.
- Shared UI belongs in packages/ui only after two apps use it.
- packages/api-client is generated. Update the OpenAPI schema and regenerate.
- Changes to packages/config require running lint and typecheck in both apps.

## Local overrides
Subdirectories may contain their own AGENTS.md for narrower rules.
The closer file wins when it conflicts with this root file.

Why it works: it uses AGENTS.md as an index. It does not try to explain every app. It gives enough structure for the agent to navigate and enough boundaries to avoid cross-app coupling.

The local override note is essential. Codex discovers instruction files through scope. A root AGENTS.md should tell the agent that narrower files may exist and should be treated as authoritative for their subtree.

Example six: docs-heavy open-source library

Libraries need strong documentation rules because the code is not the whole product.

# AGENTS.md

## Project facts
This is an open-source TypeScript library. Source lives in src/.
Examples live in examples/. Public docs live in docs/.

## Commands
- Install: npm ci
- Build: npm run build
- Test: npm test
- Docs check: npm run docs:check

## Public API rules
- Do not change exported names without updating docs/api.md and CHANGELOG.md.
- Every new option needs one docs example and one test.
- Deprecated APIs must keep working until the next major version.
- Examples must use public imports only. Do not import from src/internal.

## Release notes
- User-visible fixes need a CHANGELOG.md entry.
- Internal refactors do not need a changelog entry unless behavior changes.

Why it works: it treats docs and examples as part of the contract. Agents often update the implementation and miss the public surface. This file makes the surface visible.

The "examples must use public imports" rule is small but valuable. It catches a common shortcut: importing internals because it is easier in the example. That breaks the teaching value of the docs.

Example seven: minimal repo that still works

Not every AGENTS.md needs to be long. A small CLI can have a small file.

# AGENTS.md

## Project
Small Go CLI for validating config files.

## Commands
- Format: gofmt -w .
- Test: go test ./...
- Build: go build ./cmd/configlint

## Rules
- Keep the CLI dependency-free unless a dependency removes substantial code.
- Error messages must name the file path and config key when available.
- Golden test files live in testdata/. Update them only with intentional output changes.

Why it works: no padding. No "best practices." No generic Go tutorial. It names the two things that matter for this project: dependency discipline and useful errors.

What the examples have in common

The common pattern is not a template. It is density. Good AGENTS.md files say fewer things, but the things they say are enforceable. They list real commands. They name generated files. They define ownership boundaries. They link to deeper docs instead of copying them. They tell the agent what not to do, not just what the project is.

If your AGENTS.md cannot be tested by running commands, checking paths, or reviewing a diff against a concrete rule, it is probably too vague. AgentLint catches that kind of weakness: stale commands, stale paths, contradictions, vague guidance, and missing enforcement around the instruction file your agents rely on.