---
lastModified: 2026-08-25
---

# AGENTS.md

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

<table>
  <thead>
    <tr>
      <th>File</th>
      <th>Example content</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td class="leading-loose whitespace-nowrap">
        <code>AGENTS.md</code><br/><span class="text-muted-foreground italic">in cwd, parent dirs, &amp; subtrees</span>
      </td>
      <td>Architecture, build/test commands, overview of internal APIs, review and release steps</td>
    </tr>
    <tr>
      <td class="whitespace-nowrap"><code>$HOME/.config/amp/AGENTS.md</code><br/><code>$HOME/.config/AGENTS.md</code></td>
      <td>Personal preferences, device-specific commands, and guidance that you're testing locally before committing to your repository</td>
    </tr>
    <tr>
      <td class="whitespace-nowrap"><code>/etc/ampcode/AGENTS.md</code><br/><code>/Library/Application Support/ampcode/AGENTS.md</code><br/><code>%ProgramData%\ampcode\AGENTS.md</code></td>
      <td>System-wide or organization-managed guidance for all Amp sessions</td>
    </tr>
  </tbody>
</table>

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 <span class="ui">Settings</span>, select <span class="ui">Advanced</span>, and edit <span class="ui">Global AGENTS.md</span>.

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 <span class="ui">agents-md list</span> 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 (<em>"Update AGENTS.md based on what I told you in this thread"</em>).

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

```markdown
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:

   ```markdown
   ---
   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__/*"]`