gh-jamesrochabrun-skills/skills/anthropic-architect/references/architectural_patterns.md

Architectural Patterns

Comprehensive catalog of proven Anthropic architecture patterns for common use cases.

Table of Contents

1. Skills-First Patterns
2. Agent-Based Patterns
3. Hybrid Patterns
4. SDK Custom Patterns
5. Progressive Disclosure Patterns
6. Security Patterns

---

Skills-First Patterns

Pattern 1: Domain Expert Skill

When to use:

• Specialized domain knowledge needed
• Team-wide expertise sharing
• Consistent application of patterns

Structure:

domain-expert-skill/
├── SKILL.md
├── references/
│   ├── core_concepts.md
│   ├── patterns/
│   │   ├── pattern_1.md
│   │   ├── pattern_2.md
│   │   └── pattern_3.md
│   ├── best_practices.md
│   └── examples/
│       ├── example_1.md
│       └── example_2.md
└── scripts/
    └── validate.sh

Example: Security Expert Skill

security-expert/
├── SKILL.md
├── references/
│   ├── owasp_top_10.md
│   ├── patterns/
│   │   ├── authentication.md
│   │   ├── authorization.md
│   │   ├── encryption.md
│   │   └── input_validation.md
│   ├── threat_models.md
│   └── examples/
│       ├── secure_api.md
│       └── secure_storage.md
└── scripts/
    └── security_audit.sh

Usage:

Using the security-expert skill, review this authentication flow
for vulnerabilities following OWASP guidelines.

Benefits:

• Centralized expertise
• Consistent security reviews
• Team knowledge sharing
• Progressive disclosure of security patterns

---

Pattern 2: Workflow Automation Skill

When to use:

• Repeatable multi-step workflows
• Team-wide process standardization
• Interactive script execution

Structure:

workflow-automation-skill/
├── SKILL.md
├── workflows/
│   ├── workflow_1.md
│   ├── workflow_2.md
│   └── workflow_3.md
├── scripts/
│   ├── step_1.sh
│   ├── step_2.sh
│   └── orchestrate.sh
└── templates/
    ├── template_1.md
    └── template_2.md

Example: Release Management Skill

release-management/
├── SKILL.md
├── workflows/
│   ├── version_bump.md
│   ├── changelog_generation.md
│   ├── deployment.md
│   └── rollback.md
├── scripts/
│   ├── bump_version.sh
│   ├── generate_changelog.sh
│   ├── deploy.sh
│   └── release.sh (orchestrator)
└── templates/
    ├── changelog_template.md
    └── release_notes.md

Usage:

Using the release-management skill, prepare a new release:
- Bump version to 2.1.0
- Generate changelog from commits
- Create release notes

Benefits:

• Standardized processes
• Reduced errors
• Faster execution
• Team consistency

---

Pattern 3: Progressive Disclosure Skill

When to use:

• Large knowledge base
• Context limits are concern
• Query-based information retrieval

Structure:

progressive-skill/
├── SKILL.md
├── query_tool.sh
├── index.md (high-level navigation)
├── expertise/
│   ├── by_task/
│   │   ├── task_1.md
│   │   └── task_2.md
│   ├── by_category/
│   │   ├── category_1.md
│   │   └── category_2.md
│   └── quick_reference/
│       └── cheat_sheet.md
└── examples/
    └── contextualized_examples.md

Example: API Design Skill

api-design-expert/
├── SKILL.md
├── query_expertise.sh
├── index.md
├── expertise/
│   ├── by_task/
│   │   ├── rest_api.md
│   │   ├── graphql.md
│   │   └── webhooks.md
│   ├── by_concern/
│   │   ├── authentication.md
│   │   ├── rate_limiting.md
│   │   ├── versioning.md
│   │   └── documentation.md
│   └── quick_reference/
│       ├── http_methods.md
│       └── status_codes.md
└── examples/
    └── real_world_apis.md

Usage:

