Tools

AGENTS.md Best Practices: Insights from Top GitHub Repositories

Back to Tutorials

What AGENTS.md Does

AGENTS.md is a repository-local instruction file for AI coding agents. It gives an agent durable context about a codebase before the agent starts inspecting files, editing code, running tests, or preparing a change.

The format is deliberately simple: Markdown stored in the repository. It is not an execution engine, policy enforcement system, or universal configuration standard with one governing parser. Its usefulness depends on whether the coding agent supports the file, how that agent discovers instructions, and whether the instructions are accurate and scoped to the work.

A good file answers questions that an experienced maintainer would otherwise have to explain repeatedly:

  • What is this repository and how is it organized?
  • Which commands should be used to build, lint, type-check, and test it?
  • Which tests are relevant to a particular area?
  • Which directories or files are generated, sensitive, vendor-owned, or off-limits?
  • What local naming, formatting, architectural, or review conventions matter?
  • What should the agent do when a rule conflicts with the requested change?

The strongest evidence in the supplied research comes from GitHub's analysis of more than 2,500 repositories. It identifies recurring practical patterns: commands appear early, concrete code examples are more effective than abstract prose, stack details matter, and explicit boundaries are valuable. Additional repository examples show teams using root and package-level files, generated command sections, strict naming rules, and behavioral constraints.

That makes AGENTS.md best understood as a context and workflow layer for coding agents. It reduces repeated orientation work, but it does not replace tests, branch protection, code review, secret scanning, or CI permissions.

What Top Repositories Put Inside

1. Repository Layout and Architecture

The most useful files establish a compact mental model of the repository. An agent needs to know where production code, tests, documentation, generated files, examples, scripts, and configuration live.

A useful structure might look like this:

## Repository layout

- `src/`: application code
- `tests/`: integration and end-to-end tests
- `docs/`: user and developer documentation
- `scripts/`: maintenance and development utilities
- `generated/`: generated output; do not edit by hand
- `packages/api/`: API package with its own local instructions

This is more actionable than saying that the repository contains “the usual source and test directories.” Agents can navigate explicit paths immediately and can distinguish editable source from generated output.

For monorepos, a root file should explain the shared conventions and point agents toward package-specific instructions. A package-level AGENTS.md can then describe the local build command, test runner, ownership boundary, or framework conventions for that subtree.

The practical principle is progressive disclosure: keep global rules at the root and move detailed, local rules closer to the files they govern. A root document that contains every package's implementation detail becomes difficult to maintain and increases the chance that an agent applies a rule in the wrong place.

2. Commands Early in the File

The GitHub research specifically recommends putting executable commands in an early section. This is one of the highest-value improvements because agents frequently need to choose a first verification command before they understand the entire project.

Include complete commands with relevant flags and paths:

## Essential commands

- Install dependencies: `<repository-approved install command>`
- Run the full test suite: `<repository-approved test command>`
- Run tests for the API package: `<repository-approved package test command>`
- Run linting: `<repository-approved lint command>`
- Run the production build: `<repository-approved build command>`

The placeholders above are intentional. The correct command depends on the repository's package manager, language, test runner, working directory, environment variables, and service dependencies. An AGENTS.md file should contain commands verified by maintainers, not commands inferred from a framework name.

Flags and paths matter. “Run pytest” may be insufficient if tests require a virtual environment, a particular working directory, a marker, a service container, or a package-specific path. Likewise, “run the build” does not tell an agent whether the repository uses a workspace command, a task runner, or a generated build step.

Commands should also state prerequisites and known limitations. If a test requires a local database, emulator, container runtime, credentials, or network access, document that beside the command. Otherwise an agent may waste time repeating a command that cannot succeed in its current environment.

3. Testing Guidance

Testing sections are common because they turn a vague request to “verify the change” into a concrete workflow. Strong guidance distinguishes fast checks from expensive checks and maps code areas to relevant tests.

For example:

## Testing

- For changes under `packages/api/`, run the API unit tests first.
- For changes to shared types, run the type-check and affected package tests.
- For documentation-only changes, run the documentation linter.
- Run the full suite before claiming the change is complete.
- Report skipped, failed, interrupted, or timed-out tests accurately.

The final rule is especially important. An agent should never describe a timed-out or interrupted test as passing. Test status is part of the result, not merely a detail in the transcript.

Avoid requiring every small edit to trigger the slowest possible workflow. A practical file can describe a sequence: run a focused test while iterating, then run the broader suite when the change stabilizes. This reduces wasted execution while preserving a clear release check.

Testing instructions should also explain when tests must be added or updated. “Add regression coverage for behavior changes” is more useful when paired with the location and style of existing tests. A short example of an expected test shape can communicate local conventions better than a long paragraph.

4. Build and Development Commands

Build instructions should tell an agent how to produce the relevant artifact and how to start a development environment. These are separate operations and should not be conflated.

Document details such as:

  • The supported package manager or build tool.
  • The working directory for each command.
  • Whether generated code must be refreshed.
  • Whether environment variables are required.
  • Whether a command starts a long-running process.
  • Which command is appropriate for a package versus the whole repository.

A repository can also identify commands that agents must not run directly. The supplied examples include Apache Airflow rules that forbid running pytest directly on the host, implying that the project expects a controlled environment. That kind of rule is more useful when it says what to use instead and why.

5. Explicit Boundaries and Negative Rules

The most important guardrails are often negative rules. Agents can make destructive or noisy changes while trying to be helpful, so maintainers should identify protected areas explicitly.

Common examples include:

  • Never commit secrets or credentials.
  • Do not edit generated files by hand.
  • Do not modify vendor directories.
  • Do not change production configuration without explicit approval.
  • Do not alter database schemas as part of an unrelated API change.
  • Do not place temporary scripts in the repository root.
  • Do not change lockfiles unless dependency changes require it.

A boundary should be specific enough to guide an action. “Be careful with production” is weak. “Do not modify config/production/ unless the task explicitly requests it; ask before proceeding” is operational.

The supplied GitHub research reports that “never commit secrets” was the most common helpful constraint. That is sensible, but it should not be treated as a security control by itself. An instruction file can influence an agent's behavior; it cannot guarantee that a secret will not be exposed in a patch, terminal output, generated artifact, or commit. Repository permissions and automated scanning remain necessary.

6. Concrete Examples and Local Style

The GitHub findings favor code examples over explanations. A small example can show import ordering, naming, error handling, test structure, or API shape with less ambiguity than several paragraphs of prose.

If the repository has a naming convention that agents are unlikely to infer, state it plainly. Apache Airflow is cited as using a specific prose convention for “Dag,” demonstrating that even terminology can deserve an explicit rule. Style constraints should be concrete and limited to conventions that materially affect consistency or correctness.

Avoid turning the file into a general programming textbook. The agent can inspect existing code for ordinary patterns. Reserve instructions for decisions that are easy to miss, costly to repair, or not reliably inferable from nearby files.

Setup Experience

Creating the first file is easy. The difficult part is discovering accurate instructions and keeping them current.

Start with a short root file containing the repository purpose, layout, essential commands, testing workflow, and hard boundaries. Validate every command in a clean or documented development environment. Then ask a maintainer who did not author the file to use it for a small change and record where the instructions were ambiguous.

For larger repositories, add scoped files only when a subtree has genuinely different behavior. The file hierarchy should follow ownership and code boundaries, not an attempt to describe every conceivable task.

Some repositories use generated command blocks. The supplied examples identify coder/coder as marking an auto-generated commands section with START generated-commands, helping keep documented commands aligned with tooling. This is useful when commands change frequently, but it introduces maintenance complexity: the generation process itself must be understandable, reviewable, and available to contributors.

Treat AGENTS.md as source code. Review changes, test commands, remove obsolete rules, and avoid instructions that only one agent understands. Sentry's example is notable for declaring AGENTS.md the source of truth instead of spreading conflicting guidance across multiple agent-specific files. Centralization reduces drift, although compatibility with the tools used by your team still needs to be checked.

Pros and Cons

Pros

  • Faster orientation: Agents receive repository-specific context before making changes.
  • More reliable commands: Exact test, lint, and build commands reduce guesswork.
  • Clearer safety boundaries: Protected directories and approval requirements are visible at the point of work.
  • Scalable monorepo guidance: Root and package-level files support local rules without bloating one document.
  • Tool portability: Markdown is easier to inspect and version than instructions hidden in one developer's environment.
  • Better human onboarding: The same commands and layout notes help new contributors understand the repository.

Cons

  • No universal enforcement: An instruction file cannot replace CI, permissions, or review controls.
  • Tool support varies: Different coding agents may discover, merge, or prioritize instruction files differently.
  • Staleness is dangerous: Incorrect commands can waste time or cause agents to verify the wrong thing.
  • Context overload: A huge file can bury the commands and rules agents need most.
  • Conflicting scope: Root and nested instructions can become confusing if ownership and precedence are not clear.
  • Security overconfidence: “Never commit secrets” is useful guidance, not a complete data-loss prevention mechanism.

