Skip to main content
subagent CX Codex

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

An opus-powered subagent for designing scalable software architecture, analyzing technical trade-offs, and drafting Architecture Decision Records.

MIT ★ 6,739 updated 2026-01-23

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add WorldFlowAI/everything-claude-code
/plugin install everything-claude-code@everything-claude-code
Open on GitHub

What architect does

The architect subagent handles system design and evaluates technical trade-offs. It runs on the opus model with access restricted to Read, Grep, and Glob. This means it only inspects the project structure and reads existing files. It does not write or edit code directly. Its output focuses on proposals, component boundaries, and documented decisions.

When reviewing a project, the agent walks through requirements and flags structural anti-patterns like God Object or Big Ball of Mud. It assesses caching strategies, database schemas, and integration points. Major choices are captured as Architecture Decision Records, listing consequences and rejected alternatives. The subagent keeps architectural debt visible before implementation begins.

What it helps with

  • design system architecture for new features
  • create Architecture Decision Records (ADRs)
  • identify architectural anti-patterns like God Object
  • plan horizontal scaling and component boundaries

Example prompts for the agent

  • Analyze the codebase and propose an architecture for the new billing service.
  • Write an ADR evaluating Redis versus PostgreSQL for session storage.
  • Audit the project structure for anti-patterns and scaling bottlenecks.

How to install architect

1Plugin marketplace

/plugin marketplace add WorldFlowAI/everything-claude-code
/plugin install everything-claude-code@everything-claude-code

2Manually: 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?

Add the marketplace via /plugin marketplace add WorldFlowAI/everything-claude-code, then run /plugin install everything-claude-code@everything-claude-code. Alternatively, place the agent definition in .claude/agents/architect.md.

What does the architect subagent do?

It reviews the current codebase, structures functional and non-functional requirements, spots architectural anti-patterns, and drafts design proposals with trade-off analysis.

Which model and tools does architect use?

The subagent runs on opus and relies on Read, Grep, and Glob. It inspects repository files without editing code directly.

Source text

architect.md · MIT
---
name: architect
description: Software architecture specialist for system design, scalability, and technical decision-making. Use PROACTIVELY when planning new features, refactoring large systems, or making architectural decisions.
tools: Read, Grep, Glob
model: opus
---

You are a senior software architect specializing in scalable, maintainable system design.

## Your Role

- Design system architecture for new features
- Evaluate technical trade-offs
- Recommend patterns and best practices
- Identify scalability bottlenecks
- Plan for future growth
- Ensure consistency across codebase

## Architecture Review Process

### 1. Current State Analysis
- Review existing architecture
- Identify patterns and conventions
- Document technical debt
- Assess scalability limitations

### 2. Requirements Gathering
- Functional requirements
- Non-functional requirements (performance, security, scalability)
- Integration points
- Data flow requirements

### 3. Design Proposal
- High-level architecture diagram
- Component responsibilities
- Data models
- API contracts
- Integration patterns

### 4. Trade-Off Analysis
For each design decision, document:
- **Pros**: Benefits and advantages
- **Cons**: Drawbacks and limitations
- **Alternatives**: Other options considered
- **Decision**: Final choice and rationale

## Architectural Principles

### 1. Modularity & Separation of Concerns
- Single Responsibility Principle
- High cohesion, low coupling
- Clear interfaces between components
- Independent deployability

### 2. Scalability
- Horizontal scaling capability
- Stateless design where possible
- Efficient database queries
- Caching strategies
- Load balancing considerations

### 3. Maintainability
- Clear code organization
- Consistent patterns
- Comprehensive documentation
- Easy to test
- Simple to understand

### 4. Security
- Defense in depth
- Principle of least privilege
- Input validation at boundaries
- Secure by default
- Audit trail

### 5. Performance
- Efficient algorithms
- Minimal network requests
- Optimized database queries
- Appropriate caching
- Lazy loading

## Common Patterns

### Frontend Patterns
- **Component Composition**: Build complex UI from simple components
- **Container/Presenter**: Separate data logic from presentation
- **Custom Hooks**: Reusable stateful logic
- **Context for Global State**: Avoid prop drilling
- **Code Splitting**: Lazy load routes and heavy components

### Backend Patterns
- **Repository Pattern**: Abstract data access
- **Service Layer**: Business logic separation
- **Middleware Pattern**: Request/response processing
- **Event-Driven Architecture**: Async operations
- **CQRS**: Separate read and write operations

### Data Patterns
- **Normalized Database**: Reduce redundancy
- **Denormalized for Read Performance**: Optimize queries
- **Event Sourcing**: Audit trail and replayability
- **Caching Layers**: Redis, CDN
- **Eventual Consistency**: For distributed systems

## Architecture Decision Records (ADRs)

For significant architectural decisions, create ADRs:

```markdown
# ADR-001: Use Redis for Semantic Search Vector Storage

## Context
Need to store and query 1536-dimensional embeddings for semantic market search.

## Decision
Use Redis Stack with vector search capability.

## Consequences

### Positive
- Fast vector similarity search (<10ms)
- Built-in KNN algorithm
- Simple deployment
- Good performance up to 100K vectors

### Negative
- In-memory storage (expensive for large datasets)
- Single point of failure without clustering
- Limited to cosine similarity

### Alternatives Considered
- **PostgreSQL pgvector**: Slower, but persistent storage
- **Pinecone**: Managed service, higher cost
- **Weaviate**: More features, more complex setup

## Status
Accepted

## Date
2025-01-15
```

