AGENTS.md

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

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.

Workspace admins can add guidance for every workspace member. Open Workspace Settings, select Advanced, and edit Global AGENTS.md. Amp includes workspace guidance before personal and repository guidance. It does not apply to subagents, Puck, or raw custom agents.

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.

Ignoring Guidance Files

Set AMP_IGNORE_GUIDANCE_FILES to a colon-delimited (:) list of globs to skip matching guidance files. Amp matches globs against absolute file paths, including hidden directories. Use / as the path separator and ** to match across directories.

For example, skip your personal guidance for a non-interactive CLI run without changing $HOME:

AMP_IGNORE_GUIDANCE_FILES="$HOME/.config/amp/AGENTS.md:$HOME/.config/AGENTS.md" amp -x "do the thing"

Use **/.config/amp/** to skip all guidance files under an Amp user config directory. Quote the value so your shell does not expand the globs.

Set AMP_IGNORE_GUIDANCE_FILES='*' to ignore all guidance files and prevent Amp from loading any AGENTS.md files automatically.

Ignored files are not read as guidance, but the agent can still read them explicitly with a tool.

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:

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

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

   ---
   globs:
     - '**/*.ts'
     - '**/*.tsx'
   ---
   
   Follow these TypeScript conventions:
   
   - Never use the `any` type
   - ...

3. 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__/*"]