AGENTS.md Amp Sourcegraph Claude Code AI rules 2026

Amp's AGENTS.md Discovery: The System-Wide Paths (2026)

The Prompt Shelf ·

Amp, Sourcegraph’s autonomous coding agent, reads AGENTS.md — that much is documented in the manual’s table of contents. What’s easy to miss is how much further Amp’s search goes than the repo-and-home-directory pattern most tools use. Amp also checks three operating-system-level config paths that no project file ever touches, and it has its own history with this file format: Amp proposed a singular AGENT.md standard in mid-2025, before switching to the plural form the rest of the ecosystem settled on.

AGENTS.md is a Markdown file that AI coding agents read for project-specific instructions — build commands, conventions, and things a human-facing README doesn’t need. Amp is one of a growing list of tools that read it, alongside Claude Code, Codex, and Factory’s Droid CLI.

Where Amp Actually Looks

Per Amp’s manual, guidance files are pulled in from four kinds of locations:

  • Working directory and parents, up to $HOME — always included, no action required.
  • Subtree files — an AGENTS.md deeper in the project is included once the agent reads a file in that subtree (lazy-loaded, not scanned upfront).
  • System-wide locations — one per OS:
    • /etc/ampcode/AGENTS.md (Linux)
    • /Library/Application Support/ampcode/AGENTS.md (macOS)
    • %ProgramData%\ampcode\AGENTS.md (Windows)
  • Home config — both $HOME/.config/amp/AGENTS.md and $HOME/.config/AGENTS.md load if present.

That system-wide tier is the part most AGENTS.md coverage skips, because most tools don’t have one. It exists for machine-level defaults: an IT team imaging developer laptops, or a CI provider building a shared runner image, can drop instructions that apply to every Amp session on that machine — no per-repo file required.

The Legacy Fallback Chain

Amp doesn’t require you to have renamed anything. Per the manual: “If no AGENTS.md exists in a directory, but a file named AGENT.md (without an S) or CLAUDE.md does exist, that file will be included.” So the lookup per directory is effectively AGENTS.md → AGENT.md → CLAUDE.md, and a repo that’s only ever had a CLAUDE.md for Claude Code doesn’t need a duplicate file to work with Amp.

A Short History: Why AGENT.md Existed First

Amp’s own May 2025 announcement explains the original choice: it picked the singular AGENT.md specifically to avoid “the proliferation of agent-specific files in your repositories” — one file, not a .cursorrules plus a .clinerules plus a CLAUDE.md all saying the same thing. A later update reversed the naming: “Amp now looks in files named AGENTS.md (with an S),” aligning with the plural convention that OpenAI’s Codex team and the rest of the ecosystem had converged on. The AGENT.md support never went away — it’s the fallback described above, not a deprecated dead end.

Granular Guidance with Globs Frontmatter

Files referenced from an AGENTS.md can carry YAML frontmatter that scopes them to specific file patterns:

---
globs:
  - '**/*.ts'
  - '**/*.tsx'
---

A block like this means the instructions only apply “when working with certain files” — TypeScript-specific conventions that don’t clutter the context when Amp is editing a config file or a doc. Glob patterns get an implicit **/ prefix unless they start with ../ or ./, so *.tsx on its own matches anywhere in the tree.

@-Mentions: Pulling In Other Files

AGENTS.md content isn’t limited to what’s typed inline. Amp supports @-mention syntax to reference other files directly: See @doc/style.md and @specs/**/*.md. A few rules apply:

  • Relative paths resolve relative to the agent file doing the mentioning, not the working directory.
  • Absolute paths and @~/some/path (home-relative) both work.
  • Glob patterns are supported inside a mention.
  • @-mentions inside code blocks are ignored — so documenting the syntax in this article doesn’t accidentally trigger it.

This lets a root AGENTS.md stay short — a table of contents that pulls in @docs/testing.md and @docs/deploy.md — instead of one file trying to hold everything.

Included, Not Overridden — and That’s a Real Difference

Here’s where Amp’s documented behavior diverges from other tools we’ve covered. Factory’s Droid CLI explicitly documents an override model: a nested AGENTS.md replaces the root file’s instructions for its subtree, full stop. Amp’s manual uses different language throughout — files “are included,” full stop, with no mention of one file replacing another. Working directory files, parent files, subtree files, system files, and home-config files all appear to stack rather than override each other.

That’s a meaningful practical distinction: if you’re used to Droid’s or Claude Code’s nested-file-wins model and you bring the same mental model to Amp, you may be surprised that a project-level instruction doesn’t get silently dropped just because a subtree file also applies. The manual doesn’t spell out what happens when two included files give contradictory instructions on the same topic — which is worth testing directly in your own setup rather than assuming either merge or override behavior when content actually conflicts.

What This Means for Managed or Shared Machines

The system-wide tier is useful, but it’s also a place bugs hide. If Amp behaves differently on one machine than another with what looks like an identical repo, check /etc/ampcode/AGENTS.md (or the macOS/Windows equivalents) before assuming the repo-level file changed. On a shared CI runner or a company-imaged laptop, a system-wide file nobody on the team wrote can quietly shape every session — the same troubleshooting instinct we cover in our AGENTS.md not loading guide applies here, just at a layer most people never think to check.

FAQ

Q1. Does Amp read AGENTS.md by default, or does it need to be enabled? By default. Amp always includes AGENTS.md files from the current working directory and parent directories up to $HOME, with no setup required. Subtree, system-wide, and home-config locations load automatically too, under the conditions described above.

Q2. What happens if my repo only has a CLAUDE.md, not an AGENTS.md? Amp uses it. Per Amp’s documented fallback, if a directory has no AGENTS.md, Amp looks for AGENT.md next, and then CLAUDE.md. An existing Claude Code repo doesn’t need a duplicate file to work with Amp.

Q3. Why did Amp originally use AGENT.md instead of AGENTS.md? Amp introduced AGENT.md (singular) in an effort to stop teams from accumulating a separate instruction file per AI tool. It later renamed its default to the plural AGENTS.md to match the naming the wider ecosystem converged on, while keeping AGENT.md working as a fallback.

Q4. Do nested AGENTS.md files override the root file in Amp, like they do in some other tools? Amp’s documentation doesn’t describe an override model — it describes each applicable file as “included.” That suggests files stack rather than one replacing another, which is a different model from tools like Factory’s Droid CLI that explicitly document nested files overriding the root file for their subtree.

Q5. What are the system-wide AGENTS.md paths, and who would actually use them? /etc/ampcode/AGENTS.md on Linux, /Library/Application Support/ampcode/AGENTS.md on macOS, and %ProgramData%\ampcode\AGENTS.md on Windows. They’re aimed at machine-level defaults — IT-managed developer images or shared CI runners — rather than individual project setup.

Q6. Can I reference other files from inside an AGENTS.md in Amp? Yes, using @-mention syntax such as @doc/style.md or a glob like @specs/**/*.md. Relative paths resolve against the file doing the mentioning, absolute and @~/-prefixed paths both work, and mentions inside code blocks are ignored.

Machine-Level Config Files Are a Bigger Blast Radius Than Repo Files

A system-wide AGENTS.md under /etc/ampcode/ or %ProgramData%\ampcode\ sits outside any repo, which also means it sits outside your normal secrets hygiene — it’s easy to forget it exists at all. If credentials ever end up anywhere near a machine-level config an agent reads by default, 1Password CLI’s op run keeps them out of every file entirely, injecting them at runtime instead of leaving them for any agent — or any file on the machine — to stumble into.

Share on X

Related Articles

How Factory Droid CLI Discovers AGENTS.md (2026)

Droid CLI searches .factory/, .agents/, and .agent/ folders up to the git root, and it accepts CLAUDE.md as a compatible filename. The exact precedence order, explained.

Testing AGENTS.md Effectiveness: A Benchmark Approach for Measuring Whether Your Instructions Actually Work

Most teams write AGENTS.md and assume it works. Here's a systematic approach to testing whether your instructions are followed, measuring the delta when they're absent, and fixing the rules that silently fail.

AGENTS.md for Gemini CLI: How Google's Agent Reads Your Instructions (And Where It Diverges from Claude)

Gemini CLI landed with its own take on AGENTS.md support. Here's exactly what it reads, what it ignores, and how to write instructions that work across both Gemini CLI and Claude Code without maintaining two files.

Goose and AGENTS.md: Hierarchical Context Loading (2026)

Block's Goose reads both AGENTS.md and .goosehints, checked at every directory level from your working directory down, with a CONTEXT_FILE_NAMES setting that controls which filenames it looks for. Verified against Goose's own docs.

Explore the collection

Browse all AI coding rules — CLAUDE.md, .cursorrules, AGENTS.md, and more.

Browse Rules