Ultimate Architect Helper

Your comprehensive agent for software architecture guidance — covering system design, design patterns, code structure, and architectural decision-making across all technology stacks.

When to Use This Agent

Choose Ultimate Architect Helper when:

• Designing new systems or major features from scratch
• Evaluating architectural trade-offs between multiple approaches
• Applying design patterns (GoF, enterprise, distributed systems)
• Structuring codebases for scalability and maintainability
• Creating architecture documentation and decision records

Consider alternatives when:

• You need cloud-specific architecture — use a cloud architect agent
• You need infrastructure provisioning — use a Terraform or DevOps agent
• You need code implementation — use a language-specific developer agent

Quick Start

Copy
# .claude/agents/ultimate-architect.yml
name: Ultimate Architect Helper
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Comprehensive software architecture agent for system design, design patterns, and architectural decision-making

Example invocation:

claude "Design the architecture for a real-time collaborative document editor that supports 1000 concurrent users per document, with conflict resolution and offline editing"

Core Concepts

Architecture Levels

Level	Scope	Key Decisions
Enterprise	Organization-wide systems	Technology standards, integration patterns, governance
Solution	Multi-system solutions	Service boundaries, data ownership, communication patterns
Application	Single application	Layer structure, module design, dependency management
Code	Implementation details	Design patterns, data structures, algorithm choices

Design Pattern Categories

Creational       → Factory, Builder, Singleton, Prototype
Structural       → Adapter, Bridge, Composite, Decorator, Facade, Proxy
Behavioral       → Observer, Strategy, Command, State, Chain of Responsibility
Distributed      → Circuit Breaker, Saga, CQRS, Event Sourcing, Bulkhead
Integration      → API Gateway, Message Broker, Service Mesh, BFF
Data             → Repository, Unit of Work, Specification, Active Record

Configuration

Parameter	Description	Default
architecture_level	Focus level (enterprise, solution, application, code)	application
paradigm	Programming paradigm (oop, functional, hybrid)	hybrid
scale_target	Expected system scale	provided per project
quality_attributes	Priority NFRs (performance, security, maintainability)	balanced
output_type	Deliverable (design-doc, adr, diagram, code-structure)	design-doc

Best Practices

1. Choose the right architecture level for the problem. Don't design a microservices architecture for what should be a clean module structure within a monolith. Match the architectural sophistication to the actual complexity of the problem and the team's operational maturity.

2. Favor composition over inheritance in all designs. Whether at the class level or service level, composable components are more flexible than deep inheritance hierarchies. Design small, focused components that combine to create complex behavior.

3. Make dependencies flow inward (Dependency Inversion). High-level business logic should not depend on low-level infrastructure details. Define interfaces in the domain layer and implement them in the infrastructure layer. This keeps your core logic portable and testable.

4. Design for the current scale, architect for the next. Build what you need now, but make architectural decisions that don't prevent future scaling. A well-structured monolith can evolve into microservices; a poorly-structured microservices system is hard to fix.

5. Document the "why" behind every architectural decision. Capture the context, constraints, options considered, and reasoning in ADRs (Architecture Decision Records). The decision without its reasoning is useless to future developers who need to evaluate whether it still holds.

Common Issues

Architecture is too abstract to implement. Diagrams with labeled boxes and arrows don't guide developers. Include concrete details: folder structure, interface definitions, data flow with actual field names, and implementation steps. Good architecture documentation bridges the gap between concept and code.

Design patterns are applied where they add unnecessary complexity. Patterns solve specific problems — using Strategy pattern for code that will only ever have one strategy is over-engineering. Apply patterns when you can clearly articulate the problem they solve in your specific context.

Architecture documents are created once and never updated. Static architecture docs diverge from reality within months. Keep architectural decisions close to the code they govern (ADRs in the repo), generate diagrams from code when possible, and review architecture documentation during major refactors.