PulseFlow Tecnologia
← Insights
·5 min read·technical-guide·agents-md·harness-engineering·best-practices
PulseFlow Tecnologia

How to structure an AGENTS.md for a corporate repository

AGENTS.md started from a simple premise: "a simple, open format for guiding coding agents" - one predictable place where a coding agent looks for instructions before touching a repository. The real question engineering teams face isn't whether to have one, but what to put inside it so it actually works.

What 2,500+ repositories teach us

A GitHub analysis of more than 2,500 repositories with an agents.md reached a clear conclusion: "the successful agents aren't just vague helpers; they are specialists." Generic descriptions like "helpful coding assistant" don't produce better results - what works is specific instruction with clear boundaries. The study identified six blocks that consistently show up in the most effective AGENTS.md files:

  1. Executable commands - npm test, npm run build, and equivalents, ready to copy and paste
  2. Project structure - where everything lives, without forcing the agent to explore
  3. Tech stack with versions - not "React," but "React 18," "TypeScript 5," and so on
  4. Real code examples - show the expected pattern, don't just describe it
  5. Style patterns - naming and formatting conventions
  6. Clear boundaries - what the agent can do alone, what needs approval, what it should never do

Among the identified restrictions, the most common and most useful was simply "never commit secrets" - a short line that prevents one of the costliest mistakes an agent can make.

Why structure matters at scale: the Codex case

How much this matters becomes clear in an experiment OpenAI documented itself: a repository that started empty in August 2025, with the initial scaffold generated by Codex CLI (GPT-5) - even the initial AGENTS.md itself was written by an agent. Five months later, the repository held roughly a million lines of code, with more than 1,500 pull requests merged, produced by just three engineers driving agents - an average of 3.5 PRs per engineer per day. No line was written manually by a human.

The central lesson from that experiment is what OpenAI calls "legibility": the repository needs to be optimized so an agent can understand the entire business domain from the code and documentation itself - without relying on tacit context. When architecture decisions lived only in Slack conversations, they were as invisible to the agent as they would be to a new hire on day one. The fix was bringing that context into the repository itself, where the agent actually looks.

A reference structure

Combining the 2,500-repository research with the agents.md open format, a consistent corporate AGENTS.md covers, in practice:

  1. Project goal and business domain
  2. Architecture and adopted patterns
  3. Local setup (step by step, assuming no prior knowledge)
  4. Allowed commands (build, test, lint, deploy)
  5. Required tests before any PR
  6. Code style and naming conventions
  7. Security rules (starting with "never commit secrets")
  8. Explicit restrictions - what the agent should never do on its own
  9. Expected pull request flow
  10. Acceptance criteria for considering a task done

The practical point

An AGENTS.md isn't documentation you write once and forget - it's a living artifact, versioned as tightly as the code it governs. Teams that treat this file as part of the architecture, not a footnote, are the same ones that manage to scale from "one agent helping with a task" to "agents driving real delivery," as in the case OpenAI documented.

Sources