AGENTS.md

Amp looks in AGENTS.md files for guidance on codebase structure, build/test commands, and conventions.

File	Example content
`AGENTS.md` in cwd, parent dirs, & subtrees	Architecture, build/test commands, overview of internal APIs, review and release steps
`$HOME/.config/amp/AGENTS.md` `$HOME/.config/AGENTS.md`	Personal preferences, device-specific commands, and guidance that you're testing locally before committing to your repository
`/etc/ampcode/AGENTS.md` `/Library/Application Support/ampcode/AGENTS.md` `%ProgramData%\ampcode\AGENTS.md`	System-wide or organization-managed guidance for all Amp sessions

Amp includes AGENTS.md files automatically:

AGENTS.md files in the current working directory (or editor workspace roots) and parent directories (up to $HOME) are always included.
Subtree AGENTS.md files are included when the agent reads a file in the subtree.
System-wide guidance files, as well as both $HOME/.config/amp/AGENTS.md and $HOME/.config/AGENTS.md, are always included if they exist.

To add personal guidance to top-level agents from the web app, open Settings, select Advanced, and edit Global AGENTS.md.

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.

In a large repository with multiple subprojects, we recommend keeping the top-level AGENTS.md general and creating more specific AGENTS.md files in subtrees for each subproject.

To see the agent files that Amp is using, select agents-md list from the command palette.

Writing AGENTS.md Files

Amp offers to generate an AGENTS.md file for you if none exists. You can create or update any AGENTS.md files manually or by asking Amp (“Update AGENTS.md based on what I told you in this thread”).

To include other files as context, @-mention them in agent files. For example:

See @doc/style.md and @specs/\*_/_.md.

When making commits, see @doc/git-commit-instructions.md.

Relative paths are interpreted relative to the agent file containing the mention.
Absolute paths and @~/some/path are also supported.
@-mentions in code blocks are ignored, to avoid false positives.
Glob patterns are supported (such as @doc/*.md or @.agent/**/*.md).

Granular Guidance

To provide guidance that only applies when working with certain files, you can specify globs in YAML front matter of mentioned files.

For example, to apply language-specific coding rules:

Put See @docs/*.md anywhere in your AGENTS.md file.

Create a file docs/typescript-conventions.md with:

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

Follow these TypeScript conventions:

- Never use the `any` type
- ...

Repeat for other languages.

Mentioned files with globs will only be included if Amp has read a file matching any of the globs (in the example above, any TypeScript file). If no globs are specified, the file is always included when @-mentioned.

Globs are implicitly prefixed with **/ unless they start with ../ or ./, in which case they refer to paths relative to the mentioned file.

Other examples:

Frontend-specific guidance: globs: ["src/components/**", "**/*.tsx"]
Backend guidance: globs: ["server/**", "api/**"]
Test guidance: globs: ["*.test.ts", "__tests__/*"]