Advisor Code Architect

A senior software architect agent that delivers comprehensive, actionable architecture blueprints by deeply understanding codebases and making confident decisions on module boundaries, patterns, and technology choices.

When to Use This Agent

Choose Code Architect when:

• Analyzing existing codebases to understand architecture and patterns
• Making architectural decisions about module boundaries and dependencies
• Designing component architectures for new features within existing systems
• Evaluating and recommending technology choices for specific problems
• Creating actionable architecture blueprints with implementation guidance

Consider alternatives when:

• Writing implementation code rather than architecture (use a development agent)
• Conducting architecture reviews for production readiness (use a review agent)
• Designing system-level architecture across multiple services (use a system architect)

Quick Start

Copy
# .claude/agents/advisor-code-architect.yml
name: Code Architect
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
prompt: |
  You are a senior code architect. Deeply analyze codebases to
  understand patterns and conventions before making decisions.
  Deliver actionable architecture blueprints with clear rationale.
  Your decisions should align with existing patterns and team
  capabilities.

Example invocation:

Copy
claude --agent advisor-code-architect "Analyze the current
  authentication module and design an architecture for adding
  multi-tenant support. Identify all affected modules and
  provide a migration blueprint."

Core Concepts

Architecture Analysis Process

1. Codebase Pattern Analysis
   - Extract conventions, patterns, naming standards
   - Map module boundaries and dependencies
   - Identify technology stack and frameworks

2. Dependency Mapping
   - Trace import chains
   - Identify circular dependencies
   - Map external service integrations

3. Quality Assessment
   - Test coverage gaps
   - Technical debt hotspots
   - Performance bottleneck areas

4. Blueprint Creation
   - New module design
   - Integration points
   - Migration path

Module Boundary Criteria

Criterion	Good Boundary	Bad Boundary
Cohesion	Module does one thing well	Module handles unrelated concerns
Coupling	Minimal external dependencies	Changes require modifying other modules
Interface	Clean, stable public API	Internals leaked to consumers
Data	Owns its data exclusively	Shares database tables with others
Deployability	Can be deployed independently	Requires coordinated deployment
Testability	Can be tested in isolation	Requires full system to test

Blueprint Document Template

Copy
## Architecture Blueprint: {Feature/Change}

### Current State
- Module structure and dependencies
- Patterns in use
- Technical debt relevant to this change

### Proposed Architecture
- New/modified modules with responsibilities
- Interface definitions
- Data ownership model

### Integration Points
- Which existing modules are affected
- API contracts between modules
- Event/message contracts

### Migration Plan
- Phased approach with milestones
- Backward compatibility strategy
- Rollback plan for each phase

### Risk Assessment
- Technical risks and mitigations
- Impact on existing functionality
- Performance implications

Configuration

Parameter	Description	Default
analysis_depth	Codebase analysis thoroughness	Deep
blueprint_format	Architecture document format	Markdown
include_migration	Add migration plan	true
risk_assessment	Include risk analysis	true
code_examples	Add code examples to blueprint	true
pattern_alignment	Enforce existing pattern consistency	true
dependency_analysis	Map and visualize dependencies	true

Best Practices

1. Read the codebase before designing anything. The most common architecture mistake is designing without understanding what exists. Spend significant time reading existing code, understanding conventions, and mapping dependencies before proposing changes. An architecture that ignores existing patterns creates two systems in one codebase.

2. Design module interfaces before module internals. Define what each module promises to the rest of the system: its public API, events it emits, and data it owns. The interface is the contract that other teams and modules depend on. Getting the interface right is more important than the internal implementation, which can be refactored later without affecting consumers.

3. Make the architecture support independent team work. If two features require coordinating changes across the same modules, those modules have the wrong boundaries. Good module boundaries let different teams work on different features simultaneously with minimal coordination. Design boundaries around team ownership, not just technical concerns.

4. Document the rationale alongside the decision. "We chose PostgreSQL" is a decision. "We chose PostgreSQL because our query patterns require complex joins, our team has PostgreSQL expertise, and our deployment platform includes managed PostgreSQL at no additional cost" is an architecture decision with rationale. Rationale helps future architects understand whether to change the decision when circumstances change.

5. Plan the migration as carefully as the target architecture. A beautiful target architecture is useless without a safe path to reach it. Design a phased migration where each phase leaves the system in a working state. Define what backward compatibility is maintained at each phase and how to roll back if a phase fails. The migration plan is often harder to get right than the architecture itself.

Common Issues

Architecture blueprint is too abstract to implement. Blueprints that specify "a service for handling notifications" without defining the API, data model, or integration points leave too much ambiguity for implementers. Include concrete specifications: API endpoints with request/response examples, database table definitions, and sequence diagrams for key flows. Implementers should be able to start coding from the blueprint.

Architecture doesn't account for the team's current capabilities. An architecture requiring Kubernetes, event sourcing, and CQRS is wrong for a team of three JavaScript developers. Assess team skills and propose architecture that can be built and maintained by the actual team. If the ideal architecture requires skills the team doesn't have, include a training plan or simplify the architecture to match current capabilities.

Changes to one module cascade into changes across the system. This indicates tight coupling between modules. Identify the coupling points: shared database tables, synchronous call chains, or shared data types. Introduce interfaces, events, or API boundaries that decouple the modules. When module A changes its internal data model, module B should not need to change—they communicate through a stable interface.