Using api-design-expert, show me best practices for:
- RESTful resource design
- Authentication and authorization
- Rate limiting strategy

Query Flow:

1. Agent loads index.md (high-level)
2. Agent identifies relevant task: "rest_api.md"
3. Skill provides only REST API patterns
4. If auth needed, loads authentication.md
5. Progressive disclosure of information

Benefits:

• Minimal context usage
• Fast responses
• Scalable knowledge base
• Efficient token consumption

---

Agent-Based Patterns

Pattern 4: Multi-Phase Agent Pipeline

When to use:

• Complex workflows with distinct phases
• Different tool permissions per phase
• Isolated contexts beneficial

Structure:

Main Agent (orchestrator)
│
├── Phase 1: Explore Agent
│   Tools: [Read, Grep, Glob]
│   Context: Codebase exploration
│   Output: Insights, patterns, structure
│
├── Phase 2: Plan Agent
│   Tools: [TodoWrite]
│   Context: Insights from Phase 1
│   Output: Detailed plan
│
├── Phase 3: Execute Agent
│   Tools: [Read, Edit, Write]
│   Context: Plan + target files
│   Output: Code changes
│
└── Phase 4: Validate Agent
    Tools: [Bash, Read]
    Context: Changes + tests
    Output: Validation results

Example: Feature Implementation

Feature Implementation Pipeline

1. Explore Agent
   - Analyze existing codebase
   - Find related code patterns
   - Identify integration points
   → Output: Architecture analysis

2. Design Agent
   - Review analysis
   - Create detailed design
   - Plan file changes
   → Output: Implementation plan

3. Code Agent
   - Implement feature
   - Follow design plan
   - Write tests
   → Output: Code changes

4. Review Agent
   - Run tests
   - Check coverage
   - Validate functionality
   → Output: Pass/fail + feedback

5. Main Agent
   - Aggregate results
   - Report to user
   - Handle iterations

Usage:

Implement a new user authentication feature:
1. Analyze current auth system
2. Design JWT-based auth
3. Implement changes
4. Validate with tests

Benefits:

• Clear phase separation
• Minimal permissions per phase
• Isolated contexts (no pollution)
• Parallel execution possible
• Easy to debug and iterate

---

Pattern 5: Parallel Agent Execution

When to use:

• Independent tasks that can run simultaneously
• Large codebases or datasets
• Time-sensitive operations

Structure:

Coordinator Agent
│
├─┬─ Worker Agent 1: Task Subset 1
│ │
│ ├─ Worker Agent 2: Task Subset 2
│ │
│ ├─ Worker Agent 3: Task Subset 3
│ │
│ └─ Worker Agent 4: Task Subset 4
│
└── Aggregator Agent: Combine Results

Example: Codebase Analysis

Analysis Coordinator
│
├─┬─ Analyze Agent 1: /src/components/
│ │  → Component patterns
│ │
│ ├─ Analyze Agent 2: /src/services/
│ │  → Service patterns
│ │
│ ├─ Analyze Agent 3: /src/utils/
│ │  → Utility patterns
│ │
│ └─ Analyze Agent 4: /tests/
│    → Test coverage
│
└── Aggregator Agent
    → Combined analysis report

Usage:

Analyze entire codebase for:
- Code patterns
- Test coverage
- Performance issues
- Security vulnerabilities

Execute in parallel for speed.

Benefits:

• Massive speedup (4x with 4 agents)
• Independent execution
• Resource optimization
• Scalable to large codebases

---

Pattern 6: Specialist Agent Team

When to use:

• Different expertise areas needed
• Collaborative task execution
• Review and validation workflows

Structure:

Project Lead Agent (orchestrator)
│
├── Frontend Specialist Agent
│   Expertise: UI/UX, components, accessibility
│   Tools: Frontend-specific
│
├── Backend Specialist Agent
│   Expertise: APIs, databases, services
│   Tools: Backend-specific
│
├── DevOps Specialist Agent
│   Expertise: CI/CD, deployment, infrastructure
│   Tools: DevOps-specific
│
└── QA Specialist Agent
    Expertise: Testing, validation, quality
    Tools: Testing-specific

