> ## 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 * Begin with single-agent solutions * Add complexity only when measurements prove it helps * Avoid premature framework adoption * Validate each addition delivers value Start simple Persistence when needed Capabilities when needed Scale when needed Organize when needed 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 * Agent A → `src/auth/` only * Agent B → `src/api/` only * Clear boundaries * 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 Valid? Continue. Invalid? Reject. Pass? Continue. Fail? Reject. Clean? Continue. Issues? Auto-fix and retry. 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 **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 * [ ] Clear, single-purpose objective * [ ] Specific constraints and boundaries * [ ] Defined output format * [ ] Error handling instructions * [ ] Anti-slop rules included * [ ] Tested on representative inputs ### Production Readiness * [ ] Monitoring in place * [ ] Budget limits configured * [ ] Error alerting enabled * [ ] Rollback plan documented * [ ] Feedback loop established * [ ] Review process defined ### Daily Operations * [ ] Check `squads status` for issues * [ ] Review any failed tasks * [ ] Monitor cost trends * [ ] Update memory with learnings * [ ] Clear completed todos ## Related Feed agents effectively Control costs Scale with parallel agents