The practical trade-off is maintenance. A 40-to-80-line file is often easier to keep accurate than a 300-line manual, while unusually complex repositories may justify more detail through linked, scoped documents.

Alternatives and Complementary Tools

AGENTS.md is not the only place teams can put coding-agent guidance. Some tools have their own project instruction files or rule systems, and repositories may also contain contributor documentation, editor configuration, task-runner metadata, and CI definitions.

The right choice depends on the audience and the contract you need:

  • Use AGENTS.md for repository-level guidance intended to be discoverable by compatible coding agents and readable by humans.
  • Use README or contributor documentation for onboarding that applies to all developers, regardless of agent.
  • Use CI configuration for enforceable build, test, security, and policy gates.
  • Use formatter, linter, type-checker, and compiler configuration for machine-enforced code rules.
  • Use package-level instruction files when a subtree has distinct commands or conventions.
  • Use tool-specific rule files only when the team accepts the resulting vendor coupling or the tool requires them.

These are complements rather than substitutes. A linter can enforce formatting but cannot explain the architecture. A CI pipeline can reject a secret or failed test but cannot tell an agent which focused test to run first. A README can document setup but may not be discovered at the right moment by an agent.

Avoid duplicating the same rule in several locations unless one is the enforceable source and the other is a concise pointer. Duplicated instructions drift, and contradictory guidance is worse than missing guidance.

Practical Verdict

AGENTS.md is worth adopting for repositories where coding agents perform recurring maintenance, feature work, refactoring, or test-driven changes. Its strongest value is not clever prompting. It is operational precision: telling an agent where things are, what commands are trusted, what must be verified, and which areas require permission.

A high-quality file should be short enough to scan and specific enough to change behavior. Put commands near the top. Describe the stack and versions when they affect decisions. Show representative code or test examples. State boundaries as explicit actions. Use nested files for package-specific rules. Link to deeper documents instead of moving every detail into the root file.

Do not measure success by file length or by how authoritative the prose sounds. Measure it by outcomes: fewer wrong commands, fewer edits to generated or protected files, faster test selection, and more accurate reports of what was actually verified.

The empirical patterns from the supplied repository analysis are convincing as design guidance, but they are not a universal benchmark. Repository populations, agent behavior, support for nested files, and instruction precedence can change. Teams should inspect the behavior of the coding agents they actually use and keep CI as the final authority.

A sensible first version can be created in one review cycle. Start with the five facts agents repeatedly get wrong, verify the commands, and revise the document when a real agent failure exposes a missing rule. That feedback loop is more valuable than trying to predict every future task.

FAQ

Is AGENTS.md an official GitHub standard?

The supplied material presents AGENTS.md as a simple, open format used across repositories and coding-agent ecosystems. It should not be treated as a universal enforcement standard. Support and instruction-precedence behavior depend on the coding agent and its integration.

How long should an AGENTS.md file be?

There is no required length. The supplied repository examples suggest that many projects are better served by a focused file of roughly 40 to 80 lines, with larger repositories using scoped files and linked documentation. Complexity should determine length, not a target word count.

Should commands appear at the beginning?

Yes. Put the most frequently used executable commands in an early section, including flags, paths, prerequisites, and package scope. This gives an agent actionable information before it spends time exploring the repository.

Can AGENTS.md prevent an agent from changing dangerous files?

It can clearly instruct the agent not to touch protected files and to ask for approval, but it cannot guarantee compliance. Use repository permissions, CI checks, secret scanning, code review, and protected branches for enforcement.

Should every package have its own AGENTS.md?

No. Add a package-level file when that package has distinct commands, architecture, ownership, or constraints. Otherwise, a root file with a clear layout is simpler and less likely to create conflicting guidance.

Should AGENTS.md duplicate the README?

Only where duplication provides immediate agent value. Keep general onboarding in the README and put agent-relevant navigation, commands, testing sequences, and boundaries in AGENTS.md. Link between them when useful, and avoid maintaining contradictory copies of the same rule.

What is the first rule to add?

Start with the commands that a contributor must run to test and build the repository, then add the protected paths and the most common failure modes. Those details usually provide more value than a long project history or a generic persona for the agent.