AGENTS.md and the AI Context Debate: How FAF Defines Project Facts

A Debate with Codex

While building the FAF project, developer Wolfe-Jam once got into an argument with OpenAI's Codex. At the time, Claude had CLAUDE.md, Gemini had GEMINI.md, but OpenAI had no CODEX.md—only AGENTS.md. Codex insisted it "had context," while the developer argued it did not, and eventually simply stopped using Codex.

Later, the industry made its choice. AGENTS.md became the file that every coding agent reads, covering Codex, Cursor, Copilot, Windsurf, Amp, and Devin. In December 2025, OpenAI donated it to the Linux Foundation's Agentic AI Foundation, making it an open standard.

According to an rss source, the turning point came from a question posed by a developer in the Svelte community: "Isn't that what AGENTS.md does?" Reexamining the situation, the developer finally had an epiphany—the debate was never about which file would win, but about something Markdown cannot express: what the project actually is.

AGENTS.md is currently the industry's de facto standard file, placed at the root of a code repository to convey project instructions, conventions, and ways of working to various AI coding agents. It was pushed toward standardization by OpenAI in 2025 and donated in December of the same year to the Agentic AI Foundation under the Linux Foundation, becoming a neutral open specification. Its original design intent was to provide a vendor-agnostic entry point: whether you use Codex, Cursor, GitHub Copilot, Windsurf, or Devin, the agent will read this file first, avoiding each tool maintaining its own proprietary configuration (such as CLAUDE.md or .cursorrules). This "single entry point, multi-party compatible" model lowers migration costs, but also brings a widely overlooked problem: it is a plain-text Markdown file that can only hold natural language instructions.

The Boundary Between Definition and Instruction

AGENTS.md is essentially a guide for the agent: how to build, how to test, what the conventions are, what not to touch. It is instruction, and it does that job well. But instruction needs an object to be "about," and that is precisely what Markdown fails to provide.

Hence this dividing line:

• FAF defines. AGENTS.md instructs. AI codes.

project.faf is a small YAML file located at the repository root, sitting side by side with package.json. The developer uses a directory structure to illustrate this relationship:

project/
├── AGENTS.md        ← the agent follows this file
├── package.json     ← npm reads this file
├── project.faf      ← AI reads this file
├── README.md        ← humans read this file
└── src/

What project.faf holds is facts: goals, tech stack, who the users are, what it is, why it exists. Each fact is a verified "verifiable fact" that can only come from two places—the repository itself (faf auto reads runtime, build, CI, and hosting information), or a human (writing or approving via faf go the goals and user information that code cannot reveal). No guessing is allowed, and placeholders like tbd are treated as empty values because they have no source.

Empirical Evidence for Separating Facts and Instructions

This distinction matters more than it sounds. According to a 2026 study titled "Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?" (Gloaguen et al., arXiv 2602.11988), providing context files generally does not improve task success rates and instead increases inference cost by over 20% on average, whether the files are LLM-generated or committed by developers.

The study recommends using them only for non-standard content, and evaluating anything else before relying on it. The latest version of the study adds a key finding: instructions in context files are well followed, but repository overviews—"despite being popular and recommended by model providers"—do not help.

The author's interpretation is this: an overview is essentially just more prose, and prose can be outdated, non-specific, or self-contradictory, leaving the agent unable to tell. So FAF does not write overviews; it keeps definitions in project.faf, giving every fact a source, while what enters AGENTS.md are commands, guardrails, and tech stack—things the agent can run or check. The study tested Markdown context files, demonstrating the limitations of prose, but structured data (schemas in YAML) was not part of it, and the author considers this the next thing that should be tested.

"Inference cost" in this context refers to the total number of tokens an agent consumes to complete a task. Every piece of text in a context file gets injected into the model's context window on every call, so the longer and more detailed the file, the more tokens the agent spends on the same task—and tokens map directly to money and time. The study's core finding is that these extra tokens do not buy a higher task success rate; they just raise costs. This is called the "context tax"—you think you're helping the agent, but in fact you're only making it read more prose that does nothing to help execution. Particularly noteworthy is that models follow instructional statements (such as "run npm test") closely, but for descriptive overviews (such as "this project is a high-performance distributed system") they can barely verify truth or falsehood and simply accept them wholesale—once an overview is outdated, it can mislead decisions.

The Four-Level Ladder for Repositories

Based on this, the context state of any repository can be divided into four levels:

Level	State	Consequence
NONE	No AGENTS.md, the agent guesses	Every session starts from a blank slate
GOOD	Any AGENTS.md	It will quietly go stale
BETTER	AGENTS.md with a managed block: lean, current, checkable	The facts in the block have no source in the repository
BEST	BETTER plus project.faf in the repository: the source behind the block, plus application type and human context	Facts and instructions stay in sync

Most repositories remain in the first column. Reaching GOOD only takes a single file. BEST is the state where facts no longer drift, because they are defined in one place and every instruction file points back to the same source.

The Two Camps Converge

What delighted the author most was the convergence of industry trends. In September 2025, Claude Code also began reading AGENTS.md—in a project without a CLAUDE.md, it would fall back to AGENTS.md. The "two camps" the author once agonized over have now joined forces.

This precisely confirms the core point: the files responsible for instruction will keep changing names, vendors, and rules, but the underlying facts do not change. Define the facts once, and let every instruction file—AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules—point back to the same source.

How to Try It

The developer provides two commands to experience this workflow:

npx faf-cli auto
npx faf-cli export --agents

The second command writes out a standard, spec-compliant Markdown file rather than a FAF dialect. Within it, FAF manages a facts block containing setup commands, build commands, how to run tests, file locations, guardrails, and tech stack. Anything else you hand-write is preserved. When facts change, run the same command again, and the block is rewritten from the source, avoiding drift.

The project repository is at github.com/Wolfe-Jam/faf-cli. The author's advice is: when you're done, ask your agent what this project is—it no longer has to guess.

One-line Summary

Instruction files for AI coding agents are converging on AGENTS.md, but project definition needs to be carried by a structured project.faf.

Paragraph Summary

The article documents the developer Wolfe-Jam's thinking and practice while building the FAF project. The industry ultimately chose AGENTS.md as the instruction file that all coding agents read in common, and pushed it to become an open standard. But the author points out that AGENTS.md is only "instruction" and cannot answer "what the project actually is." To address this, project.faf is proposed: a YAML file located at the repository root, alongside package.json, used to store sourced "verifiable facts" such as goals, tech stack, and users. The article cites a 2026 arXiv study showing that context files add over 20% to inference cost on average without improving task success rates, with repository overview-type content being especially unhelpful. From this comes the boundary between facts and instructions, along with a four-level ladder for repository context states. The core conclusion is: instruction files will change names and vendors, but the underlying source of facts should remain stable.