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
/plugin marketplace add CloudAI-X/claude-workflow-v2
/plugin install project-starter@claude-workflowWhat 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-workflowThis 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-code3Manually: put the files in place
~/.claude/skills/designing-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/designing-architecture/
1Skills CLI (Vercel)
npx skills add CloudAI-X/claude-workflow-v2 --skill designing-architecture -a codex2Manually: put the files in place
.agents/skills/designing-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add CloudAI-X/claude-workflow-v2 --skill designing-architecture -a cursor2Manually: put the files in place
.cursor/skills/designing-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install CloudAI-X/claude-workflow-v2 skills/designing-architecture2Manually: put the files in place
.github/skills/designing-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add CloudAI-X/claude-workflow-v2 --skill designing-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/CloudAI-X/claude-workflow-v2 --path skills/designing-architectureManually: put the files in place
.devin/skills/designing-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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