I argued with AI (Codex) about AGENTS.md. Then I realized what it actually was.

Description and use

AGENTS.md is an instruction guide, not a context file. By adding project.faf as the single source of facts and generating AGENTS.md with a managed block, agents receive accurate instructions and up‑to‑date data, reducing guesswork and improving coding efficiency.

Problem

Agents misinterpret AGENTS.md as a context file rather than an instruction guide, leading to confusion and inefficient coding workflows.

Outcome

Agents now receive clear instructions from AGENTS.md and accurate facts from project.faf, reducing guesswork and improving coding efficiency.

Workflow

• 1. Create project.faf YAML file with validated facts (goal, stack, who, why).
• 2. Run npx faf-cli auto to generate or update project.faf from repo data.
• 3. Run npx faf-cli export --agents to create AGENTS.md with a managed block of facts and instructions.
• 4. Agents read AGENTS.md for instructions and use project.faf for factual context.
• 5. Repeat steps 2–3 whenever facts change to keep AGENTS.md current.

Evidence

All three got FAF from the get-go. It had a schema and it was YAML, and they love structured data.

Source

AGENTS.md is a guide for agents: how to build, how to test, the conventions, what not to touch. Instructions.

Source

project.faf is a small YAML file at the root of a repo. It is to context what package.json is to dependencies, and it sits right next to it.

Source

npx faf-cli export --agents

Source

A 2026 study, Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? found that "providing context files does not generally improve task success rates, while increasing inference cost by over 20% on average".

Source