Back to Generator

Agent Best Practices

A guide to creating effective and maintainable Claude Code agents.

What is an Agent?

An agent is a specialized configuration that tells Claude Code how to behave in specific contexts. Think of it as a persona with defined expertise, boundaries, and workflows. Agents help Claude provide more focused, consistent, and relevant assistance.

Anatomy of an Agent

Frontmatter

Metadata including name, description, category, color, and model. These help organize and identify your agents.

Triggers

Define when this agent should activate. Be specific about file types, directories, or task contexts.

Behavioral Mindset

Describe the agent's personality and approach. Should it be cautious or bold? Verbose or concise?

Focus Areas

List the domains of expertise with descriptions. This helps Claude understand what knowledge to prioritize.

Key Actions

Step-by-step workflow actions the agent should follow when completing tasks.

Outputs

What the agent produces — code, documentation, diagrams, etc.

Boundaries

Define what the agent will and will not do. This prevents scope creep and keeps responses focused.

Tech Stack

Specify the technologies, frameworks, and tools the agent should be familiar with.

Best Practices

  • 1.
    Be Specific

    Vague instructions lead to vague results. Define clear triggers, boundaries, and expected outputs.

  • 2.
    Keep It Focused

    One agent, one purpose. If you need multiple capabilities, create multiple agents.

  • 3.
    Define Boundaries

    Tell the agent what NOT to do. This prevents unwanted behavior and scope creep.

  • 4.
    Use Consistent Naming

    Choose descriptive, lowercase, kebab-case names like backend-architect or security-auditor.

  • 5.
    Iterate and Refine

    Start simple, test with real tasks, and refine based on results. Agents improve over time.

  • 6.
    Choose the Right Model

    Use Opus for complex reasoning, Sonnet for balanced tasks, and Haiku for quick, simple operations.

Example Agent

---
name: backend-architect
description: Design scalable backend systems
category: engineering
color: blue
model: sonnet
---

# Backend Architect

## Triggers

- Working in /api or /server directories
- Discussing database design
- Building REST or GraphQL APIs

## Behavioral Mindset

Think like a senior engineer who values
reliability, scalability, and maintainability.
Always consider edge cases and failure modes.

## Focus Areas

- **API Design**: RESTful principles, versioning
- **Database**: Schema design, optimization
- **Security**: Authentication, authorization

## Boundaries

**Will:**
- Design database schemas
- Review API endpoints
- Suggest caching strategies

**Will Not:**
- Implement frontend code
- Make deployment decisions
- Modify production data