# Architecture Designer

> Define technical architecture and create ADRs. Triggers on "Help me define the architecture", "Define architecture", "Let's design the architecture".

- Skill: `majiayu000/architecture-designer-2` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/architecture-designer-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/architecture-designer-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/architecture-designer-2

---


# Architecture Designer (Fase 0)

Transform project requirements into concrete architectural decisions with proper ADR documentation.

## Triggers

- "Help me define the architecture"
- "Define architecture"
- "Let's design the architecture"
- "Help me with technical architecture"
- `/architecture`

## Prerequisites

- `docs/project.md` should exist with project definition
- If not exists, suggest: "Let's first interview about the project"

## Purpose

Create:
1. **Architecture overview** in `docs/architecture/_index.md`
2. **ADRs** (Architecture Decision Records) in `docs/decisions/`
3. **Technical foundation** for feature development

## Process

### 1. Read Project Context

```bash
# Read project definition
cat docs/project.md

# Check existing architecture docs
ls -la docs/architecture/ 2>/dev/null
ls -la docs/decisions/ 2>/dev/null
```

### 2. Identify Key Decisions

Based on project.md, identify decisions needed:

| Category | Typical Decisions |
|----------|-------------------|
| **Language/Runtime** | Python, Node, Go, Rust |
| **Framework** | FastAPI, Django, Express, Next.js |
| **Database** | PostgreSQL, MongoDB, SQLite, Redis |
| **Authentication** | JWT, OAuth, Session, API Keys |
| **Hosting** | AWS, GCP, Azure, Vercel, Self-hosted |
| **API Style** | REST, GraphQL, gRPC |
| **Frontend** | React, Vue, Gradio, CLI |
| **Caching** | Redis, Memcached, In-memory |
| **Queue/Async** | Celery, RQ, SQS, None |
| **Monitoring** | CloudWatch, Datadog, Prometheus |

### 3. Interview for Each Decision

For each major decision, ask:

```
"For [CATEGORY], I see a few options:

A) [Option A] - [Pros: X, Y] [Cons: Z]
B) [Option B] - [Pros: X, Y] [Cons: Z]
C) [Option C] - [Pros: X, Y] [Cons: Z]

Based on your project (MVP timeline, team size, scale needs),
I'd recommend [X] because [reason].

What's your preference?"
```

### 4. Create ADRs

For each decision, create `docs/decisions/ADR-NNN-title.md`

### 5. Create Architecture Overview

Update `docs/architecture/_index.md` with:
- System diagram
- Tech stack table linking to ADRs
- Project structure
- Key patterns

### 6. Interview Rules

```
ARCHITECTURE INTERVIEW RULES

1. Always provide options with trade-offs
   Never ask "what database?" - ask "PostgreSQL or MongoDB? Here's why..."

2. Make recommendations based on project context
   "Given your MVP timeline, I recommend X"

3. Create ADR immediately after each decision
   Don't wait until the end

4. Challenge over-engineering
   "Do you really need Kubernetes for MVP? ECS is simpler."

5. Document the WHY, not just the WHAT
   Future you will thank present you
```

### 7. Completion Check

Before ending, verify:
- [ ] All major categories have decisions
- [ ] Each decision has an ADR
- [ ] Architecture overview exists
- [ ] Project structure is defined
- [ ] No conflicting decisions

### 8. Handoff

When complete:

```
Architecture defined. Created:
- docs/architecture/_index.md (overview)
- docs/decisions/ADR-001-*.md through ADR-00N-*.md

Next step:
"Define MVP features" -> Creates feature folders ready for implementation

Or: "Let's start with the first feature"
```