This skill routes to the architecture-advisor agent — a principal software architect (Opus, plan mode) that provides strategic guidance on system design, technology evaluation, and architectural decisions.
When to Use
- Designing new system components or services
- Evaluating technology choices (build vs. buy, library selection)
- Planning large-scale migrations or refactors
- Assessing technical debt and prioritizing remediation
- Creating Architecture Decision Records (ADRs) for
docs/adr/ - Reviewing system design for quality attributes (scalability, maintainability, security)
What the Agent Does
The architecture-advisor agent operates in plan mode — it researches the codebase, analyzes the current architecture, and presents a recommended approach for your approval before any changes are made.
- Understands current architecture — reads config files, maps dependencies, reviews existing ADRs
- Identifies the concern — new design, migration, scaling, tech debt
- Evaluates against principles — Clean Architecture, SOLID, DDD, Twelve-Factor App
- Assesses quality attributes — scalability, maintainability, testability, security, performance, reliability, observability
- Produces an ADR — documents the decision with context, alternatives, consequences
Output Format
The agent produces Architecture Decision Records in the standard ADR format:
ADR-NNN: Title with Status, Context, Decision, Consequences, and Alternatives Considered.
See .claude/agents/architecture-advisor.md for the full advisory protocol and ADR template.