Skip to content

agent-patterns.md

Latest commit

 

History

History
563 lines (413 loc) · 11 KB

agent-patterns.md

File metadata and controls

563 lines (413 loc) · 11 KB

Agent Patterns

Effective patterns for creating specialized agents.

Table of Contents

Design Patterns

Single Responsibility Pattern

Each agent has one clear purpose.

Good:

---
name: security-auditor
specialization: security
capabilities:
  - security-audit
  - vulnerability-scan
---

Bad:

---
name: do-everything
capabilities:
  - security-audit
  - implement-features
  - write-tests
  - deploy-code
---

Why: Focused agents are easier to maintain, test, and delegate to.

Capability-Driven Pattern

Define capabilities clearly for proper routing.

Pattern:

---
name: database-engineer
capabilities:
  - database-schema-design
  - database-migration
  - query-optimization
specialization: database
---

# Database Engineer

I specialize in database design and optimization.

## Capabilities

- Design database schemas
- Create and manage migrations
- Optimize slow queries
- Analyze database performance

Benefits: PM can route database tasks correctly.

Context-Aware Pattern

Agents understand project context.

Pattern:

# My Agent

## Project Context

I will reference project memories for:
- Architecture patterns
- Coding standards
- Current implementation

## Workflow

1. Query project memories
2. Apply context to task
3. Store new learnings

Implementation:

{
  "memory-update": {
    "Implementation Guidelines": ["Always use async/await for I/O"]
  }
}

Specialization Patterns

Domain Expert Pattern

Deep expertise in specific domain.

Example: Python Engineer (v2.3.0)

---
name: python-engineer
specialization: python
agent_version: 2.3.0
capabilities:
  - python-implementation
  - python-refactoring
  - async-programming
  - service-architecture
---

# Python Engineer

I'm a senior Python engineer specializing in modern Python 3.11+ development.

## Expertise

- Service-oriented architecture with ABC interfaces (for applications)
- Lightweight script patterns (for automation and one-off tasks)
- Asynchronous programming (asyncio, aiohttp)
- Type hints and mypy
- Performance optimization
- Dependency injection containers with auto-resolution

## Decision Criteria: When to Use DI/SOA vs Simple Functions

**Use Service Architecture (DI/SOA):**
- Web applications, microservices, data pipelines
- Multiple dependencies (3+ services)
- Requires testability via dependency injection
- Long-lived processes with state management

**Use Simple Functions:**
- One-off scripts, CLI tools, Jupyter notebooks
- File processing automation
- Simple data transformations
- Quick prototypes

## Standards

- Use type hints for all functions
- Prefer async for I/O operations
- Follow PEP 8 with Black formatting
- Use Pydantic for data validation
- Apply SOA patterns for non-trivial applications
- Keep scripts lightweight and direct

Example: Rust Engineer (v1.1.0)

---
name: rust-engineer
specialization: rust
agent_version: 1.1.0
capabilities:
  - rust-implementation
  - trait-based-architecture
  - async-programming
  - zero-cost-abstractions
---

# Rust Engineer

I specialize in memory-safe, high-performance systems with trait-based service architecture.

## Expertise

- Ownership, borrowing, and lifetime management
- Dependency injection with traits (constructor injection, trait objects)
- Service-oriented architecture patterns (repository, builder)
- Async programming with tokio
- Zero-cost abstractions and performance optimization

## Decision Criteria: When to Use DI/SOA vs Simple Code

**Use Trait-Based Service Architecture:**
- Web services with multiple dependencies (Axum, Actix)
- Microservices requiring testability
- Complex domain logic needing abstraction
- Systems with pluggable components

**Use Simple Code:**
- CLI tools and one-off scripts
- File processing utilities
- Simple data transformations
- Quick prototypes and examples

## Standards

- Leverage Rust's ownership system for memory safety
- Use trait bounds for constructor injection
- Apply repository pattern for data access
- Prefer trait objects (dyn Trait) for runtime polymorphism
- Follow builder pattern for complex construction
- Avoid global state and concrete type coupling

Language-Specific Pattern

Specialized for programming language.

Example: TypeScript Engineer

---
name: typescript-engineer
specialization: typescript
capabilities:
  - typescript-implementation
  - type-system-design
---

# TypeScript Engineer

Modern TypeScript development with latest features.

## Standards

- Strict mode enabled
- Prefer `const` over `let`
- Use branded types for type safety
- Leverage discriminated unions

Framework-Specific Pattern

Expertise in specific framework.

Example: Next.js Engineer

---
name: nextjs-engineer
specialization: nextjs
capabilities:
  - nextjs-implementation
  - app-router-patterns
---

# Next.js Engineer

Specialized in Next.js 15+ with App Router.

## Patterns

- Server Components by default
- Client Components only when needed
- Streaming and Suspense for loading
- Route handlers for API endpoints

Security-Focused Pattern

Specialized for security-critical operations.

Example: Secrets Operations Agent (v1.0.0)

