The Definitive Guide to AGENTS.md

Summary: The Definitive Guide to AGENTS.md (AI coding agents + agents.md)

Why agents.md matters

• The speaker argues that agents.md (an agents’ instruction/context file) is one of the most important files when using AI coding agents.
• Well-written content improves agent performance.
• Poor or outdated content can:
  • slow agents down,
  • increase token usage (higher inference cost),
  • confuse the agent—especially when repository information becomes outdated.

What the guide covers (tutorial structure)

• What agents.md is and what to include.
• What not to include.
• Using research papers to evaluate context files.
• A “live audit” of the speaker’s own agent files to demonstrate:
  • what’s outdated,
  • what to remove,
  • and how to audit your own agents.md.

---

Key technological concepts & findings

1) “Repository context” (what not to include)

A major caution: don’t add information the model can infer from the code, such as repository/project structure.

• A referenced research paper (published in February of the year mentioned) reports:
  • context files can reduce task success rate versus having no repo context,
  • while increasing inference cost by ~20% (token usage).
• The speaker’s practical reasoning:
  • If you provide specific file/folder instructions, the agent may load in too much context.
  • When the project changes, the context becomes stale, and the agent wastes steps detecting what’s missing.

Rule proposed: Whatever can be learned from the code, leave it there. Therefore, avoid adding directory structure / project structure in agents.md.

2) What is valuable to include in agents.md

Since agents.md is loaded into every message/session, it should contain only high-value instructions that aren’t extractable from code.

Recommended inclusions:

• TDD (Test-Driven Development) workflow instructions
  • Agents should write tests first, then implement, and use tests for validation.
  • Framed as something the agent can’t reliably infer from code alone.
• Command conventions
  • Even if some commands exist in package.json, the speaker uses repo-specific workflows for which tests/commands to run by feature area.
• Product invariance / design decisions
  • Non-negotiable rules the agent must respect (not reliably deducible from code).
  • Example: “gates” failure behavior
    • “gates” are stopping points where the user is asked questions.
    • if gates fail, the system should not crash; it should continue and log errors for later review.
  • “Agent neutrality” and Altitude app compatibility
    • avoid agent-specific behaviors inside instructions so the same project can work across different agent harnesses.
• Commit discipline
  • The speaker dislikes agents committing immediately after completing work; this should be controlled via instructions.

---

Product features / multi-harness agent setup

How harnesses load these files

Different AI coding harnesses (e.g., Cloud Code, Cursor, Codeex, Windsurf, Copilot) can load agents.md based on working directory.

• Cloud Code special case:
  • Cloud Code loads cloud.md instead of agents.md.
  • Best practice: create a minimal cloud.md that imports the canonical agents.md using an “import syntax” (e.g., described in subtitles like u@agents.md) so all harnesses read the same source instructions.

File location hierarchy (project vs directory vs root)

The speaker describes multiple levels of agents.md / cloud.md:

• Root level (common to all projects / loaded always)
  • Cross-project preferences and shared conventions
  • Not project-specific constants
• Project level
  • Project-specific commands and constants
• Subdirectory level
  • Loaded depending on the directory the agent operates in
  • Useful for large mono-repos with different team/project conventions
  • The speaker says it’s typically not needed early on

Symlink/import approach for Cloud Code + Codex

• The speaker uses a “root/cloud” structure.
• Notes:
  • In some harness directories (e.g., Codex), agents.md may be a symlink pointing to the real cloud files.
  • Caution: symlinks may break after git clone on some platforms (e.g., Windows).
  • For GitHub collaboration, prefer an import method over symlinks for portability.

Headless Codex note

• Even in headless mode, Codex still reads these root files—so linking/paths must be correct across harnesses.

---

Agent-operations guidance (skills, cost control, workflow)

Skills for “load only when needed”

The speaker suggests moving parts of instructions into skills so they load only when triggered, reducing environment/token cost.

Example:

• A “No Mistakes” gate/agent method:
  • implemented via a smaller sub-agent in a new environment for the easier part of a flow.
  • recommended to put it into a project.cloudmd, or better, into a skill so you don’t pay cost every conversation.

Technical decision-making tip (design tradeoffs)

• LLMs may overemphasize “development cost” due to human dev timelines influencing training/rating.
• Recommendation:
  • down-weight “development cost,” recognizing the agent can write code quickly.
• Framed as a note that should be included in all plans.

Context re-entry between multiple projects/agents

The speaker includes guidance for context re-entry:

• End each method/summary with:
  • a simple review summarizing what was done,
  • and most importantly the next action,
• so the human doesn’t need to re-check what’s pending.

Build orchestration / parallel sub-agents

• During auditing, the speaker discusses moving some “run agents in parallel / sub-agent build lane” orchestration logic into skills.
• Conclusion: not every agent/build needs all orchestration logic—so modularize.

---

Live audit: how the speaker removes outdated/unhelpful content

In the live review, the speaker:

• avoids dumping copied examples all at once; instead adds/removes content gradually,
• uses a “North Star” article/thesis for guidance,
• asks an agent (Claude) to “censor” agents.md by removing unneeded or outdated sections.

Specific removals mentioned include:

• outdated sections duplicating content already provided at root/project levels,
• untracked/empty demo files,
• Docker Compose instructions/steps replaced by an automated workflow,
• content contradicting the principle: only include what can’t be learned from code.

---

Reviews / guides / tutorials emphasized

• Research-backed guidance on repo context vs. success/cost tradeoffs.
• A checklist-style best practice for “what to include vs not to include” in agents.md.
• A tutorial workflow for auditing your own agents.md:
  • revise gradually,
  • remove duplicates/stale sections,
  • move expensive logic into skills (load-on-demand),
  • keep harness-agnostic configuration via root/project/subdirectory structure and Cloud Code import.

---

Main speakers / sources

• Main speaker: The video author (conducting the live audit and instruction, explicitly referencing their own agents.md files and systems like “Altitude,” “The Workshop,” and “No Mistakes”).
• Sources referenced:
  • A research paper published in February about the usefulness of repository context files (effects on success rate and inference cost).
  • A “North Star” article/thesis guiding the audit and curation.
  • “Kungchen,” mentioned as the origin of the technical decision-making tip.