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

说明与用途

AGENTS.md 是指令指南，而非上下文文件。通过添加 project.faf 作为唯一事实来源，并生成包含管理块的 AGENTS.md，代理能够获得准确指令和最新数据，减少猜测并提高编码效率。

问题

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

结果

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

工作流

• 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.

证据

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

来源

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

来源

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.

来源

npx faf-cli export --agents

来源

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".

来源