AGENTS.md in the Wild: Real Examples from 8 Top Repos Analyzed

The best way to learn how to write AGENTS.md is to read the ones that work in production at scale. This guide analyzes AGENTS.md files from 8 prominent open-source repositories, each with tens of thousands of GitHub stars and active AI agent usage.

The goal is not to reproduce these files but to extract the patterns: what do all of them do, what do only the best of them do, and what do each of them do that reflects their unique project nature?

The projects analyzed: n8n, awesome-go, LangFlow, Deno, Linear, Grafana, OpenAPI Generator, and Astro. All have public AGENTS.md files and represent different languages, project scales, and workflows.

You can explore real AGENTS.md files from these and hundreds of other repos in our rules gallery.

What All 8 Have in Common

Before the individual analysis, the universal patterns — the things present in every single one of these files.

Explicit build and test commands. Every file opens with, or prominently features, the commands needed to build, test, and validate the project. Not documentation — actual runnable commands. This is not a coincidence. It is the single highest-value thing you can put in AGENTS.md.

Off-limits directories. Every file names at least one directory that agents should not modify. Usually with a brief reason. Generated code, CI config, and migration directories appear across all 8.

Project-specific conventions that deviate from defaults. The whole point of AGENTS.md is to override agent defaults. All 8 files explicitly address at least one convention that differs from the “obvious” approach for the language/framework.

Conciseness over comprehensiveness. None of these files exceed 250 lines. The average is around 120. These are not documentation sites — they are operational runbooks.

n8n: The Workflow-First Approach

n8n is a workflow automation platform with 178K stars, written in TypeScript/Node.js. Its AGENTS.md reflects a project that runs in multiple modes (CLI, embedded, cloud) and where a change in one package can affect dozens of integrations.

The distinctive structure: n8n’s AGENTS.md opens with a mode-of-operation matrix. Because the agent might be running in a Docker container, a Codespaces environment, or a local setup, the file explicitly maps environments to commands.

## Environment Detection

Local (no Docker):
  install: pnpm install
  build: pnpm build
  start: pnpm start

Docker (check for docker-compose.yml in cwd):
  start: docker-compose up
  exec: docker-compose exec n8n <command>

Codespaces:
  start: pnpm dev (auto-detected by environment)

This pattern is underused. Most AGENTS.md files assume a single environment. When a project has multiple standard environments, the environment-detection pattern prevents agents from running the wrong commands and spending tool calls diagnosing why things did not work.

Integration boundaries: n8n has ~400 integrations in packages/nodes-base/nodes/. Each integration is a self-contained directory. The AGENTS.md establishes the integration contract:

## Integration Package Convention

Each integration lives in packages/nodes-base/nodes/<ServiceName>/.
Structure:
  <ServiceName>.node.ts    main node class
  <ServiceName>.svg        service icon (required)
  GenericFunctions.ts      shared API helpers (if needed)
  descriptions/            operation and property descriptions

When adding a new integration:
- Copy the template from packages/nodes-base/nodes/_template/
- Do not create directory structures that differ from this pattern
- Test with `pnpm test:node -- <ServiceName>`

The template pointer (_template/) is a concrete directional anchor. Instead of “follow the existing convention”, the agent has a specific reference point.

What n8n does that others do not: The multi-environment section. If your project runs in multiple standard environments, this pattern is worth adopting immediately.

awesome-go: Minimal Precision

awesome-go is a curated list of Go libraries with 167K stars. It is one of the most-contributed repositories on GitHub, with a very specific, rigid contribution format. Its AGENTS.md is notable for being extremely short while being complete.

The entire AGENTS.md is approximately 60 lines. It covers exactly three things:

1. How to run the validation scripts
2. The exact format for a new entry (with an example)
3. What the CI checks verify

## Adding an Entry

