Augment Code and AGENTS.md: The Complete 2026 Setup Guide

Auggie, Augment Code’s CLI agent, looks for rules files in a specific order — and CLAUDE.md ranks above AGENTS.md, not below it. That’s the opposite of what most teams assume when they add an AGENTS.md file expecting it to be Augment’s primary source of truth. Augment Code is one of the tools listed as supporting AGENTS.md on the format’s own site, and it also happens to be the vendor that published one of the more detailed public breakdowns of a February 2026 ETH Zurich study on whether context files help at all. This guide covers what Augment’s docs actually say about file discovery, where that ETH Zurich research fits in, and what to do with both.

What Augment Code Is

Augment Code is an AI coding agent built around a proprietary Context Engine — a semantic index that maps an entire codebase (Augment cites up to 400,000 files) including function signatures, class hierarchies, import chains, and API contracts, kept live as the repo changes. Auggie is Augment’s CLI, a terminal-based agent that pairs that Context Engine with AGENTS.md-style rules files. Since February 2026, the Context Engine has also shipped as a standalone MCP server, so Cursor, Claude Code, Zed, Kilo Code, and Roo Code can query it directly without running Auggie itself.

The Exact Rules Precedence, Per Augment’s Docs

Augment’s official documentation at docs.augmentcode.com/cli/rules states plainly: “Auggie looks for rules files in the following order of precedence.” That order is:

1. Custom rules file — passed explicitly via --rules "/path/to/custom-rules.md"
2. CLAUDE.md
3. AGENTS.md
4. Workspace guidelines — <workspace_root>/.augment-guidelines
5. Workspace rules folder — <workspace_root>/.augment/rules/ (recursively searches .md files)
6. User rules folder — ~/.augment/rules/ (recursively searches .md files)

The two details worth sitting with:

CLAUDE.md is checked before AGENTS.md. If your repo carries both files with genuinely different content — a common setup for teams that ship a Claude Code-specific file alongside a tool-agnostic AGENTS.md — Auggie’s documented precedence puts CLAUDE.md first. This is easy to miss, because most tool coverage on this subject treats AGENTS.md as the universal default and CLAUDE.md as the exception. In Auggie specifically, it’s inverted.

Only two of the six file types are hierarchical. Per the docs, “for AGENTS.md and CLAUDE.md files specifically, the system walks directory trees” — checking the directory of the file being edited, then each parent directory up to the workspace root. The .augment/rules/ folder does not get this treatment: it “load[s] only from the workspace root,” regardless of which subdirectory you’re actually working in.

Workspace Rules vs. User Rules: Frontmatter Matters

Augment splits rules into two scopes with different behavior:

• User rules (~/.augment/rules/) apply across every workspace on your machine. They ignore YAML frontmatter entirely and are always treated as always_apply.
• Workspace rules (<workspace_root>/.augment/rules/) are project-specific and support frontmatter with two fields: type (always_apply, the default, or agent_requested) and description (required when type is agent_requested).

A workspace rule file that should only load when relevant — rather than being injected into every prompt — looks like this:

---
type: agent_requested
description: "Database migration conventions. Use when writing or reviewing Prisma migrations."
---

# Migration Rules

- Every migration needs a corresponding rollback script in `migrations/rollback/`.
- Never run `prisma migrate reset` against a shared branch database.
- Migrations touching `users` or `billing` tables require a second reviewer.

Compare that to a minimal, hierarchy-aware AGENTS.md at a repo root:

# AGENTS.md

## Stack
Next.js 15, TypeScript strict, Postgres via Prisma. Deploys to Vercel.

## Commands
- `pnpm test` — unit tests (must pass before any commit)
- `pnpm build` — production build, run before opening a PR

## Don't touch
- 🚫 `infra/` — deployment config, reviewed separately
- ⚠️ `packages/billing/` — ask before editing, Stripe webhook logic lives here
- ✅ Everything else

And a one-off override via the CLI flag, which sits above both files in precedence:

auggie --rules "./ci-strict-rules.md" "fix the failing test in checkout.spec.ts"

The ETH Zurich Study Augment Cites — And What It Actually Found

In February 2026, researchers at ETH Zurich’s SRI Lab — Thibaud Gloaguen, Niels Mündler, Mark Niklas Müller, Veselin Raychev, and Martin Vechev — published “Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?” (arXiv:2602.11988). Augment’s own guide, “How to Build Your AGENTS.md,” cites it directly, which is worth taking seriously given Augment has an obvious commercial incentive to say context files help.

The study built AGENTbench, a benchmark of 138 tasks drawn from 12 real Python repositories that already had developer-written context files in place, sourced from 5,694 actual GitHub pull requests. It tested three agents — Claude Code, Codex, and Qwen Code — across models including Sonnet-4.5, GPT-5.2, GPT-5.1 mini, and Qwen3-30b-coder, comparing task success with no context file, an LLM-generated one, and a human-curated one.

The results split sharply by who wrote the file:

