Six prominent production repositories—including the code behind OpenAI Codex, Sentry, Apache Airflow, Temporal, Cloudflare’s Workers SDK, and Coder—have adopted AGENTS.md files, marking a decisive shift from experimental AI agent prompts to a formal, reviewable layer of repository policy. The move signals that the software industry is ready to treat instructions for AI coding assistants as first-class engineering artifacts, subject to version control, peer review, and continuous integration checks.

AGENTS.md, a plain-text file placed at the root of a repository, acts as a system prompt for tools like GitHub Copilot, Cursor, and other AI agents that read codebases. It tells the AI how to write code that matches the project’s conventions, which testing commands to run, how to handle error handling, and what security constraints apply. Unlike README.md, which is written for humans, or CONTRIBUTING.md, which provides general contributor guidance, AGENTS.md is crafted specifically for machine consumption—yet remains human-readable and editable.

The concept isn’t entirely new. For well over a year, developers have been using similar mechanisms: Cursor’s .cursorrules file and GitHub Copilot’s .github/copilot-instructions.md both allow tailoring AI behavior. What’s different now is the scale and the public nature of adoption. With six major codebases openly committing AGENTS.md files, the practice is evolving from an individual productivity hack into a shared, institutionalized standard that teams can depend on across multiple tools.

What Is AGENTS.md?

At its core, AGENTS.md is a set of written directives that govern how an AI coding assistant should interact with a particular codebase. A typical file might contain:

  • Code style preferences: Indentation rules, naming conventions, and linting commands (e.g., “always run black before suggesting Python changes”).
  • Testing requirements: Specifying that new functions must include pytest unit tests, and the command to run them.
  • Security boundaries: Refusing to suggest code that introduces specific vulnerable patterns, or requiring that any generated SQL uses parameterized queries.
  • Architecture rules: Ensuring that new files are added to the correct directory, or that certain design patterns are followed.
  • Pull request etiquette: Describing how commits should be structured and whether the AI should request reviews from specific code owners.

Because AGENTS.md lives inside the repo, it automatically travels with every fork and clone. When multiple developers on a team use different AI tools, each tool can read the same file and apply consistent rules—provided the tool supports the standard. This makes it a lightweight, vendor-neutral way to codify project policy for AI assistants.

The Six Repositories Leading the Charge

While many projects have been privately experimenting with AGENTS.md, the six named in the latest wave of adoption give a cross-section of the industry:

OpenAI Codex

The repository behind Codex, OpenAI’s legacy code-generation model, uses AGENTS.md to define how code patches should be structured and what programming principles to prioritize. Given that Codex was trained on vast amounts of public code, its own repo’s AGENTS.md serves as a dogfooding exercise: AI writing code for an AI company’s own tooling, governed by the same policy file it helps enforce for others.

Sentry

Sentry’s error-tracking platform is built primarily in Python and TypeScript. Its AGENTS.md reportedly enforces database migration safety checks, requiring any AI-suggested schema change to be accompanied by a rollback plan. It also mandates that all generated Python code passes strict mypy type-checking and automatically runs integration tests against a local development server.

Apache Airflow

As a workflow orchestration engine used across thousands of enterprises, Airflow’s AGENTS.md focuses heavily on production reliability. It instructs AI assistants to never propose changes that would break backward compatibility in DAG execution, to include documentation updates for any new operator, and to run the full test suite with breeze, Airflow’s CI tool.

Temporal

The Temporal workflow engine, written in Go, uses AGENTS.md to enforce its stringent code review norms. Any AI-generated PR must reference an issue, follow the conventional commit format, and include both unit and integration tests. Temporal’s maintainers have publicly stated that AGENTS.md has reduced the number of “obviously wrong” AI suggestions by catching misaligned code early.

Cloudflare Workers SDK

Cloudflare’s Workers SDK, a JavaScript/TypeScript toolkit for edge computing, employs AGENTS.md to keep AI assistants aligned with its aggressive release cadence and strict security posture. The file forbids the use of certain global APIs, requires all network calls to be wrapped in fetch with specific error handling, and instructs the AI to generate Wrangler configuration snippets only with explicit user permission.

Coder

Coder, an open-source developer environment platform, was one of the earliest adopters and made its AGENTS.md publicly visible as part of a pull request in mid-2025. The file is notably comprehensive, covering Go formatting, Terraform provider patterns, and even rules about how to name example workspace templates. Coder’s engineering team treats AGENTS.md with the same rigor as their CODEOWNERS file, requiring two senior engineers to sign off on any changes.

How AGENTS.md Works in Practice

When a developer starts an AI-assisted session in their editor, the tool reads the AGENTS.md and incorporates its directives into every prompt. This means the AI is continuously reminded of the project’s rules without the developer having to type them repeatedly. For instance, if AGENTS.md says “all SQL queries must use ORM models, never raw SQL,” the AI will avoid generating raw SQL even when it might seem like a shortcut.

Crucially, AGENTS.md also influences pull request reviews. When an AI-generated PR is submitted, human reviewers can check whether the changes adhere to the AGENTS.md instructions. If the AI ignored a rule—say, it added a feature without tests—the reviewer can simply point to the AGENTS.md violation and ask for a revision. This transforms AGENTS.md from a silent background prompt into a concrete, enforceable contract.

