technical
Dark Factories

AGENTS.md

An open standard file format for giving AI coding agents context about a project. Co-launched by Google, OpenAI, Factory.ai, Sourcegraph, and Cursor. Adopted in 20,000+ GitHub repositories. The cross-vendor equivalent of Anthropic's CLAUDE.md.

AGENTS.md is an open standard for the file that tells coding agents what they need to know about your project. Place it in your repository root; agents automatically read the nearest file in the directory tree.

20,000+ GitHub repositories have adopted it as of early 2026.

What Goes In It

The “tribal knowledge” that engineers carry that agents need to operate independently:

  • Build steps — how to compile, run tests, deploy
  • Test commands — the exact commands to run, not just “run the tests”
  • Style rules — naming conventions, code organization preferences
  • PR guidelines — what a good PR looks like, review criteria
  • MCP server documentation — what tools are available to agents
  • Known gotchas — the things that would take a new engineer weeks to discover

How It Works

When an agent starts working in a repository, it looks for the nearest AGENTS.md file in the directory tree (same scoping logic as .gitignore). The file is read as context before any other task.

Cross-Agent Compatibility

AGENTS.md is supported by:

  • GitHub Copilot (Coding Agent)
  • Google Jules
  • OpenAI Codex
  • Factory.ai Droids
  • Aider
  • Cursor
  • Cline

Relationship to CLAUDE.md

CLAUDE.md is Anthropic’s analogous format, specific to Claude Code. AGENTS.md is the cross-vendor open standard. Both serve the same architectural purpose: giving agents repo-specific context they need to operate autonomously.

In practice: maintain both if you use Claude Code heavily (CLAUDE.md for Claude-specific instructions) plus AGENTS.md for cross-agent compatibility.

Why This Matters for Dark Factories

At Level 5, the agent needs to understand the repository without asking a human. AGENTS.md externalizes the institutional knowledge that would otherwise require human explanation. It’s the spec-layer for the agent’s operational context — separate from, and prerequisite to, the NLSpecs that describe individual features.

Without good AGENTS.md documentation, agents make wrong assumptions about build tooling, test runners, naming conventions, and deployment processes — wasting compute and producing wrong implementations.

Spec

The specification lives at agents.md and github.com/agentsmd/agents.md. Launched jointly by Google, OpenAI, Factory.ai, Sourcegraph, and Cursor.