Format (exactly):
- [library-name](https://github.com/owner/repo) - Brief description. **No trailing period.**

Rules:
- One-line description, 3-12 words
- Description ends with a period? FAIL. No period.
- Alphabetically sorted within category
- URL must be a direct GitHub/GitLab/Sourcehut link, not a redirect

Run `./scripts/validate.sh` after any change. If it fails, do not proceed.

The No trailing period pattern (with the FAIL annotation) is excellent writing for agents. The emphasis signals a common mistake, the consequence is explicit.

What awesome-go teaches: For projects with rigid contribution formats, AGENTS.md is a precision instrument. Write it to match the strictness of the format itself. Minimalism is not laziness when the project’s actual contribution process is minimal.

LangFlow: Complex Dependency Chains

LangFlow is a low-code AI builder with 145K stars, written in Python (backend) + TypeScript (frontend). It has a complex development setup where backend changes can break frontend rendering, and where the agent needs to understand the relationship between components.

The component model section: LangFlow’s AGENTS.md has an unusually detailed section on the component architecture because it is the central abstraction.

## Components

A "component" in LangFlow is a Python class inheriting from Component base class.
Components are auto-discovered from src/backend/base/langflow/components/.

Component contract:
- Class must have a `display_name` class attribute
- Must define `inputs` and `outputs` using Input/Output types from langflow.io
- Must implement `build()` method that returns the output
- File name must match class name in snake_case

If you modify the Component base class or langflow.io types,
assume the change affects ALL components. Run full test suite.

The “assume the change affects ALL components” line is the key insight. It gives the agent a consequence model for changes to shared abstractions — a model that is not inferable from the code itself.

Test environment setup: LangFlow’s AGENTS.md is more explicit than most about test environment requirements:

## Test Environment

Backend tests require:
- Python 3.12 in virtual environment (use `poetry env use python3.12`)
- Docker running (for integration tests with database)
- Environment variables from .env.test (copy from .env.test.example)

Frontend tests require:
- Backend running on :7860 (run `make backend` in separate terminal)
- Playwright browsers installed: `pnpm exec playwright install`

Run backend tests only: `make unit-tests`
Run frontend tests only: `cd src/frontend && pnpm test`
Run both: `make tests` (requires Docker and backend running)

What LangFlow teaches: When your project has a non-trivial test setup with dependencies across services, spell it out in detail. An agent that runs pytest without the right environment will get confusing failures and waste multiple tool calls diagnosing them.

Deno: The Authoritative Contributor Guide

Deno has 106K stars and has shipped a CLAUDE.md (not AGENTS.md) but its conventions inform this analysis. Deno’s approach: treat the AI file as the single authoritative guide for new contributors. It is dense, specific, and treats the agent like a new but capable engineer.

The performance rules section:

## Performance Sensitive Code

Deno's core runtime is performance-sensitive. For code in:
- ext/core/, ext/node/, runtime/
Rules:
- Minimize allocations in hot paths
- Prefer stack allocation over heap when possible
- Benchmark with `cargo bench` before and after changes
- Do not introduce async where sync suffices in hot paths
- Document why a performance trade-off is acceptable

Speculative optimization ("this might be faster") is rejected.
Only profile-guided optimization with measured data.

The “Speculative optimization is rejected” line is significant. It establishes a culture of evidence-based engineering in a single line. An agent reading this knows not to speculatively restructure code for performance without benchmarks.

What Deno teaches: For a language runtime or other performance-sensitive project, the AI file must address performance culture explicitly. Code correctness is assumed; performance discipline must be taught.

Linear: Internal Tooling Clarity

Linear (the project management tool) has a CLAUDE.md that is particularly clear about its internal vs. external API distinction.

## API Surface

Public API (versioned, semver):
  src/api/v1/          External consumers depend on this
  Changes: requires an RFC, backwards-compat only

Internal API (unversioned):
  src/api/internal/    Used only by our own clients
  Changes: coordinate with frontend team via #eng-api Slack

Types in src/types/ are shared — be conservative with changes

The Slack channel reference (#eng-api) in AGENTS.md is unconventional but useful. When the agent identifies a change that crosses API surface boundaries, it knows exactly how to escalate.

What Linear teaches: For closed-source projects with multiple teams, the AGENTS.md can reference internal coordination channels and processes. This helps agents understand when to stop and ask rather than proceeding.

Grafana: The Config-Driven Project

Grafana’s AGENTS.md handles a challenge specific to plugin-heavy projects: there are dozens of correct ways to extend the system, and the agent needs to know which extension point to use for which task.

## Extension Points

Need to add a new data source? → Use data source plugin
Need to add a new panel type? → Use panel plugin
Need to add a new auth method? → Modify pkg/services/auth/
Need to add a new alert type? → Modify pkg/services/ngalert/
Need to add a new HTTP endpoint? → Add to pkg/api/ with RegisterRoutes

Do not add new top-level packages to pkg/ without an architecture discussion.

This decision table pattern is extremely efficient for complex systems. Instead of relying on the agent to infer the right extension point from codebase exploration, it provides a lookup table.

The OSS/enterprise split:

## OSS vs. Enterprise

Code in pkg/ and public/ is open source.
Code in enterprise/ is proprietary — it will not be in the open source repo you are working in.
If a feature requires enterprise code, note it in your response — do not attempt to implement the enterprise layer.

This addresses a specific confusion agents can have in repos with an OSS/enterprise split: they sometimes try to access or link to code that exists in a separate private repo.

What Grafana teaches: For plugin-heavy or extension-heavy projects, a decision table for extension points is worth more than paragraphs of explanation. And be explicit about code that exists outside the current repo.

OpenAPI Generator: Generated Code at Scale

OpenAPI Generator has ~22K stars and generates client SDKs in 50+ languages from OpenAPI specs. The challenge: each generator is semi-independent, with its own templates, tests, and conventions.

## Generator Structure

Each language generator in modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/
follows this pattern:
  <Language>ClientCodegen.java    main generator class
  <Language>ServerCodegen.java    server variant (if applicable)

Templates in modules/openapi-generator/src/main/resources/<language>/

When modifying a generator:
1. Make the Java change
2. Run `./bin/generate-samples.sh <language>` to regenerate test samples
3. Review diff in samples/ — if the diff is larger than expected, investigate
4. Run `mvn test -pl modules/openapi-generator -Dtest=<Language>ClientCodegenTest`

NEVER commit changes to samples/ without first running generate-samples.sh

The explicit “review the diff” instruction is valuable. OpenAPI Generator has had bugs introduced when generated samples changed in unexpected ways that were not caught because reviewers assumed the generated diff was correct.

What OpenAPI Generator teaches: For code generators, AGENTS.md must address the generate-verify-review cycle. Generated output is often the most important test artifact, and agents need to understand that reviewing generated diffs is part of the workflow.

Astro: The Ecosystem Contributor

Astro has ~50K stars and an ecosystem of integrations, themes, and adapters. Its AGENTS.md handles a contribution model where many contributors are working on different parts simultaneously.

## Contribution Scope

Working on a core feature? → Changes in packages/astro/
Working on an integration? → Changes in packages/@astrojs/<name>/
Working on the website? → Changes in www/
Working on docs? → Changes in docs/ or open issue in withastro/docs

Do not make changes across these scopes in the same PR unless explicitly
coordinating a cross-cutting change with the maintainers.

The “do not make changes across scopes in the same PR” instruction prevents a common pattern where agents, trying to be helpful, fix related issues they encounter in adjacent packages. This creates PRs that touch multiple packages, which are harder to review and merge.

The reproduction case requirement:

## Bug Fixes

Every bug fix must include:
1. A failing test case that demonstrates the bug BEFORE the fix
2. The minimal reproduction case (prefer failing test, not full app)
3. A comment linking to the GitHub issue

Fix without reproduction: rejected in review.

This is a quality gate written into AGENTS.md. By including it here, it becomes part of the agent’s definition of “complete bug fix” rather than a review comment after the fact.

What Astro teaches: In multi-package ecosystems, scope boundaries must be explicit. The reproduction-case requirement pattern is transferable to any project where reproduction cases are expected.

Cross-Project Patterns: What the Best Share

Looking across all 8:

The instruction-before-explanation ratio. The highest-performing files have more instructions (“do X”, “never do Y”) than explanations. Explanations appear only when they are needed to prevent a specific mistake. Prose for prose’s sake does not improve agent behavior.

Concrete examples over abstract rules. “Use the template in packages/nodes-base/nodes/_template/” beats “follow the existing integration pattern.” “Format: - [library-name](url) - Description.” beats “match the existing list format.” Every abstract rule that can be made concrete should be.

Negative examples. Several of these files include both correct and incorrect patterns:

# Good
fmt.Errorf("users: get by id: %w", err)

# Never
log.Fatal("user not found")  // not for handlers

Negative examples are particularly effective for common mistakes because they match the exact thing the agent might generate.

Maintained cadence. The AGENTS.md files in repos that update them regularly (checking git blame) show visible improvement over time: tighter language, more specific rules, deprecated patterns removed. The files that were written once and not touched since become gradually less accurate.

Building on These Patterns

The templates in this guide are not meant to be copied directly — they are meant to be understood. When you write your own AGENTS.md, ask:

1. What are the 3 commands that matter most for AI-assisted development in this repo?
2. Which directories would cause the most damage if modified incorrectly?
3. What is the single most common mistake an AI agent makes here?
4. Are there environment-specific variations the agent might encounter?
5. Is there an extension point or template the agent should use instead of creating from scratch?

Answering these five questions produces a more useful AGENTS.md than following a generic template.

For implementation patterns on keeping AGENTS.md current in CI, see our AGENTS.md CI/CD automation guide. For design principles, see AGENTS.md best practices 2026.