Integration with CI and Testing

The repositories adopting AGENTS.md aren’t just using it as a prompt—they’re wiring it into their continuous integration pipelines. A growing pattern is to include a linting step that validates AI-generated code against the AGENTS.md rules. For example, a CI job might scan the diff for forbidden patterns (e.g., commented-out print statements, which could indicate AI-generated debugging code) or verify that every new function has a corresponding test file.

Airflow’s CI, for instance, now includes a check that warns if a PR contains code that doesn’t conform to the AGENTS.md-mandated import ordering. Temporal’s CI blocks merges if the AI didn’t follow the commit message format. These automated checks reduce the burden on human reviewers and ensure that AGENTS.md compliance is objective and measurable.

Security and Compliance Benefits

One of the most compelling arguments for AGENTS.md is security. AI coding assistants, left to their own devices, can suggest vulnerable code paths: hardcoded secrets, SQL injection, cross-site scripting, or weak cryptography. AGENTS.md allows security teams to bake in rules that prevent these patterns before they reach a reviewer. The file becomes a living security policy that every AI tool respects.

Sentry’s use case highlights this: the AGENTS.md explicitly forbids AI from suggesting changes to authentication logic without flagging the PR for a security review. Cloudflare’s file blocks the use of eval and other dangerous functions. As supply-chain attacks become more sophisticated, having a central, reviewable security policy that applies to both human and AI contributors is a powerful defense.

The Windows Development Perspective

For Windows developers, the rise of AGENTS.md arrives at a pivotal moment. Microsoft’s ecosystem is deeply integrated with AI coding tools: Visual Studio Code and Visual Studio both offer first-class support for GitHub Copilot, and GitHub Copilot itself reads .github/copilot-instructions.md by default. But that file only applies to Copilot. AGENTS.md promises a cross-tool standard that could work with Copilot, Cursor, AWS CodeWhisperer, and others, all from a single file.

Windows-centric projects—from PowerShell modules to .NET MAUI apps to WinUI libraries—stand to benefit. Imagine a Windows Terminal contributor who uses Copilot while another uses Cursor. A single AGENTS.md in the repo could standardize both assistants to follow the same C++ formatting and testing rules. This reduces friction and ensures consistency across the contributor base.

Moreover, Windows development often involves .NET, Win32, or UWP-specific idioms that off-the-shelf AI models might misunderstand. AGENTS.md provides a place to encode those idioms: “Use P/Invoke only through the approved wrapper,” or “All WinForms controls must be initialized in the constructor.” These rules can dramatically improve the quality of AI-generated code for Windows projects.

Microsoft itself has not yet officially endorsed AGENTS.md, but the pattern aligns with existing practices. The .github directory already hosts COPILOT.md and copilot-instructions.md files in many of its repositories. It’s plausible that the company will converge on AGENTS.md as a vendor-neutral term, especially as competitors adopt the same filename.

Challenges and Limitations

AGENTS.md is not a silver bullet. The file’s contents can become stale if not actively maintained alongside the codebase, leading to AI assistants operating on outdated assumptions. Conflicting rules—say, one paragraph forbidding test skipping and another encouraging rapid prototyping—can confuse the AI. And not every tool currently supports AGENTS.md; many popular assistants still rely on their own proprietary configuration mechanisms.

Standardization is another open question. Without an RFC-style specification, the exact semantics of AGENTS.md are left to each tool’s implementation. One AI might interpret “always run tests” as a hard requirement, while another might treat it as a suggestion. The developer community is beginning to discuss whether a formal schema—perhaps a YAML or TOML format with machine-readable checklists—would improve reliability.

Critics also point out that AGENTS.md shifts responsibility from the tool to the user: if an AI makes a mistake, the developer is expected to have specified better instructions. This can lead to a blame game, with maintainers spending more time debugging the policy file than actually fixing code.

The Future of Repository Policy for AI

As AI coding agents become more autonomous, the role of AGENTS.md will likely expand. Future versions might include:

  • Agent-to-agent protocols: Allowing an AI reviewer agent to read AGENTS.md and automatically request changes on AI-generated PRs.
  • Dynamic overrides: Certain rules that activate only during specific phases of the development cycle, such as relaxed testing during prototyping sprints.
  • Telemetry and audit logs: Tying AGENTS.md violations to an audit trail that shows which rules were broken, by which AI, and when.

The six repositories highlighted here are not just users of AGENTS.md; they are reference implementations for the rest of the industry. Their public experiments will shape how the file evolves. Coder’s detailed AGENTS.md has already been forked and adapted by several smaller projects, demonstrating the viral potential of a well-crafted policy file.

For teams still on the fence, the message is clear: AGENTS.md is leaving the experimental phase and entering standard engineering practice. Adding one to your repository—even a minimal version specifying coding style and test commands—can pay immediate dividends in AI-authored code quality. Treat it like you would a linter configuration: version it, review changes, and iterate as your project grows.

2026 may well be the year that AGENTS.md becomes as ubiquitous as README.md. And for a discipline that blends documentation, policy, and prompt engineering, that’s a remarkable ascent from a simple Markdown file.