Example: Full-Stack Feature

Feature: Add user profile page

Project Lead Agent
│
├── Frontend Agent
│   - Create profile component
│   - Add routing
│   - Implement responsive design
│   Load: frontend-designer skill
│
├── Backend Agent
│   - Create profile API endpoint
│   - Add database queries
│   - Implement validation
│   Load: api-design-expert skill
│
├── DevOps Agent
│   - Update deployment config
│   - Add environment variables
│   - Configure monitoring
│   Load: devops-expert skill
│
└── QA Agent
    - Write integration tests
    - Validate end-to-end flow
    - Check accessibility
    Load: qa-test-planner skill

Usage:

Implement user profile feature across the stack:
- Frontend: Profile page with edit capability
- Backend: CRUD API for profile data
- DevOps: Deploy to staging
- QA: Full test coverage

Benefits:

• Specialized expertise
• Parallel execution
• Skills loading per specialist
• Clear ownership
• Comprehensive coverage

---

Hybrid Patterns

Pattern 7: Agents + Skills Hybrid

When to use:

• Complex workflows needing domain expertise
• Reusable knowledge + autonomous execution
• Best of both approaches

Structure:

Agent Workflow
│
├── Explore Agent
│   Loads: codebase-analysis-skill
│   Expertise: Pattern recognition
│   Tools: [Read, Grep, Glob]
│
├── Plan Agent
│   Loads: architecture-patterns-skill
│   Expertise: Design patterns
│   Tools: [TodoWrite]
│
└── Execute Agent
    Loads: coding-standards-skill
    Expertise: Team conventions
    Tools: [Read, Edit, Write]

Example: Refactoring Pipeline

Refactoring Workflow

1. Analysis Agent
   Load: code-quality-skill
   - Identify code smells
   - Find duplication
   - Analyze complexity
   Use skill's: anti-patterns reference

2. Planning Agent
   Load: refactoring-patterns-skill
   - Choose refactoring patterns
   - Plan step-by-step changes
   - Estimate risk
   Use skill's: safe refactoring strategies

3. Execution Agent
   Load: team-coding-standards-skill
   - Apply refactorings
   - Follow team style
   - Maintain tests
   Use skill's: style guide and examples

4. Validation Agent
   Load: testing-strategies-skill
   - Run test suite
   - Check coverage
   - Verify behavior
   Use skill's: test validation patterns

Usage:

Refactor the UserService class:
- Load relevant skills for expertise
- Use agents for autonomous execution
- Progressive disclosure of skill knowledge
- Isolated contexts per phase

Benefits:

• Reusable expertise (skills)
• Autonomous execution (agents)
• Progressive disclosure
• Isolated contexts
• Best of both worlds

---

Pattern 8: Prompts + Skills Fallback

When to use:

• Start simple, escalate complexity
• Most tasks simple, some complex
• Cost optimization

Structure:

Task Router
│
├── Simple task? → Direct Prompt
│
├── Needs expertise? → Load Skill
│   └── Still simple? → Skill + Prompt
│   └── Complex? → Skill + Agent
│
└── Very complex? → Agents + Skills

Example: Code Review System

Code Review Router

1. Check complexity
   - Small PR (< 50 lines)? → Direct Prompt
     "Review this PR for basic issues"

   - Medium PR (50-500 lines)? → Load Skill
     Using code-review-skill, review this PR
     Skill provides: checklist, patterns

   - Large PR (> 500 lines)? → Agent + Skill
     Review Agent loads code-review-skill
     - Explore codebase context
     - Apply review checklist
     - Generate comprehensive review

Benefits:

• Cost-effective (simple → cheap)
• Scalable (complex → powerful)
• Flexible (adapts to task)
• Progressive enhancement

---

SDK Custom Patterns

Pattern 9: Custom Tool Integration

When to use:

