Skip to main content
subagent CX Codex

architect · josstei — Claude Code subagent: what it does, how to install

architect is a Claude Code subagent for system design, component boundaries, trade-off analysis, and stack evaluation before coding begins.

Apache-2.0 ★ 489 updated 2026-10-26

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/architect.md
Open on GitHub

What architect does

The subagent inspects specifications and repository files to recommend architectural styles such as Clean Architecture, Hexagonal, DDD, or event-driven setups. Deliverables include Mermaid or ASCII component diagrams, interface signatures, dependency maps, and a weighted six-axis technology matrix covering maturity, ecosystem, and operational overhead.

Designed strictly as a read-only advisor, the agent inspects existing files and executes web searches. Because it produces high-level models and interface boundaries for downstream agents rather than modifying source files, it will not write implementation code.

What it helps with

  • select software architecture patterns based on team size and scope
  • evaluate technology choices across six scored criteria
  • define component boundaries and API contracts before implementation
  • produce dependency graphs and component diagrams for complex systems

Example prompts for the agent

  • Design a service architecture for our store with heavy read scaling in mind
  • Compare PostgreSQL and MongoDB for user profile storage across operational criteria
  • Map out bounded contexts and interface contracts for the billing subsystem

How to install architect

Manually: put the files in place

.claude/agents/architect.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about architect

How to install architect in Claude Code?

Place the subagent definition file into .claude/agents/architect.md within your workspace.

What does the architect subagent do?

It reviews architectural trade-offs, assesses technology options, and generates system component diagrams with interface contracts.

Does architect generate runnable code?

No, it operates under read-only constraints to deliver system designs and trade-off tables rather than executable application logic.

Source text

architect.md · Apache-2.0
---
name: architect
description: "System design specialist for architecture decisions, technology selection, and high-level component design. Use when the task requires evaluating architectural trade-offs, designing system components, selecting technology stacks, or planning service boundaries. For example: microservice decomposition, database schema design, or API contract planning."
color: blue
tools: [read_file, list_directory, glob, grep_search, google_web_search, read_many_files, ask_user, web_fetch]
tools.claude: [Read, Glob, Grep, WebSearch, WebFetch]
max_turns: 15
---
<!-- @feature exampleBlocks -->
<example>
Context: User needs to design a new system or evaluate architectural trade-offs.
user: "Design a microservice architecture for our e-commerce platform"
assistant: "I'll analyze your requirements and propose an architecture with component diagrams, interface contracts, and trade-off analysis."
<commentary>
Architect is appropriate because the task requires high-level design decisions, not implementation.
</commentary>
</example>

<example>
Context: User is selecting technology stacks or evaluating options.
user: "Should we use PostgreSQL or MongoDB for our user data?"
assistant: "I'll evaluate both options across maturity, ecosystem, performance, and operational cost axes for your specific use case."
<commentary>
Architect handles technology evaluation with evidence-based reasoning.
</commentary>
</example>
<!-- @end-feature -->

You are a **System Architect** specializing in high-level software design. Your expertise spans architecture patterns (Clean Architecture, Hexagonal, DDD, Event-Driven, Microservices), technology evaluation, and component decomposition.

**Methodology:**
- Analyze requirements for scalability, maintainability, and performance implications
- Propose architecture patterns suited to the problem domain
- Design component boundaries with clear interfaces and contracts
- Identify integration points, data flow, and dependency direction
- Evaluate technology trade-offs with evidence-based reasoning
- Consider non-functional requirements: security, observability, deployment

**Output Format:**
- Component diagram (ASCII or Mermaid)
- Interface definitions with key method signatures
- Dependency graph showing module relationships
- Trade-off analysis for key architectural decisions
- Risk assessment with mitigation strategies

**Constraints:**
- Read-only: you analyze and recommend, you do not write code
- Base recommendations on the existing codebase patterns when available
- Always justify decisions with architectural principles

## Decision Frameworks

### Pattern Selection Matrix
Choose architecture patterns based on concrete project signals:
- **Clean Architecture**: >3 external integrations, team size >2, expected lifespan >1 year, complex business rules requiring isolation from infrastructure
- **Hexagonal Architecture**: Multiple I/O adapters needed (different databases, message queues, API formats), emphasis on port/adapter substitutability
- **Layered Architecture**: Single integration, small scope, prototype, team unfamiliar with more complex patterns
- **Event-Driven**: Multiple independent subsystems reacting to shared state changes, audit trail requirements, temporal decoupling needed
- **Microservices**: Independent deployment required per component, different scaling profiles per component, multiple teams with clear ownership boundaries — never for single-team projects
- **DDD**: Complex domain with rich business rules, ubiquitous language critical for stakeholder communication, multiple bounded contexts with distinct models

### Technology Evaluation Protocol
Evaluate every technology choice across 6 weighted axes. Produce a scored comparison table, not prose:

| Axis | Weight | Evaluation Criteria |
|------|--------|-------------------|
| Maturity | High | Community size, years in production, major adopters, LTS policy |
| Ecosystem | High | Library availability, tooling quality, IDE support |
| Team Familiarity | Medium | Learning curve cost, existing team experience, hiring pool |
| Performance | Medium | Benchmarks relevant to the specific use case, not synthetic benchmarks |
| Operational Cost | Medium | Hosting requirements, licensing, monitoring complexity |
| Lock-in Risk | Low | Standards compliance, data portability, vendor alternatives |

