designing-architecture
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.
- Installs
- 245
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/cloudai-x/claude-workflow-v2 --skill designing-architecture- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads designing-architecture automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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:
- Simplicity - Start simple, evolve when needed
- Team Skills - Match architecture to team capabilities
- Requirements - Let business needs drive decisions
- Scalability - Consider growth trajectory
- Maintainability - Optimize for change
Trade-off Analysis Template
Use this template to document architectural decisions:
## 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.
FAQ
What does the designing-architecture skill do?
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.
How do I install designing-architecture?
Run npx skills add https://github.com/cloudai-x/claude-workflow-v2 --skill designing-architecture in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/designing-architecture/ (personal) or .claude/skills/designing-architecture/ (project).
Which AI agents can use designing-architecture?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is designing-architecture safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains designing-architecture?
It is published by cloudai-x in cloudai-x/claude-workflow-v2. It has 245 recorded installs.
More from cloudai-x/claude-workflow-v2
analyzing-projects
cloudai-x/claude-workflow-v2
Analyzes codebases to understand structure, tech stack, patterns, and conventions. Use when onboarding to a new project, exploring unfamiliar code, or when asked "how does this work?" or "what's the architecture?"
convex-backend
cloudai-x/claude-workflow-v2
Convex backend development guidelines. Use when writing Convex functions, schemas, queries, mutations, actions, or any backend code in a Convex project. Triggers on tasks involving Convex database operations, real-time subscriptions, file storage, or serverless functions.
optimizing-performance
cloudai-x/claude-workflow-v2
Analyzes and optimizes application performance across frontend, backend, and database layers. Use when diagnosing slowness, improving load times, optimizing queries, reducing bundle size, or when asked about performance issues.
parallel-execution
cloudai-x/claude-workflow-v2
Patterns for parallel subagent execution using the Agent tool (formerly Task). Use when coordinating multiple independent tasks, spawning dynamic subagents, or implementing features that can be parallelized.
managing-git
cloudai-x/claude-workflow-v2
Manages Git workflows including branching, commits, and pull requests. Use when working with Git, creating commits, opening PRs, managing branches, resolving conflicts, or when asked about version control best practices.
designing-apis
cloudai-x/claude-workflow-v2
Designs REST and GraphQL APIs including endpoints, error handling, versioning, and documentation. Use when creating new APIs, designing endpoints, reviewing API contracts, or when asked about REST, GraphQL, or API patterns.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.