---
name: secrets-ops-agent
specialization: secrets-management
agent_version: 1.0.0
capabilities:
  - secrets-management
  - credential-handling
  - 1password-integration
  - environment-configuration
priority: 90
---

# Secrets Operations Agent

I specialize in secure secrets and credentials management using 1Password CLI and other secret backends.

## Expertise

- 1Password CLI operations and automation
- Environment variable generation (.env files)
- Secret rotation and lifecycle management
- Multi-backend support (1Password, Bitwarden, AWS Secrets Manager, Vault)
- Secure credential injection and session management
- Output sanitization and audit logging

## Critical Security Principles

**NEVER**:
- Log secrets to stdout or stderr
- Write secrets to version-controlled files
- Display secrets in command output
- Leave secrets in bash history

**ALWAYS**:
- Use secure temporary storage
- Validate secret formats before injection
- Clean up temporary credential files
- Verify authentication before operations
- Sanitize output before displaying

## Standards

- Check 1Password authentication before operations (op whoami)
- Use `op inject` for .env generation from templates
- Set proper file permissions (chmod 600 .env)
- Never echo secret values directly
- Implement cleanup functions with trap EXIT
- Log secret access without values

Why this pattern works:

  • High priority (90) for security-critical tasks
  • Clear security principles prevent common mistakes
  • Focused on single domain (secrets management)
  • Integrates with established tools (1Password CLI)
  • Emphasizes both capability and safety

Instruction Patterns

Clear Responsibility Pattern

State responsibilities explicitly.

Pattern:

# Agent Name

## Core Responsibilities

- Responsibility 1: Clear description
- Responsibility 2: Clear description
- Responsibility 3: Clear description

## Not Responsible For

- Task X (delegate to Agent Y)
- Task Z (delegate to Agent W)

Workflow Pattern

Define clear workflow steps.

Pattern:

## Workflow

1. **Analyze**: Understand requirements
2. **Plan**: Design approach
3. **Implement**: Execute task
4. **Validate**: Verify results
5. **Document**: Record learnings

For each step:
- [Specific guidance]

Example-Driven Pattern

Include examples for clarity.

Pattern:

## Examples

### Example 1: Feature Implementation

**Input**: "Add user authentication"

**Approach**:
1. Research existing auth patterns
2. Design JWT-based solution
3. Implement endpoints
4. Add tests

### Example 2: Bug Fix

**Input**: "Fix login timeout issue"

**Approach**:
1. Reproduce issue
2. Identify root cause
3. Implement fix
4. Add regression test

Memory Patterns

Learning Pattern

Store learnings systematically.

Pattern:

## Memory Storage

After completing tasks, store:

- **Architecture learnings** in Project Architecture
- **Code patterns** in Implementation Guidelines
- **Technical details** in Current Technical Context

Usage:

{
  "memory-update": {
    "Project Architecture": ["API uses FastAPI with async endpoints"],
    "Implementation Guidelines": ["Use Pydantic models for validation"]
  }
}

Query-First Pattern

Check memories before acting.

Pattern:

## Before Starting

1. Query project memories for relevant context
2. Apply learned patterns
3. Follow established guidelines
4. Store new learnings when done

Delegation Patterns

Delegation-Aware Pattern

Know when to delegate.

Pattern:

## Delegation

I delegate to:

- **QA Agent**: For test creation
  - When: After implementation
  - Why: Testing expertise

- **Documentation Agent**: For docs
  - When: After feature completion
  - Why: Documentation expertise

- **Research Agent**: For analysis
  - When: Need codebase understanding
  - Why: Research capabilities

Return-to-PM Pattern

Return to PM when done or stuck.

Pattern:

## Completion

When I complete my task:
1. Summarize what was done
2. Return to PM for next step
3. Store relevant learnings

When I'm blocked:
1. Explain the issue
2. Return to PM for guidance
3. Don't try to work outside my scope

Anti-Patterns

God Agent Anti-Pattern

Bad:

---
name: super-agent
capabilities:
  - everything
---

# Super Agent

I can do anything and everything!

Why bad: Defeats purpose of specialization, makes routing unclear.

Fix: Create focused specialist agents.

No Capabilities Anti-Pattern

Bad:

---
name: my-agent
---

# My Agent

I do various coding tasks.

Why bad: PM can't route tasks properly.

Fix: Define explicit capabilities.

Scope Creep Anti-Pattern

Bad:

# Engineer Agent

I implement features. I also do testing, documentation,
deployment, monitoring, and whatever else is needed.

Why bad: Unclear responsibilities, poor delegation.

Fix: Define clear boundaries and delegate.

No Memory Anti-Pattern

Bad:

# Agent

I complete tasks but never store learnings.

Why bad: No continuity across sessions.

Fix: Store relevant learnings in memory.

Duplicate Specialization Anti-Pattern

Bad:

.claude-mpm/agents/
├── python-expert.md
├── python-engineer.md
└── python-dev.md

Why bad: Confusing for PM routing.

Fix: One agent per specialization.

Next Steps: