Manu's Vault

AGENTS-md-Files

3 min readStatus:Seedling

AGENTS.md (and its tool-specific equivalents such as CLAUDE.md, .cursor/rules/, and .github/copilot-instructions.md) are repository-level markdown files that get injected into an AI coding agent’s system prompt at the start of every session. They are the lowest-friction layer of Harness-Engineering: plain text, version-controlled, and editable by anyone without touching agent infrastructure.

Mechanism

When the harness launches, it reads the AGENTS.md file from the repository root and prepends its contents to the agent’s context window. This happens before the agent sees any task, making it a form of ambient, always-on Context-Engineering. Most tools — Claude Code, Cursor, GitHub Copilot — implement the same pattern under different filenames; the concept is tool-agnostic even if filenames differ.

Design Principles

Evidence-backed guidelines for writing effective AGENTS.md files:

  • Keep it short — under 60 lines is a practical target; every line enters every session regardless of relevance
  • Universally applicable only — instructions should apply to nearly every task in the repo; edge-case rules belong in task-specific prompt files or skills
  • Non-inferable content only — tooling commands, custom build steps, naming conventions the model cannot derive from the code are worth including; directory listings and architecture overviews are not
  • Never auto-generate — LLM-generated AGENTS.md files consistently hurt performance; craft content by hand
  • Progressive disclosure — structure instructions so the most critical information is visible at the top; defer detailed how-to guidance to referenced files (e.g., docs/testing.md)

What Belongs Here vs Elsewhere

Content TypeAGENTS.mdSkills / PromptsMCP Tools
Custom build commands✓
Non-standard test runner flags✓
Task-specific workflows✓
Dynamic data (APIs, DBs)✓
Architecture overview✗
Directory listings✗

Known Failure Modes

  • Over-stuffing: adding comprehensive documentation defeats the purpose — it increases cost without improving outcomes
  • Auto-generation: producing the file from a model introduces drift and verbosity; the ETH Zurich study (Gloaguen et al., 2026) found LLM-generated files reduced task resolve rates by ~3% while inflating inference cost by over 20%
  • Conditional rules: instructions of the form “if X then Y” add reasoning overhead that slows the agent and rarely triggers correctly
  • Stale content: AGENTS.md must be maintained; outdated conventions mislead the agent more than no instructions at all

Sources

  • Gloaguen, Thibaud, Niels Mündler, Mark Müller, Veselin Raychev, and Martin Vechev (2026). “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?” arXiv preprint. arXiv:2602.11988. ETH Zurich SRI Lab.

    • Empirical study on 138 real-world Python repositories; evaluated four coding agents on SWE-bench Lite and AGENTBENCH; key finding: LLM-generated files reduce resolve rate by ~3%, inflate cost by >20%; recommendation: omit LLM-generated files, limit human-written to non-inferable tooling details
    • Available: https://arxiv.org/abs/2602.11988

  • Horthy, Dex (2026). “Skill Issue: Harness Engineering for Coding Agents.” HumanLayer Blog.

  • Cursor Inc. (2025). “Rules.” Cursor Documentation.

    • Documents the .cursor/rules/ system (successor to deprecated .cursorrules), showing the cross-tool universality of the repository-level context file pattern
    • Available: https://cursor.com/docs/context/rules

  • Osmani, Addy (2026). “Stop Using /init for AGENTS.md.” AddyOsmani.com.

Note

This content was drafted with assistance from AI tools for research, organization, and initial content generation. All final content has been reviewed, fact-checked, and edited by the author to ensure accuracy and alignment with the author’s intentions and perspective.

Graph View

Backlinks