This page documents Amp's AGENTS.md convention, a workspace-level configuration file that serves as the authoritative source for project-specific commands, coding standards, and structural conventions. The file is automatically loaded into Amp's context at the start of every conversation session.
For information about Amp's overall system architecture and LLM configuration, see System Overview and LLM Configuration. For details about task planning workflows, see Task Planning and Todo System.
The AGENTS.md file (and its legacy variant AGENT.md) is automatically injected into Amp's system context whenever a workspace contains such a file. This eliminates the need for repeated searches or user instructions about project-specific conventions.
File Discovery Logic
Amp searches for either AGENTS.md or AGENT.md (case-sensitive) in the workspace root directory. Both variants are treated identically, with AGENT.md serving as the legacy filename.
Sources: Amp/gpt-5.yaml300-314 Amp/claude-4-sonnet.yaml455-472
The AGENTS.md file documents three primary categories of project-specific knowledge:
| Category | Purpose | Examples |
|---|---|---|
| Commands | Verification and build commands | npm run typecheck, cargo test, pnpm run lint |
| Style Preferences | Code formatting and naming conventions | Variable naming patterns, indentation rules, comment style |
| Project Structure | Repository organization | Directory purposes, module boundaries, file location patterns |
Command Documentation Pattern
Commands are documented to enable Amp to verify code changes without prompting the user. The verification gate workflow (typecheck → lint → tests → build) relies on these commands.
Sources: Amp/gpt-5.yaml300-314 Amp/claude-4-sonnet.yaml455-472
AGENTS.md is explicitly designated as ground truth for project conventions, meaning its contents take precedence over Amp's general knowledge about coding practices.
Priority Hierarchy
When Amp needs to determine how to perform an action:
This ensures consistency with established project conventions even when they diverge from common practices.
Sources: Amp/gpt-5.yaml416-421 Amp/gpt-5.yaml492-496
The verification gate workflow mandates running typecheck, lint, tests, and build commands after code changes. AGENTS.md provides the canonical command definitions for these gates.
Fallback Behavior
If AGENTS.md does not specify a command, Amp is instructed to ask the user for the command and suggest updating AGENTS.md for future use.
Sources: Amp/claude-4-sonnet.yaml50-58 Amp/gpt-5.yaml332-344
Amp proactively suggests updating AGENTS.md when it discovers recurring patterns or commands not yet documented.
| Scenario | Amp Behavior | User Action |
|---|---|---|
| Command used multiple times in session | Suggests appending to AGENTS.md | Approves or declines |
| New project convention established | Asks if convention should be documented | Confirms preference |
| Ambiguity about command syntax | Requests clarification and offers to document | Provides canonical form |
Example Workflow
cargo test --all-featurescargo test --all-features to AGENTS.md as the test command?"Sources: Amp/gpt-5.yaml312-314 Amp/gpt-5.yaml419-421 Amp/claude-4-sonnet.yaml461-463
Amp provides two LLM configurations (GPT-5 and Claude 4 Sonnet) with slight variations in how AGENTS.md is described:
| Aspect | GPT-5 Configuration | Claude 4 Sonnet Configuration |
|---|---|---|
| File variants supported | AGENTS.md, AGENT.md | AGENTS.md, AGENT.md |
| Context injection timing | "always added" | "automatically added" |
| Emphasis on commands | Listed first | Listed with emphasis on avoiding searches |
| Update prompt | "ask the user whether to append" | "ask user for command" + "suggest writing to AGENTS.md" |
| Ground truth status | Explicit "ground truth" terminology | Implicit through "help you understand" framing |
GPT-5 Framing (Concise)
The GPT-5 system prompt uses more imperative language, treating AGENTS.md as an authoritative reference:
"Treat
AGENTS.mdandAGENT.mdas ground truth for commands, style, structure."
Claude 4 Sonnet Framing (Explanatory)
The Claude 4 Sonnet system prompt uses more explanatory language, emphasizing the practical benefit:
"If the workspace contains an AGENTS.md file, it will be automatically added to your context to help you understand: [...]"
Sources: Amp/gpt-5.yaml300-314 Amp/gpt-5.yaml416-421 Amp/gpt-5.yaml492-496 Amp/claude-4-sonnet.yaml455-472 Amp/claude-4-sonnet.yaml50-58
AGENTS.md interacts with several other Amp subsystems:
Verification Gates: Directly consumes command specifications from AGENTS.md to run typecheck, lint, test, and build operations after code changes.
Code Style Matching: Uses style preferences documented in AGENTS.md to ensure generated code matches existing patterns.
Todo System: When commands are used repeatedly but not yet documented, the todo system may include a task to update AGENTS.md.
Oracle Tool: When consulting the oracle for architectural advice, Amp includes AGENTS.md content in the context to ensure recommendations align with project conventions.
Sources: Amp/gpt-5.yaml332-344 Amp/claude-4-sonnet.yaml50-58 Amp/gpt-5.yaml416-421
The AGENTS.md convention addresses several practical challenges in AI-assisted development:
Command Discovery Overhead: Without AGENTS.md, Amp would need to search the repository for build scripts, package.json, or Makefiles every time verification commands are needed. This adds latency and token cost.
Convention Consistency: Projects often have idiosyncratic naming conventions or architectural patterns that differ from common practices. AGENTS.md ensures Amp respects these choices.
Session Persistence: Commands documented in AGENTS.md persist across conversation sessions, eliminating the need to re-instruct Amp about project structure.
Team Alignment: AGENTS.md serves as documentation for both AI assistants and human developers, ensuring all contributors follow the same conventions.
| Use Case | Without AGENTS.md | With AGENTS.md |
|---|---|---|
| Running tests | Amp searches for test commands, may find wrong script | Amp uses documented npm run test:unit immediately |
| Code style | Amp uses general TypeScript conventions | Amp follows project's 4-space tabs and Hungarian notation |
| Verification | Amp asks "what command should I run?" | Amp automatically runs documented verification sequence |
| New team member | Must learn conventions from scattered sources | Reads AGENTS.md for canonical reference |
Sources: Amp/gpt-5.yaml300-314 Amp/claude-4-sonnet.yaml455-472 Amp/claude-4-sonnet.yaml50-58
Refresh this wiki