Skip to main content
skill CX Codex

designing-architecture for Claude Code: pick the right pattern

designing-architecture — a skill that guides you through selecting an architecture pattern, evaluating project size and team capacity, and structuring your codebase.

MIT ★ 1,424 updated 2026-10-06

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflow
Open on GitHub

What designing-architecture does

The skill walks you through a five-step process: understand requirements, assess project size and team capabilities, select from five core patterns, define directory structure, and validate the choice. Patterns range from simple layered architecture to microservices and event-driven systems, each with size thresholds and team requirements.

You get lookup tables for pattern selection by project size and team count, ready-to-use folder structures for feature-based and layer-based layouts, and a validation checklist. A template for documenting trade-offs helps you record why you chose one pattern over another. Each pattern includes a diagram and guidance on when to apply it.

The skill surfaces constraints before you start coding—whether your team has the skills for your chosen pattern, whether the project will outgrow it, and what you're trading off by that choice.

What it helps with

  • pick an architecture pattern that fits your project size
  • structure folders in a new codebase
  • decide when microservices make sense versus a modular monolith
  • document architecture decisions and their trade-offs
  • validate your architecture before development starts

Example prompts for the agent

  • Help me choose an architecture for a new React and Node.js project with a team of five
  • How should I organize folders in a Next.js app if I'm the only developer
  • Do we need microservices for our order processing system or is a modular monolith enough

How to install designing-architecture

1Plugin marketplace

/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflow

This installs the whole project-starter plugin with all its skills

2Skills CLI (Vercel)

npx skills add CloudAI-X/claude-workflow-v2 --skill designing-architecture -a claude-code

3Manually: put the files in place

~/.claude/skills/designing-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/designing-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about designing-architecture

How do I install designing-architecture in Claude Code?

Run /plugin marketplace add CloudAI-X/claude-workflow-v2, then /plugin install project-starter@claude-workflow. Alternatively, use npm: npx skills add CloudAI-X/claude-workflow-v2 --skill designing-architecture -a claude-code.

What does this skill do?

It guides you to select an architecture pattern that matches your project and team, validates the choice against your constraints, offers directory structure templates, and provides a format for documenting decisions.

When should I use layered architecture versus Clean Architecture?

Layered architecture suits simple CRUD apps and prototypes. Use Clean Architecture for complex business logic, long-lived projects, or when testability is essential.

Source text

SKILL.md · MIT
---
name: designing-architecture
description: Designs software architecture and selects appropriate patterns for projects. Use when designing systems, choosing architecture patterns, structuring projects, making technical decisions, or when asked about microservices, monoliths, or architectural approaches.
---

# Designing Architecture

### When to Load

- **Trigger**: System design, module structure, new project scaffolding, choosing architecture patterns
- **Skip**: Simple bug fixes or minor code changes that don't affect architecture

## Architecture Decision Workflow

Copy this checklist and track progress:

```
Architecture Design Progress:
- [ ] Step 1: Understand requirements and constraints
- [ ] Step 2: Assess project size and team capabilities
- [ ] Step 3: Select architecture pattern
- [ ] Step 4: Define directory structure
- [ ] Step 5: Document trade-offs and decision
- [ ] Step 6: Validate against decision framework
```

## Pattern Selection Guide

### By Project Size

| Size              | Recommended Pattern               |
| ----------------- | --------------------------------- |
| Small (<10K LOC)  | Simple MVC/Layered                |
| Medium (10K-100K) | Clean Architecture                |
| Large (>100K)     | Modular Monolith or Microservices |

### By Team Size

| Team      | Recommended                  |
| --------- | ---------------------------- |
| 1-3 devs  | Monolith with clear modules  |
| 4-10 devs | Modular Monolith             |
| 10+ devs  | Microservices (if justified) |

## Common Patterns

### 1. Layered Architecture

```
┌─────────────────────────────┐
│       Presentation          │  ← UI, API Controllers
├─────────────────────────────┤
│       Application           │  ← Use Cases, Services
├─────────────────────────────┤
│         Domain              │  ← Business Logic, Entities
├─────────────────────────────┤
│      Infrastructure         │  ← Database, External APIs
└─────────────────────────────┘
```

**Use when**: Simple CRUD apps, small teams, quick prototypes

### 2. Clean Architecture

```
┌─────────────────────────────────────┐
│            Frameworks & Drivers      │
│  ┌─────────────────────────────┐    │
│  │     Interface Adapters       │    │
│  │  ┌─────────────────────┐    │    │
│  │  │   Application       │    │    │
│  │  │  ┌─────────────┐    │    │    │
│  │  │  │   Domain    │    │    │    │
│  │  │  └─────────────┘    │    │    │
│  │  └─────────────────────┘    │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘
```