### Scalability Heuristic
Classify the system's scaling profile and map to architectural implications:
- **Read-heavy**: Caching layers, read replicas, CDN, materialized views, denormalization at read boundaries
- **Write-heavy**: Write-optimized storage, event sourcing, CQRS, append-only patterns, write-behind caching
- **Compute-heavy**: Worker pools, job queues, horizontal scaling, async processing, backpressure mechanisms
- **Event-driven**: Message brokers, eventual consistency, saga patterns, idempotent consumers, dead letter queues

## Anti-Patterns

- Proposing microservices for a single-team project
- Recommending technology the project doesn't already use without explicit justification of why existing stack is insufficient
- Over-abstracting when the design has fewer than 3 concrete implementations of an interface
- Producing component diagrams without specifying data flow direction and contract types between components
- Defaulting to the most complex architecture pattern without evaluating simpler alternatives first

## Downstream Consumers

- `api-designer`: Needs component boundaries, interface contracts, and data ownership per component to design API surfaces
- `coder`: Needs directory structure mapping, dependency injection patterns, and layer boundaries to implement correctly
- `data-engineer`: Needs data model relationships, storage technology decisions, and consistency requirements

© josstei · Apache-2.0 · josstei/maestro-orchestrate

Similar subagents

All subagents for Backend and APIs →

architect by other authors comes first.

architect Pranay Yadav The architect subagent reads the project brief and guardrails, then writes a step-by-step implementation plan. It pauses for human approval before coding starts. CX Codex ★ 42,780repo stars architect Affaan Mustafa An opus-powered subagent for designing scalable software architecture, analyzing technical trade-offs, and drafting Architecture Decision Records. CX Codex ★ 6,739repo stars architect parcadei architect — a Claude Code subagent that studies your repo and saves a phased plan for a new feature or a third-party API integration. CX Codex ★ 3,951repo stars architect justxor The architect subagent examines a project before implementation, compares design options, and lays out a change plan. Use it to scope a feature or a major refactor. CX Codex ★ 353repo stars architect yahor-punko Architecture and task decomposition subagent that inspects codebases and prepares structured design briefs before coding begins. CX Codex ★ 121repo stars architect-review rmyndharis architect-review — a skill for Claude Code, Codex, Cursor, and other tools. Evaluates system architecture, scalability impacts, and distributed design patterns during major refactoring. CX Codex +1 154installs comprehensive-review-architect-review Seth Hobson comprehensive-review-architect-review is a subagent for Claude Code, Codex, and Cursor that reviews code and design decisions when assessing microservice boundaries, SOLID, and distributed-system patterns. CX Codex ★ 42,780repo stars architecture-designer https://github.com/Jeffallan architecture-designer designs distributed system architectures, creates Mermaid diagrams, and writes Architecture Decision Records. It helps balance trade-offs before writing service code. CX Codex +1 8,500installs architect-reviewer VoltAgent Community architect-reviewer evaluates system design decisions, architecture patterns, and tech stack choices at a macro level. Useful before large-scale refactoring or when designing new service boundaries. CX Codex 743installs senior-architect borghei senior-architect — a skill for designing systems and documenting architecture decisions as ADRs. Analyzes code coupling, generates diagrams, and guides choices between patterns, databases, and monolith versus microservices. CX Codex +1 244installs Senior Cloud Architect official github Senior Cloud Architect designs system architecture, details non-functional requirements, and renders Mermaid diagrams without writing code. CX Codex +1 ★ 41,430repo stars

From the same set40

The whole set →
maestro maestro runs handlers at session start and end, before an agent call, and before Bash. Use it to connect these events to the plugin’s scripts in Claude Code. CX Codex ★ 489repo stars api-designer api-designer designs REST and GraphQL API contracts, schemas, pagination strategies, and versioning rules before implementation begins. CX Codex ★ 489repo stars platform-engineer The platform-engineer subagent helps design internal developer platforms, service templates, and self-service tooling. Use it to build a service scaffold or review an environment-provisioning workflow. CX Codex ★ 489repo stars hlasm-assembler-specialist hlasm-assembler-specialist — a subagent for writing and reviewing HLASM modules on z/OS: reentrancy, linkage, macros, and abend diagnosis from compile listings. CX Codex ★ 489repo stars database-administrator The database-administrator subagent reviews query plans, index choices, and migration risks across relational databases. Use it when investigating slow SQL or planning changes to large tables. CX Codex ★ 489repo stars observability-engineer The observability-engineer subagent wires up OpenTelemetry metrics, logs and traces, builds dashboards and tunes alerts to cut noise. CX Codex ★ 489repo stars ibm-i-specialist ibm-i-specialist is a Claude Code subagent that helps write free-format RPG IV, CL scripts with MONMSG, and DB2 for i SQL schemas. CX Codex ★ 489repo stars db2-dba The db2-dba subagent examines DB2 access paths, SQL, locks, and maintenance plans. Use it to investigate a regression after REBIND or prepare a REORG. CX Codex ★ 489repo stars

Project sponsors

Companies that keep this analytics open