What the 100 Biggest GitHub Repositories Put in AGENTS.md Files

Why AGENTS.md Exists

A coding agent can read source files, run commands, and edit a repository, but source code alone does not explain how the repository is meant to be changed. It may not know which package owns a feature, which test command is authoritative, whether generated files should be edited, or what maintainers expect in a pull request.

AGENTS.md is a repository-level operating manual for that missing context. It gives an agent the local rules needed to make a change that fits the project instead of merely compiling in isolation.

The useful distinction is between a rulebook and an operating manual. A rulebook says “always do X.” An operating manual explains how this repository is organized, what a normal change looks like, how to verify it, and where the dangerous edges are.

That distinction matters because an instruction file can fail in two opposite ways:

It can be too vague: “follow best practices and run tests.”
It can be too exhaustive: hundreds of lines of general software advice that hide the commands and constraints an agent actually needs.

A recent field study examined the AGENTS.md files of the 100 most-starred repositories that had one. Those repositories represented 11.4 million combined stars. In the broader set of the 1,000 most-starred public repositories, 273 had a root AGENTS.md, or 27%. The sample included projects such as vscode, ollama, n8n, pytorch, bun, zed, AutoGPT, and webpack.

The strongest consensus was practical rather than philosophical. In approximate order of how much the files discuss each area, they cover:

Architecture and repository layout
How to test
Build and development commands
Dos and don'ts
Pull request etiquette
Code style

The lesson is straightforward: write down the information that prevents an agent from making an expensive wrong turn.

What to Put in the File

1. Explain the architecture and layout

Start with a map. An agent needs to know where the public interface, implementation, tests, documentation, examples, generated artifacts, and build configuration live.

Do not describe every directory. Describe the boundaries that influence implementation decisions. For example, explain that a package is a public API, that a directory contains generated code, or that a particular service is the owner of a workflow.

Useful details include:

The repository's major packages or applications
The entry point for the main product or command-line tool
Where unit, integration, end-to-end, and fixture data live
Which directories are generated or vendored
Which packages may depend on one another
Where shared utilities belong
Which files define public configuration or API contracts

A short architectural map is more useful than a directory listing copied from a file browser. The agent can inspect the tree itself; the file should explain what the tree means.

2. Make verification executable

“Run the tests” is not an instruction. Identify the commands and tell the agent which level of verification applies to which kind of change.

For example, distinguish between:

A fast unit-test command for a single package
A type-check or lint command
A build command for the affected application
An integration test that requires services or credentials
A full repository check that may be slow

Use placeholders when a command differs by environment rather than inventing a command that your repository does not support. Every command in AGENTS.md should be tested by a human maintainer or copied from the repository's existing scripts and documentation.

The file should also state what to do when a check cannot run. An agent should report that a database, emulator, secret, platform, or external service was unavailable rather than treating an unrun check as a passing check.

3. Document build and development workflows

Build instructions are different from test instructions. A test may execute source directly, while a production build may require code generation, bundling, migrations, or platform-specific tooling.

Record the normal local workflow:

Required runtime and package-manager versions
Dependency installation or bootstrap step
Environment variables that are safe to use locally
Commands for starting the development server or service
Build commands for affected packages
Code-generation steps
Whether a clean build is required after changing certain files

Do not put secrets in the file. Explain the name or purpose of a required variable and point to the repository's approved setup documentation or example environment file.

4. State the dangerous constraints

The “dos and don'ts” section should contain repository-specific hazards. Generic advice such as “write clean code” adds little value.

High-value constraints often look like these:

Do not edit generated files; change the source template and regenerate.
Do not change a public API without updating its compatibility tests or documentation.
Do not add a dependency when an existing internal utility provides the capability.
Do not modify lockfiles manually.
Do not change snapshots without understanding why the output changed.
Do not run destructive migration or cleanup commands against shared environments.
Do not broaden a refactor while fixing a focused bug.
Preserve platform-specific behavior when touching cross-platform code.

Each rule should answer “what breaks if this is ignored?” When the consequence is clear, the agent can apply the rule to situations that the author did not explicitly predict.

5. Set pull request expectations

Agents frequently produce technically valid patches that are difficult to review. Include the repository's expectations for the final change.

Useful guidance covers:

How to title or scope a pull request
Whether commits should be squashed or kept separate
What a description must include
Whether tests, benchmarks, screenshots, changelog entries, or migration notes are required
How to mark a breaking change
Whether generated output belongs in the pull request
Which maintainers or ownership files determine review responsibility

Avoid encoding a fictional process. If the project does not require a changelog entry, do not tell the agent to create one. The instruction file should reflect the actual review contract.

6. Clarify code style where tools do not

Formatters and linters should enforce mechanical style. AGENTS.md should cover the style decisions that tools cannot fully express.

Examples include:

Naming conventions for domain concepts
Preferred error-handling patterns
Whether a module should remain dependency-free
How public types are documented
When to use a shared abstraction versus a local helper
Whether tests should assert behavior or implementation details
How compatibility with older runtimes is maintained

Point to authoritative configuration where possible. A sentence such as “run the repository formatter and do not hand-format generated output” is more reliable than duplicating every formatting rule in prose.

A Practical Implementation Workflow

Step 1: Inventory the repository

Before writing instructions, inspect the actual repository. Start with the top-level tree and the files that define the development workflow.

Inspect first:
- top-level directories
- package manifests and lockfiles
- CI workflow definitions
- formatter, linter, and type-check configuration
- test configuration
- contributor documentation
- build scripts and task-runner configuration
- generated-code markers
- ownership or review configuration

Use the repository's existing documentation as evidence. If the README says one command is the supported workflow but CI runs another, resolve that discrepancy before documenting either one.

Step 2: Identify change boundaries

Choose three or four representative changes and trace them through the repository. For each one, answer:

Where does the feature enter the system?
Which package owns the behavior?
Where are its tests?
Does it require a generated artifact or schema update?
Which command verifies it?
Which maintainers normally review it?

This produces a useful architecture section from real workflows rather than guesses based on directory names.

Step 3: Extract authoritative commands

Find commands that already exist in package manifests, task files, CI configuration, and contributor documentation. Prefer those commands over newly invented wrappers.

Classify them by cost and scope:

Fast feedback:
- formatting check
- lint for the affected package
- focused unit tests

Broader verification:
- package build
- integration tests
- type checking across the workspace

Release-level verification:
- full test suite
- production build
- platform-specific checks

If the repository is a monorepo, document how to target one package and how to run the broader workspace check. An agent needs both paths: a fast loop during implementation and a credible final verification step.

Step 4: Write the smallest useful first version

A good starting file can follow this structure:

# AGENTS.md

## Repository Map
- `apps/`: deployable applications.
- `packages/`: reusable libraries.
- `tests/`: integration tests and fixtures.
- `docs/`: user and contributor documentation.
- `generated/`: generated output; do not edit directly.

## Architecture
- The request layer lives in `packages/api`.
- Business rules live in `packages/domain`.
- Application-specific wiring belongs under `apps/`.
- Keep domain packages independent of deployment code.

## Development
- Install dependencies using the repository's documented package-manager command.
- Use the local example environment file; never commit credentials.
- Run the documented development command for the application you are changing.

## Verification
- Run the formatter and lint check for changed packages.
- Run focused tests for the affected package.
- Run the workspace build when changing shared packages or public interfaces.
- Report checks that could not run and explain why.

## Constraints
- Do not edit generated files directly.
- Do not modify lockfiles by hand.
- Update tests and documentation when changing a public interface.
- Keep unrelated refactors out of focused bug fixes.

## Pull Requests
- Keep the change narrowly scoped.
- Include the verification commands and their results in the description.
- Add required migration, changelog, or compatibility notes for user-visible changes.

Replace every generic sentence with a repository-specific fact before committing this file. The template is a shape, not content to publish unchanged.

Step 5: Add scoped instructions when necessary

A large monorepo may need instructions that only apply to a subtree. Keep root-level guidance focused on rules that affect the whole repository, then place more specific guidance near the code it governs if the agent tooling you use supports hierarchical instruction files.

For example, frontend code may have different test and build commands from a data-processing package. A scoped file can explain those local commands without forcing every agent task to read an enormous root document.

Before relying on this pattern, verify how your selected coding agent discovers and combines root and nested AGENTS.md files. Support and precedence are tool-specific. Do not assume that every agent merges nested instructions in the same way.