In other words: an AGENTS.md an LLM wrote for you tends to make task success rates slightly worse while making every task more expensive to run. A file a human actually wrote and maintained delivered a real, if modest, gain — except for Claude Code, where even the human-curated version underperformed no file at all in the study’s test set. The paper’s own recommendation is to keep context files to “minimal requirements” — specific tooling and non-standard conventions — and cut the parts most AGENTS.md guides tell you to add first: full repo overviews and directory enumerations, which the study found agents already reconstruct fine on their own by exploring the codebase.

That recommendation lines up almost exactly with what Augment’s own setup guide independently tells you to do: keep files under 150–200 lines, lead with executable commands and a three-tier “don’t touch” list (✅ always / ⚠️ ask first / 🚫 never), and skip the codebase overview section entirely if a README already covers it. For a tool built around a Context Engine that already indexes the whole repo semantically, that overlap isn’t a coincidence — Augment’s Context Engine is explicitly positioned as covering the “what does this codebase look like” job that a bloated AGENTS.md would otherwise be doing badly.

Augment Code vs. Other AGENTS.md-Reading Tools

Augment’s combination of hierarchical file discovery plus a persistent semantic index is closer to Factory Droid’s model than to single-shot cloud agents like Jules — both are built for someone working interactively inside a large, possibly monorepo-structured codebase, where “which directory am I in” actually changes what rules should apply.

Where Secrets Shouldn’t Live

Between ~/.augment/rules/ (your personal machine), .augment/rules/ (committed to the repo), and the Context Engine MCP server now reachable from multiple editors, an Augment Code setup can end up with credentials referenced from several places at once — and a plain-text rules file is not where any of them belong. If a workspace rule needs to reference an API key for a script it documents, that’s a sign the key should be injected at runtime instead. 1Password’s CLI (op run) keeps secrets in a vault and injects them into the process environment on demand — for a script your .augment/rules/ file documents, or for the MCP server config connecting Augment’s Context Engine to another editor — so nothing sensitive ends up committed alongside your rules.

FAQ

Q1. Does Augment Code support AGENTS.md? Yes. Augment Code is listed among the tools supporting AGENTS.md on the format’s own site, and Auggie CLI’s documentation at docs.augmentcode.com/cli/rules confirms it as one of six rules file types it checks, with a stated order of precedence.

Q2. Does Auggie read CLAUDE.md or AGENTS.md first? CLAUDE.md. Per Augment’s docs, the precedence order is: custom --rules flag, then CLAUDE.md, then AGENTS.md, then .augment-guidelines, then the workspace .augment/rules/ folder, then the user ~/.augment/rules/ folder.

Q3. Does Augment Code support nested AGENTS.md files in a monorepo? Yes, for AGENTS.md and CLAUDE.md specifically — the docs state the system “walks up the directory tree, checking each parent directory for these files,” starting from the file being edited and stopping at the workspace root. The .augment/rules/ folder does not get this treatment and only loads from the workspace root.

Q4. Does an LLM-generated AGENTS.md actually help coding agents? According to a February 2026 ETH Zurich study (arXiv:2602.11988) that Augment’s own guide cites, no — LLM-generated context files reduced task success rates by an average of 0.5% (SWE-bench Lite) to 2% (AGENTbench) while increasing inference cost by 20–23%. Human-curated files performed better, with a roughly 4 percentage point gain on AGENTbench, though the study found Claude Code specifically underperformed even with a human-written file.

Q5. What should an AGENTS.md for Augment Code actually contain? Augment’s own setup guide recommends tech stack details with exact versions, executable commands (placed early), coding conventions that are counterintuitive rather than obvious, testing commands, a three-tier “don’t touch” list, and non-standard tooling notes — kept under 150–200 lines. It explicitly recommends skipping redundant codebase overviews, which is also what the ETH Zurich study found agents don’t need a written summary for.

Q6. Should I maintain separate CLAUDE.md and AGENTS.md files, or symlink them? Augment’s guide recommends symlinking CLAUDE.md to AGENTS.md for teams using multiple tools, so there’s one file instead of two that can drift apart. If you keep them as genuinely separate files, remember Auggie’s precedence checks CLAUDE.md first — content that exists only in AGENTS.md may not be what Auggie actually reads if a differing CLAUDE.md is present.

Q7. How is Augment Code’s Context Engine different from just writing a good AGENTS.md? The Context Engine semantically indexes the codebase live — function signatures, class hierarchies, import chains — rather than relying on a static file a human has to keep updated. Augment positions AGENTS.md as being for instructions and conventions a semantic index can’t infer (don’t-touch zones, non-standard commands, review requirements), not as a substitute for codebase understanding.

Related Reading on The Prompt Shelf

• Google Jules and AGENTS.md: The Complete 2026 Setup Guide
• Goose and AGENTS.md: Hierarchical Context Loading (2026)
• How Factory Droid CLI Discovers AGENTS.md (2026)
• Amp’s AGENTS.md Discovery: The System-Wide Paths (2026)
• Testing AGENTS.md Effectiveness: A Benchmark Approach
• AGENTS.md vs CLAUDE.md: The Complete Decision Guide for 2026

Browse real AGENTS.md examples from open-source repositories in our gallery.