Amp Best Practices Manual¶

A concise guide to getting the most out of Amp, the AI coding agent.

Agent Modes¶

Mode	Model	Best For
`smart`	Claude Opus 4.5 (200k context)	Complex tasks, new features, debugging, architecture
`rush`	Claude Haiku 4.5	Small, well-defined tasks: simple bugs, minor UI changes
`large`	Claude Sonnet 4.5 (1M context)	Large-scale refactors (use sparingly)

Switch modes: Ctrl+O → type mode (CLI) or select in prompt field (editor)

⚠️ Don't use rush for complex tasks—it often costs more fixing mistakes. Don't use large for regular work—200k tokens is plenty.

Prompting Best Practices¶

Do's¶

Be explicit: Say "do X" instead of "can you do X?"
Keep threads focused: One task per thread
Provide context: Mention specific files, commands, or URLs
Tell it how to verify: Specify tests to run or URLs to check
First prompt matters: It sets the direction—be deliberate

Don'ts¶

Don't mix unrelated tasks (e.g., database migrations + CSS changes)
Don't let failed attempts clutter context—start a fresh thread
Don't make the model guess when you know the answer

Planning (No Dedicated Mode)¶

Amp doesn't have a separate "plan mode"—use natural language instead:

Only plan how to implement this. Do NOT write any code.

For complex planning, use the Oracle subagent for deep reasoning.

Example Prompts¶

Run `pnpm test` and fix all the errors

Look at http://localhost:3000 and make the header more minimal.
Frequently check your work by screenshotting the URL.

Convert these 5 files to Tailwind, use one subagent per file

Only plan how to implement this. Do NOT write any code.

Find the commit that added this using git log, look at the whole
commit, then help me change this feature

AGENTS.md Files¶

Amp automatically reads AGENTS.md files for codebase guidance.

Locations (all auto-included)¶

Location	Purpose
`./AGENTS.md` & parent dirs	Project-specific guidance
Subtree `AGENTS.md`	Subproject conventions (included when reading files there)
`~/.config/amp/AGENTS.md`	Personal preferences, device-specific commands

What to Include¶

Build and test commands
Architecture overview
Code conventions and patterns
Internal APIs
Common mistakes to avoid

Advanced Features¶

# Reference other files with @-mentions

See @docs/architecture.md for system design
See @docs/\*.md for all documentation

# Glob patterns work

@src/\*_/_.test.ts

Granular guidance: Add YAML frontmatter to apply rules to specific file types:

---
globs:
  - "**/*.ts"
  - "**/*.tsx"
---
Never use the `any` type...

View active files: Run /agent-files (CLI) or hover context indicator (editor)

Context Management¶

The Golden Rules¶

Shorter is better—models perform worse with more context
Everything influences output—don't clutter with irrelevant content
Context has limits—conversations eventually can't continue

Tools for Managing Context¶

Action	CLI	Editor
Edit message	Navigate with ↑/↓, press `e`	Click message
Restore to point	Navigate, press `r`	Hover → Restore
Fork thread	Navigate, press `f`	Hover → Fork
Handoff	Automatic when context is full	—

Shell Mode (CLI only)¶

Execute commands and add output to context:

$ git diff --staged

Output is included in your next message.

Reference Other Threads¶

Extract the SQL query from T-abc123-...

Amp will pull only relevant information from the referenced thread.

Subagents & Tools¶

Oracle (GPT-5.2)¶

Deep reasoning advisor for:

Code reviews and architecture feedback
Debugging across multiple files
Planning complex implementations

Ask: "Consult the Oracle to review this authentication system"

Librarian¶

Multi-repository codebase expert for:

Understanding complex codebases
Exploring code relationships
Finding implementations across repos

Ask: "Ask the Librarian how authentication works in the Kubernetes codebase"

Task (Subagents)¶

Parallelize independent work:

Convert these 5 files to use Tailwind, use one subagent per file

Review Panel (VS Code)¶

Streamline code review for agent-generated changes:

Select commit range to review
Read AI summary for overview
Request a guided tour of changes
Open full file diffs with code navigation
Stage/commit with auto-generated message

Open via the icon in the Amp panel navigation bar.

Skills & MCP Servers¶

Skills¶

Install pre-built skills:

amp skill add ampcode/amp-contrib/tmux
amp skill list
amp skill remove tmux

MCP Servers¶

Add external tool servers:

"amp.mcpServers": {
  "playwright": {
    "command": "npx",
    "args": ["-y", "@playwright/mcp@latest", "--headless"]
  }
}

Permissions¶

Control what Amp can do:

"amp.permissions": [
  { "tool": "Bash", "matches": { "cmd": "*git commit*" }, "action": "ask" },
  { "tool": "Bash", "matches": { "cmd": "*rm -rf*" }, "action": "reject" }
]

CLI management:

amp permissions edit
amp permission test Bash --cmd 'git push'
amp permissions list

CLI Power Tips¶

# One-shot execution
amp -x "what files are markdown?"

# Pipe input
echo "what package manager?" | amp -x

# Auto-approve all (dangerous)
amp --dangerously-allow-all -x "replace 2024 with 2025 in README"

# Continue previous thread
amp threads continue --execute "now add 8 to that"

# JSON output for scripting
amp --execute "what is 3+5?" --stream-json

Quick Reference¶

Shortcut (CLI)	Action
`Ctrl+O`	Command palette
`↑/↓` or `Tab/Shift+Tab`	Navigate messages
`e`	Edit selected message
`r`	Restore to selected message
`f`	Fork at selected message
`$command`	Shell mode (add output to context)

Philosophy (from Amp's FIF)¶

No model switching—Amp optimizes for each model's strengths
No edit-by-edit approval—let the agent iterate; improve prompts instead
No hiding work—transparency helps you understand what's happening
No auto-compaction—quality degrades; keep threads short instead
No .ampignore—hiding files just makes the agent find workarounds

For more: ampcode.com/manual | Context Management Guide