Architect Agent Helper

Your assistant agent for software architecture tasks — helping design system components, evaluate patterns, create architecture documentation, and guide implementation decisions for projects of any scale.

When to Use This Agent

Choose Architect Agent Helper when:

• Breaking down feature requirements into architectural components
• Choosing between implementation patterns for a specific scenario
• Creating architecture diagrams and design documentation
• Reviewing pull requests for architectural consistency
• Planning incremental migration paths between architectures

Consider alternatives when:

• You need cloud-specific architecture (AWS, Azure, GCP) — use a cloud architect agent
• You need deep system design for distributed systems — use a senior architect agent
• You need code implementation rather than design — use a developer agent

Quick Start

Copy
# .claude/agents/architect-helper.yml
name: Architect Agent Helper
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Architecture assistant for component design, pattern evaluation, and implementation planning

Example invocation:

claude "Help me design the component structure for a notification system — it needs to support email, SMS, push notifications, and in-app notifications with user preference management"

Core Concepts

Architecture Decision Process

Step	Activity	Output
Context	Understand requirements and constraints	Requirements document
Options	Identify 2-3 viable approaches	Options analysis
Evaluate	Compare against quality attributes	Trade-off matrix
Decide	Select approach with rationale	ADR (Architecture Decision Record)
Plan	Create implementation roadmap	Sprint-ready tasks

Component Design Patterns

Layered Architecture
  ├── Presentation → UI components, API controllers
  ├── Application  → Use cases, orchestration
  ├── Domain       → Business logic, entities
  └── Infrastructure → Database, external services

Hexagonal Architecture
  ├── Ports    → Interfaces (inbound + outbound)
  ├── Adapters → Implementations (web, DB, messaging)
  └── Core     → Domain logic (framework-independent)

Feature-Based Structure
  ├── features/notifications/
  │   ├── api/          → Endpoints
  │   ├── services/     → Business logic
  │   ├── models/       → Data models
  │   └── tests/        → Feature tests
  └── shared/           → Cross-cutting concerns

Configuration

Parameter	Description	Default
architecture_style	Preferred pattern (layered, hexagonal, feature-based)	feature-based
output_format	Documentation format (adr, design-doc, diagram)	design-doc
complexity_level	Design depth (simple, moderate, enterprise)	moderate
framework	Target framework context	auto-detect
team_size	Team size for complexity calibration	auto-detect

Best Practices

1. Start with the user's journey, not the system's components. Map how users interact with the feature before designing internal components. The best architectures emerge from understanding user workflows, not from organizing code into aesthetically pleasing layers.

2. Keep the number of components proportional to the team size. A team of 3 doesn't need 15 microservices. Aim for a structure where each developer can understand and contribute to any part of the system. Add organizational boundaries only when team size demands it.

3. Define component interfaces before implementing internals. Agree on what each component exposes (APIs, events, shared types) before writing internal logic. This enables parallel development and makes components independently testable.

4. Use ADRs to capture decisions, not just the chosen option. Record what you decided, what alternatives you considered, and why you chose this path. The rejected alternatives are often more valuable than the chosen one — they prevent future developers from re-evaluating the same options.

5. Plan for incremental delivery, not big-bang releases. Design your architecture so that features can be built and shipped incrementally. If a design requires all components to be complete before anything works, it's too coupled.

Common Issues

Architecture is over-designed for the current project scale. Adding abstraction layers, event buses, and service meshes for a small team building a CRUD app creates unnecessary complexity. Match the architecture to the actual complexity of the domain and the operational capacity of the team.

Components have unclear ownership boundaries. When multiple components share responsibilities, changes require coordination across owners. Define clear ownership: each component has one team or developer responsible, with explicit interfaces for cross-component communication.

Architecture decisions are made in meetings but not recorded. Without written ADRs, the same decisions get debated repeatedly. Store ADRs in the repository, reference them in pull requests, and review them during onboarding. Decisions that exist only in people's memories are decisions that will be revisited.