> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agents-squads.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Best Practices

> Essential patterns for effective agent systems

## Design Principles

### Start Simple, Scale Deliberately

> [!TIP]
>
> * Begin with single-agent solutions
> * Add complexity only when measurements prove it helps
> * Avoid premature framework adoption
> * Validate each addition delivers value

**1. Single Agent**

Start simple

**2. Add Memory**

Persistence when needed

**3. Add Tools**

Capabilities when needed

**4. Multiple Agents**

Scale when needed

**5. Squads**

Organize when needed

> [!NOTE]
>
> Only progress when current stage is insufficient.

### Optimize for Trust, Not Capability

The bottleneck is rarely what agents *can* do, but whether humans *trust* what they do.

* **Transparency** - Show reasoning, not just results
* **Auditability** - Log decisions and actions
* **Predictability** - Consistent behavior patterns
* **Reversibility** - Easy to undo mistakes

## Agent Design

### Prompt Engineering

**Do:**

```markdown theme={null}
# Clear objective
Analyze the API response times and identify bottlenecks.

# Specific constraints
- Focus on p95 latency
- Ignore requests < 100ms
- Output max 5 recommendations

# Structured output
Return JSON: {"bottlenecks": [...], "recommendations": [...]}
```

**Don't:**

```markdown theme={null}
Look at the performance stuff and let me know what you think
we should do to make things better. Be thorough!
```

### Single Responsibility

Each agent should do one thing well:

```
# Bad: Swiss Army Knife Agent
- Researches competitors
- Writes blog posts
- Deploys infrastructure
- Manages database

# Good: Focused Agents
- competitor-researcher → Research output
- content-writer → Blog posts
- deploy-agent → Infrastructure
- db-admin → Database
```

### Fail Gracefully

```markdown theme={null}
## Error Handling

If you encounter an error:
1. Log the specific error with context
2. Attempt one retry with adjusted parameters
3. If still failing, report clearly and stop
4. Never silently swallow errors
5. Never retry indefinitely
```

## System Architecture

### Memory Hierarchy

| Layer | Type | Purpose |
| - | - | - |
| Project config | Static | Project knowledge (CLAUDE.md) |
| Squad memory | Persistent | Cross-session state |
| Conversation | Session | Current task context |
| Working memory | Ephemeral | In-progress data |

### Communication Patterns

| Pattern | When to Use |
| - | - |
| Direct handoff | Agent A completes, passes to Agent B |
| Shared state file | Multiple agents read/write same doc |
| Message queue | Async, decoupled agents |
| Orchestrator | Central coordinator delegates tasks |

### Isolation Boundaries

> [card] Good Isolation
>
> * Agent A → `src/auth/` only
> * Agent B → `src/api/` only
> * Clear boundaries

> [card] Poor Isolation
>
> * All agents modify all files
> * No boundaries
> * Conflicts and overwrites

## Quality Assurance

### Review Before Merge

Even automated PRs need review:

```markdown theme={null}
## PR Checklist
- [ ] Changes match the issue scope
- [ ] No unintended side effects
- [ ] Tests pass (or added)
- [ ] No secrets committed
- [ ] Follows project conventions
```

### Validation Gates

**1. Syntax check**

Valid? Continue. Invalid? Reject.

**2. Tests**

Pass? Continue. Fail? Reject.

**3. Linter**

Clean? Continue. Issues? Auto-fix and retry.

**4. Review**

Human approval → Merge

### Feedback Loops

```bash theme={null}
# After each significant agent run
squads feedback add engineering

# Track quality over time
squads feedback stats
```

## Operational Excellence

### Monitoring

Track these metrics:

| Metric | Target | Red Flag |
| - | - | - |
| Task completion rate | > 90% | \< 70% |
| Token efficiency | > 80% | \< 50% |
| Error rate | \< 5% | > 15% |
| Avg task duration | \< 10 min | > 30 min |

### Cost Control

```markdown theme={null}
## Budget Rules
- Max $X per agent per day
- Alert at 80% of budget
- Hard stop at 100%
- Weekly cost review
```

### Incident Response

When agents fail:

1. **Stop** - Prevent further damage
2. **Assess** - What happened, what's affected
3. **Fix** - Resolve immediate issue
4. **Learn** - Update prompts/guardrails
5. **Document** - Record in squad memory

## Anti-Patterns

### Avoid These

> [!WARNING]
>
> **Over-Engineering**
>
> * Don't build orchestration for 2 agents
> * Don't add caching until you have latency problems
> * Don't create abstractions for one-time tasks
>
> **Under-Specification**
>
> * Don't say "make it better"
> * Don't assume agents know your preferences
> * Don't skip output format requirements
>
> **Blind Trust**
>
> * Don't auto-merge without review
> * Don't skip testing "because it's simple"
> * Don't ignore agent errors
>
> **Scope Creep**
>
> * Don't let agents add features unprompted
> * Don't refactor code you didn't touch
> * Don't improve things that aren't broken

## Checklists

### New Agent Checklist

> [!TIP]
>
> * [ ] Clear, single-purpose objective
> * [ ] Specific constraints and boundaries
> * [ ] Defined output format
> * [ ] Error handling instructions
> * [ ] Anti-slop rules included
> * [ ] Tested on representative inputs

### Production Readiness

> [!TIP]
>
> * [ ] Monitoring in place
> * [ ] Budget limits configured
> * [ ] Error alerting enabled
> * [ ] Rollback plan documented
> * [ ] Feedback loop established
> * [ ] Review process defined

### Daily Operations

> [!TIP]
>
> * [ ] Check `squads status` for issues
> * [ ] Review any failed tasks
> * [ ] Monitor cost trends
> * [ ] Update memory with learnings
> * [ ] Clear completed todos

## Related

> [card] [Context Optimization](https://docs.agents-squads.com/guides/context-optimization.md)
>
> Feed agents effectively

> [card] [Token Economics](https://docs.agents-squads.com/guides/token-economics.md)
>
> Control costs

> [card] [Parallelization](https://docs.agents-squads.com/guides/parallelization.md)
>
> Scale with parallel agents


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.