Architect Software Helper

A general-purpose software architecture agent that helps design, evaluate, and document software systems, covering design patterns, architectural styles, component design, and technical decision-making for applications across all scales.

When to Use This Agent

Choose Software Helper when:

• Designing new software systems from requirements
• Evaluating architectural trade-offs for technical decisions
• Documenting existing system architecture for team knowledge sharing
• Refactoring legacy systems toward modern architectural patterns
• Reviewing architecture proposals for completeness and risk

Consider alternatives when:

• Doing specific architecture reviews for production readiness (use a system architecture partner)
• Writing code without architectural decisions (use a development agent)
• Building infrastructure without application design (use a DevOps agent)

Quick Start

Copy
# .claude/agents/architect-software-helper.yml
name: Software Architect Helper
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a software architect. Help design, evaluate, and
  document software systems. Consider trade-offs carefully,
  recommend appropriate design patterns, and ensure architectures
  are maintainable, scalable, and aligned with team capabilities.

Example invocation:

Copy
claude --agent architect-software-helper "Design the architecture
  for a multi-tenant SaaS application with tenant isolation,
  shared infrastructure, and per-tenant customization capabilities"

Core Concepts

Architectural Styles Comparison

Style	Best For	Trade-offs
Monolith	Small teams, MVPs, simple domains	Simple but hard to scale independently
Modular Monolith	Medium teams, bounded contexts	Modular but single deployment unit
Microservices	Large teams, independent scaling	Flexible but operationally complex
Event-Driven	Async workflows, decoupled systems	Scalable but harder to debug
Serverless	Sporadic traffic, rapid prototyping	Cost-efficient but vendor lock-in
CQRS	Read/write asymmetry, complex domains	Optimized but increased complexity

Design Pattern Selection

Creational:  Factory → when object creation is complex
             Builder → when objects have many optional params
             Singleton → when exactly one instance is needed (use sparingly)

Structural:  Adapter → when integrating incompatible interfaces
             Facade → when simplifying a complex subsystem
             Proxy → when adding access control or caching

Behavioral:  Strategy → when algorithms are interchangeable
             Observer → when objects need event notifications
             Command → when operations need undo/queue/log

Architecture Decision Template

Copy
## Decision: {Title}

**Context**: What situation motivates this decision?
**Options**:
  1. {Option A} — {pros} / {cons}
  2. {Option B} — {pros} / {cons}
  3. {Option C} — {pros} / {cons}

**Decision**: {Chosen option} because {rationale}
**Consequences**: {What changes as a result}
**Revisit When**: {Trigger for reconsidering this decision}

Configuration

Parameter	Description	Default
diagram_style	Architecture diagram format	ASCII/Mermaid
detail_level	Design document detail depth	Moderate
pattern_preference	Preferred architectural patterns	Context-dependent
tech_constraints	Technology stack constraints	None
team_size	Team size for architecture recommendations	Not specified
scale_requirements	Expected scale for design decisions	Not specified
documentation_format	Architecture doc output format	Markdown

Best Practices

1. Match architecture complexity to team size and domain complexity. A team of three developers building an MVP should not adopt microservices. A team of fifty building a complex domain should not try to maintain a single monolith. Start with the simplest architecture that supports your current needs, and evolve complexity as the team, codebase, and requirements grow. Premature complexity is the most common architectural mistake.

2. Define clear module boundaries before choosing an architectural style. Whether you build a monolith or microservices, the boundaries between components matter more than how they're deployed. Use domain-driven design to identify bounded contexts. Each context should have a clear API, own its data, and communicate through well-defined interfaces. Good boundaries enable architectural evolution; bad boundaries create distributed monoliths.

3. Document decisions when they're made, not after. Architecture decisions lose context rapidly. A week after choosing PostgreSQL over MongoDB, you'll forget the specific query patterns and consistency requirements that drove the decision. Write a brief ADR immediately: context, options considered, decision, and consequences. Future team members (including future you) will thank you.

4. Design for the team you have, not the team you want. An architecture requiring Kubernetes expertise is wrong for a team of JavaScript developers. Consider your team's existing skills, learning capacity, and operational capabilities when choosing patterns and technologies. The best architecture is one your team can build, deploy, debug, and maintain without heroic effort.

5. Plan for change by isolating what's likely to change. Identify the parts of the system most likely to change (business rules, third-party integrations, UI frameworks) and isolate them behind stable interfaces. When the payment provider changes, only the payment adapter should need modification. When the frontend framework changes, the API should remain unchanged. Isolation of change is the primary purpose of good architecture.

Common Issues

Architecture is over-engineered for current requirements. Teams often build for imagined future scale rather than current needs. A system handling 100 requests per day doesn't need Kafka, Kubernetes, and a service mesh. Start simple, measure actual bottlenecks, and add complexity only when real problems require it. The cost of premature complexity is ongoing maintenance overhead for capabilities nobody uses.

Distributed system has all the complexity of microservices but none of the benefits. This "distributed monolith" pattern occurs when services share databases, deploy together, or can't function independently. If you can't deploy, scale, or fail one service independently of others, you don't have microservices—you have a monolith with network calls. Either strengthen service boundaries or consolidate back to a monolith.

Architecture knowledge is concentrated in one or two people. This bus factor risk threatens the entire system. Document architectural decisions with ADRs, create architecture overview diagrams, and conduct regular architecture walkthroughs with the full team. Rotate architectural responsibilities so multiple people understand the design rationale. The architecture should be understandable by any experienced developer reading the documentation, not just by its original authors.