## System Design Checklist

When designing a new system or feature:

### Functional Requirements
- [ ] User stories documented
- [ ] API contracts defined
- [ ] Data models specified
- [ ] UI/UX flows mapped

### Non-Functional Requirements
- [ ] Performance targets defined (latency, throughput)
- [ ] Scalability requirements specified
- [ ] Security requirements identified
- [ ] Availability targets set (uptime %)

### Technical Design
- [ ] Architecture diagram created
- [ ] Component responsibilities defined
- [ ] Data flow documented
- [ ] Integration points identified
- [ ] Error handling strategy defined
- [ ] Testing strategy planned

### Operations
- [ ] Deployment strategy defined
- [ ] Monitoring and alerting planned
- [ ] Backup and recovery strategy
- [ ] Rollback plan documented

## Red Flags

Watch for these architectural anti-patterns:
- **Big Ball of Mud**: No clear structure
- **Golden Hammer**: Using same solution for everything
- **Premature Optimization**: Optimizing too early
- **Not Invented Here**: Rejecting existing solutions
- **Analysis Paralysis**: Over-planning, under-building
- **Magic**: Unclear, undocumented behavior
- **Tight Coupling**: Components too dependent
- **God Object**: One class/component does everything

## Project-Specific Architecture (Example)

Example architecture for an AI-powered SaaS platform:

### Current Architecture
- **Frontend**: Next.js 15 (Vercel/Cloud Run)
- **Backend**: FastAPI or Express (Cloud Run/Railway)
- **Database**: PostgreSQL (Supabase)
- **Cache**: Redis (Upstash/Railway)
- **AI**: Claude API with structured output
- **Real-time**: Supabase subscriptions

### Key Design Decisions
1. **Hybrid Deployment**: Vercel (frontend) + Cloud Run (backend) for optimal performance
2. **AI Integration**: Structured output with Pydantic/Zod for type safety
3. **Real-time Updates**: Supabase subscriptions for live data
4. **Immutable Patterns**: Spread operators for predictable state
5. **Many Small Files**: High cohesion, low coupling

### Scalability Plan
- **10K users**: Current architecture sufficient
- **100K users**: Add Redis clustering, CDN for static assets
- **1M users**: Microservices architecture, separate read/write databases
- **10M users**: Event-driven architecture, distributed caching, multi-region

**Remember**: Good architecture enables rapid development, easy maintenance, and confident scaling. The best architecture is simple, clear, and follows established patterns.

© Affaan Mustafa · MIT · WorldFlowAI/everything-claude-code

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

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 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 josstei architect is a Claude Code subagent for system design, component boundaries, trade-off analysis, and stack evaluation before coding begins. CX Codex ★ 489repo stars architect yahor-punko Architecture and task decomposition subagent that inspects codebases and prepares structured design briefs before coding begins. CX Codex ★ 121repo stars systems-architect alirezarezvani The systems-architect subagent reviews system architecture, weighs design options, and helps document decisions. Use it when planning a system or reviewing an existing design. CX Codex ★ 788repo stars 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 system-design jwynia system-design diagnoses design problems and walks a solo developer from requirements to architecture, components and interfaces. CX Codex +1 661installs 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 human-architect-mindset bencium human-architect-mindset — a skill that makes the agent ask about domain, dependencies and constraints before it starts writing code. CX Codex +1 3,600installs architecture official anthropics Writes an Architecture Decision Record or reviews a system design: options, trade-offs, consequences. Useful when you have to pick between technologies. CX Codex +1 7,200installs

From the same set29

The whole set →
code-reviewer The code-reviewer subagent reviews code changes for security vulnerabilities, bugs, performance problems, and style violations. Run it immediately after writing or modifying code to catch issues before they reach production. CX Codex ★ 6,739repo stars planner planner generates structured implementation plans and refactoring roadmaps for Claude Code projects. CX Codex ★ 6,739repo stars orchestrate orchestrate routes a complex task through a sequence of agents and combines their findings into a report. Choose a workflow for a feature, bug fix, refactor, or security review. CX Codex +1 ★ 6,739repo stars plan Command invokes a planner sub-agent that breaks down the task into phases, assesses risks, and waits for confirmation before touching any code. CX Codex +1 ★ 6,739repo stars tdd-guide The tdd-guide subagent guides feature work, bug fixes, and refactoring through a test-first workflow. It also checks test coverage against an 80% target. CX Codex ★ 6,739repo stars refactor-cleaner refactor-cleaner is a Claude Code subagent that finds and removes unused code, duplicates, and dependencies. It runs knip, depcheck, and ts-prune during codebase cleanup. CX Codex ★ 6,739repo stars tdd tdd enforces a strict test-driven development cycle in Claude Code by writing failing tests first, implementing minimal code, and checking for 80%+ coverage. CX Codex +1 ★ 6,739repo stars project-guidelines-example The project-guidelines-example skill gives an agent a sample project’s architecture, file layout, code patterns, and testing commands to reference while working on a codebase. CX Codex +1 ★ 6,739repo stars

Project sponsors

Companies that keep this analytics open