• Integration with proprietary systems
• Custom tools needed
• Domain-specific operations

Structure:

import { Agent, Tool } from 'claude-agent-sdk';

// Define custom tool
const customTool: Tool = {
  name: 'custom-tool',
  description: 'Interacts with proprietary system',
  execute: async (params) => {
    // Custom implementation
    return await proprietarySystem.call(params);
  }
};

// Create agent with custom tool
const agent = new Agent({
  tools: [customTool, ...standardTools],
  systemPrompt: 'You are an expert with custom-system access'
});

Example: CRM Integration Agent

// Custom CRM tools
const getCRMData: Tool = {
  name: 'get-crm-data',
  description: 'Fetch customer data from CRM',
  execute: async ({ customerId }) => {
    return await crmAPI.getCustomer(customerId);
  }
};

const updateCRMData: Tool = {
  name: 'update-crm-data',
  description: 'Update customer data in CRM',
  execute: async ({ customerId, data }) => {
    return await crmAPI.updateCustomer(customerId, data);
  }
};

// Agent with CRM access
const crmAgent = new Agent({
  tools: [getCRMData, updateCRMData],
  systemPrompt: `You are a CRM assistant with access to customer data.
    Help users query and update customer information.`
});

Usage:

const response = await crmAgent.run({
  task: 'Get customer data for customer ID 12345 and update their email'
});

Benefits:

• Direct system integration
• Custom business logic
• Proprietary data access
• Fine-grained control

---

Pattern 10: Custom Feedback Loop

When to use:

• Specific workflow requirements
• Unique validation logic
• Custom iteration patterns

Structure:

const customWorkflow = async (task: Task) => {
  let result;
  let iterations = 0;
  const maxIterations = 5;

  while (iterations < maxIterations) {
    // Step 1: Generate
    result = await agent.generate(task);

    // Step 2: Custom validation
    const validation = await customValidator(result);

    // Step 3: Custom decision
    if (validation.passed) {
      break; // Success
    }

    // Step 4: Custom feedback
    task = customFeedback(task, validation.issues);
    iterations++;
  }

  return result;
};

Example: Code Generation with Custom Linter

const codeGenerationWorkflow = async (spec: Specification) => {
  let code;
  let attempt = 0;

  while (attempt < 3) {
    // Generate code
    code = await codeAgent.generate(spec);

    // Custom linter validation
    const lintResults = await customLinter.check(code);

    if (lintResults.errors.length === 0) {
      // Passed linting
      break;
    }

    // Custom feedback loop
    spec = addLintingFeedback(spec, lintResults.errors);
    attempt++;
  }

  // Custom post-processing
  code = await customFormatter.format(code);

  return code;
};

Benefits:

• Custom validation logic
• Specific iteration patterns
• Business rule enforcement
• Unique workflows

---

Progressive Disclosure Patterns

Pattern 11: Query-Based Disclosure

When to use:

• Large knowledge bases
• Context optimization critical
• Task-specific information needed

Structure:

skill/
├── SKILL.md (high-level overview)
├── query.sh (interactive query tool)
├── index.md (navigation)
└── content/
    ├── topic_1/
    │   ├── overview.md (loaded first)
    │   ├── detailed.md (on demand)
    │   └── examples.md (when requested)
    └── topic_2/
        ├── overview.md
        ├── detailed.md
        └── examples.md

Query Pattern:

# User queries skill
"Using skill, how do I implement authentication?"

# Skill loading strategy
1. Load: index.md (< 500 tokens)
   → Find relevant topic: authentication
2. Load: authentication/overview.md (< 1000 tokens)
   → Provides high-level guidance
3. If user needs more:
   Load: authentication/detailed.md
   → In-depth patterns
4. If user wants examples:
   Load: authentication/examples.md
   → Real code samples

Benefits:

• Minimal initial context
• Load more as needed
• Efficient token usage
• Fast initial response

---

Pattern 12: Hierarchical Disclosure

When to use:

• Complex topics with depth
• Progressive learning needed
• Multiple expertise levels

Structure:

skill/
├── level_1_basics/
│   └── (fundamental concepts)
├── level_2_intermediate/
│   └── (common patterns)
├── level_3_advanced/
│   └── (complex techniques)
└── level_4_expert/
    └── (edge cases, optimization)

Disclosure Flow:

User: "Help me with caching"

Skill responds:
├─ Level 1: Basic caching concepts
│  User: "I know basics, show me patterns"
│
├─ Level 2: Common caching patterns
│  User: "Show me advanced optimization"
│
├─ Level 3: Cache optimization techniques
│  User: "What about distributed caching?"
│
└─ Level 4: Distributed caching strategies

Benefits:

• Tailored to user expertise
• Prevents overwhelming
• Progressive depth
• Efficient learning

---

Security Patterns

Pattern 13: Allowlist Security Pattern

When to use:

• Sensitive operations
• Controlled tool access
• Security-critical applications

Structure:

const secureAgent = new Agent({
  tools: allowlistOnly([
    'Read',      // Safe: read-only
    'Grep',      // Safe: read-only
    'Glob',      // Safe: read-only
  ]),
  denylist: [
    'rm -rf',
    'sudo',
    'curl',      // Could leak data
    'wget',      // Could leak data
  ],
  confirmations: [
    'git push',
    'deployment',
    'data deletion'
  ]
});

Example: Production Agent

const productionAgent = new Agent({
  name: 'production-agent',

  // Minimal permissions
  tools: [
    'Read',          // View configs
    'Grep',          // Search logs
  ],

  // Block dangerous operations
  denylist: [
    'rm',
    'delete',
    'drop',
    'truncate',
    'sudo',
    'chmod',
    'exec'
  ],

  // Require confirmation
  confirmations: [
    'restart service',
    'change config',
    'modify database'
  ],

  // Audit all operations
  audit: {
    enabled: true,
    logLevel: 'verbose',
    destination: 'security-log'
  }
});

Benefits:

• Deny-all default
• Explicit permissions
• Confirmations for sensitive ops
• Full audit trail

---

Pattern 14: Defense in Depth

When to use:

• High security requirements
• Multiple security layers needed
• Critical systems

Structure:

Security Layers:

Layer 1: Tool Allowlist
  → Only approved tools

Layer 2: Command Validation
  → Validate command safety

Layer 3: Confirmation Required
  → Human approval for sensitive ops

Layer 4: Sandbox Execution
  → Isolated environment

Layer 5: Audit Logging
  → Full operation trail

Layer 6: Rollback Capability
  → Undo mechanism

Example: Financial System Agent

const financialAgent = new Agent({
  // Layer 1: Tool Allowlist
  tools: allowlistOnly(['Read', 'Grep']),

  // Layer 2: Command Validation
  preExecute: async (command) => {
    return await securityValidator.validate(command);
  },

  // Layer 3: Confirmation Required
  confirmations: 'all',

  // Layer 4: Sandbox
  sandbox: {
    enabled: true,
    isolated: true,
    networkBlocked: true
  },

  // Layer 5: Audit
  audit: {
    enabled: true,
    level: 'detailed',
    retention: '7years',
    immutable: true
  },

  // Layer 6: Rollback
  rollback: {
    enabled: true,
    autoSnapshot: true,
    quickRevert: true
  }
});

Benefits:

• Multiple security layers
• Defense against various threats
• Compliance ready
• Maximum security

---

Summary

Choose patterns based on your requirements:

Simple Tasks: Direct Prompts Reusable Expertise: Skills (Patterns 1-3) Complex Workflows: Agents (Patterns 4-6) Best of Both: Hybrid (Patterns 7-8) Custom Needs: SDK (Patterns 9-10) Large Knowledge: Progressive Disclosure (Patterns 11-12) Security Critical: Security Patterns (Patterns 13-14)

Key Principle: Start simple, add complexity only when needed.