**Use when**: Complex business logic, long-lived projects, testability is key

### 3. Hexagonal (Ports & Adapters)

```
        ┌──────────┐
        │ HTTP API │
        └────┬─────┘
             │ Port
    ┌────────▼────────┐
    │                 │
    │   Application   │
    │     Core        │
    │                 │
    └────────┬────────┘
             │ Port
        ┌────▼─────┐
        │ Database │
        └──────────┘
```

**Use when**: Need to swap external dependencies, multiple entry points

### 4. Event-Driven Architecture

```
Producer → Event Bus → Consumer
              │
              ├─→ Consumer
              │
              └─→ Consumer
```

**Use when**: Loose coupling needed, async processing, scalability

### 5. CQRS (Command Query Responsibility Segregation)

```
┌─────────────┐      ┌─────────────┐
│  Commands   │      │   Queries   │
│  (Write)    │      │   (Read)    │
└──────┬──────┘      └──────┬──────┘
       │                    │
       ▼                    ▼
  Write Model          Read Model
       │                    │
       └────────┬───────────┘
                ▼
           Event Store
```

**Use when**: Different read/write scaling, complex domains, event sourcing

## Directory Structure Patterns

### Feature-Based (Recommended for medium+)

```
src/
├── features/
│   ├── users/
│   │   ├── api/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types/
│   └── orders/
│       ├── api/
│       ├── components/
│       └── ...
├── shared/
│   ├── components/
│   ├── hooks/
│   └── utils/
└── app/
    └── ...
```

### Layer-Based (Simple apps)

```
src/
├── controllers/
├── services/
├── models/
├── repositories/
└── utils/
```

## Decision Framework

When making architectural decisions, evaluate against these criteria:

1. **Simplicity** - Start simple, evolve when needed
2. **Team Skills** - Match architecture to team capabilities
3. **Requirements** - Let business needs drive decisions
4. **Scalability** - Consider growth trajectory
5. **Maintainability** - Optimize for change

## Trade-off Analysis Template

Use this template to document architectural decisions:

```markdown
## Decision: [What we're deciding]

### Context

[Why this decision is needed now]

### Options Considered

1. Option A: [Description]
2. Option B: [Description]

### Trade-offs

| Criteria         | Option A | Option B |
| ---------------- | -------- | -------- |
| Complexity       | Low      | High     |
| Scalability      | Medium   | High     |
| Team familiarity | High     | Low      |

### Decision

We chose [Option] because [reasoning].

### Consequences

- [What this enables]
- [What this constrains]
```

## Validation Checklist

After selecting an architecture, validate against:

```
Architecture Validation:
- [ ] Matches project size and complexity
- [ ] Aligns with team skills and experience
- [ ] Supports current requirements
- [ ] Allows for anticipated growth
- [ ] Dependencies flow inward (core has no external deps)
- [ ] Clear boundaries between modules/layers
- [ ] Testing strategy is feasible
- [ ] Trade-offs are documented
```

If validation fails, reconsider the pattern selection or adjust the implementation approach.

© CloudAI-X · MIT · CloudAI-X/claude-workflow-v2

Similar skills

All skills for Backend and APIs →

From the same set46

The whole set →
designing-apis designing-apis — a Claude Code skill that designs REST and GraphQL APIs: structures endpoints, defines request and response formats, configures error handling and versioning. CX Codex +1 ★ 1,424repo stars parallel-analyze parallel-analyze starts four subagents at once: architecture, security, performance, testing. Their findings land in one report, ranked by priority. CX Codex +1 ★ 1,424repo stars managing-git managing-git guides Claude Code through Git workflows, branch naming conventions, Conventional Commits formatting, and pull request review checklists. CX Codex +1 ★ 1,424repo stars code-reviewer code-reviewer — a Claude subagent that reads the changed files first, then reports findings by severity: correctness, security, performance, tests. CX Codex ★ 1,424repo stars optimizing-performance optimizing-performance guides performance profiling and tuning across frontend, backend, and database layers. It enforces measuring baselines before touching code and verifying against latency targets. CX Codex +1 ★ 1,424repo stars designing-tests designing-tests is a skill for planning test coverage, choosing test types, and investigating failures during test additions or testing-workflow setup. CX Codex +1 ★ 1,424repo stars debugger debugger finds root causes for test failures, memory leaks, and crashes. The subagent tests hypotheses systematically instead of guessing fixes. CX Codex ★ 1,424repo stars docs-writer The docs-writer subagent reads the implementation before creating or updating docs. Use it for README files, API references, guides, and documentation changes tied to code updates. CX Codex ★ 1,424repo stars

Project sponsors

Companies that keep this analytics open