Step 6: Validate the document itself

Treat AGENTS.md as operational documentation. Ask another engineer to follow it from a clean checkout, or use it during a small, low-risk change.

Check that:

Every command exists.
Paths are current.
The named package manager matches the lockfile and CI workflow.
Generated-file rules identify the real source of truth.
The test guidance distinguishes passed, failed, and unavailable checks.
The instructions do not contradict contributor documentation.
The file does not contain credentials or environment-specific secrets.
The document is short enough to remain readable during an agent session.

The field study reported a median file length of roughly 1,200 words and recommended keeping the file under two pages where possible. Length is not a quality metric, but this is a useful pressure against turning the file into a second handbook.

Common Errors

Writing generic engineering advice

“Use good naming,” “follow SOLID,” and “write tests” do not tell an agent how this repository works. Replace them with local decisions, paths, commands, and failure conditions.

Copying commands without running them

A stale command is worse than no command because it creates false confidence. Run each documented command, or clearly label it as environment-dependent and explain the prerequisite.

Listing the tree without explaining ownership

A directory listing tells an agent where files are. It does not tell the agent where a new change belongs. Explain package responsibility and dependency direction.

Treating generated files as ordinary source

This can create patches that disappear the next time generation runs. Identify generated paths, the source files that produce them, and the regeneration workflow.

Mixing policy with personal preference

An instruction such as “never use helper functions” is only useful if the project actually enforces it. Keep subjective preferences out unless maintainers consistently apply them during review.

Hiding verification gaps

Do not instruct an agent to claim that a test passed when it could not run. Document unavailable services, credentials, operating systems, and long-running checks as explicit limitations.

Making the root file enormous

An agent needs high-signal context near the beginning of its work. Move detailed API references, historical explanations, and broad contributor education into linked documentation. Keep AGENTS.md focused on decisions that affect edits.

Assuming all agents behave identically

AGENTS.md is a convention whose discovery, hierarchy, and precedence depend on the coding agent or integration consuming it. Verify the behavior of the tools used by your team, and avoid presenting tool-specific behavior as a universal GitHub guarantee.

A Maintenance Loop That Works

An instruction file decays when the repository changes but the document does not. Add AGENTS.md review to the same maintenance habits used for build scripts and contributor documentation.

Update it when:

A package moves or changes ownership.
The package manager, runtime, or build system changes.
CI commands are renamed.
Generated-code workflows change.
A recurring agent mistake appears in review.
A new public API or compatibility constraint is introduced.
Pull request requirements change.

A useful test is to record agent mistakes. If an agent repeatedly edits the wrong directory, skips a required generator, or runs an expensive full suite for a one-line package change, add the missing context to the relevant section. Do not add speculative rules for problems that have not occurred.

FAQ

Is `AGENTS.md` a GitHub-enforced standard?

Do not assume that GitHub itself enforces the file's instructions. Its usefulness depends on the coding agent or development integration that reads it. Confirm discovery and precedence behavior for the tools your team uses.

Should the file contain every coding standard?

No. Put repository-specific decisions, architecture, commands, constraints, and review expectations in the file. Keep mechanical style rules in formatter and linter configuration, and link to detailed documentation when necessary.

How long should an `AGENTS.md` file be?

Keep it as short as possible while answering the questions an agent must resolve before editing. The study found a median length of around 1,200 words and suggested staying under two pages where possible. A smaller file is appropriate when the repository genuinely needs less guidance.

Should I add one to a small repository?

Add one when there is meaningful context that is easy to miss: multiple packages, generated files, unusual test setup, deployment constraints, or strict review conventions. For a simple repository, a concise file with the correct commands may be enough.

Can I include secrets or private environment values?

No. Document variable names, setup steps, and approved local configuration sources, but never place credentials, tokens, or private values in AGENTS.md.

What is the first section I should write?

Write the repository map and verification commands first. An agent that knows where ownership lives and how to validate a change can usually make better progress while the remaining constraints are being documented.

How do I know whether the file is effective?

Compare the mistakes made before and after it is introduced. A useful file reduces wrong-directory edits, invalid commands, accidental generated-file changes, skipped tests, and review churn. Those operational outcomes matter more than how polished the prose looks.