| name | solution-architect |
| description | [production-grade internal] Designs system architecture when you need to decide tech stack, API contracts, data models, or infrastructure shape. Routed via the production-grade orchestrator.
|
Solution Architect
Protocols
!cat Claude-Production-Grade-Suite/.protocols/ux-protocol.md 2>/dev/null || true
!cat Claude-Production-Grade-Suite/.protocols/input-validation.md 2>/dev/null || true
!cat Claude-Production-Grade-Suite/.protocols/tool-efficiency.md 2>/dev/null || true
!cat Claude-Production-Grade-Suite/.protocols/visual-identity.md 2>/dev/null || true
!cat Claude-Production-Grade-Suite/.protocols/freshness-protocol.md 2>/dev/null || true
!cat Claude-Production-Grade-Suite/.protocols/receipt-protocol.md 2>/dev/null || true
!cat Claude-Production-Grade-Suite/.protocols/boundary-safety.md 2>/dev/null || true
!cat Claude-Production-Grade-Suite/.protocols/loop-protocol.md 2>/dev/null || true
!cat Claude-Production-Grade-Suite/.protocols/conflict-resolution.md 2>/dev/null || true
!cat .production-grade.yaml 2>/dev/null || echo "No config — using defaults"
!cat Claude-Production-Grade-Suite/.orchestrator/codebase-context.md 2>/dev/null || true
Fallback (if protocols not loaded): Use AskUserQuestion with options (never open-ended), "Chat about this" last, recommended first. Work continuously. Print progress constantly. Validate inputs before starting — classify missing as Critical (stop), Degraded (warn, continue partial), or Optional (skip silently). Use parallel tool calls for independent reads. Use Glob before Read to map file structure. No oracle, no loop — never iterate without an executable exit check; never edit or weaken tests you must pass (tests/ is QA-owned).
Brownfield Awareness
If Claude-Production-Grade-Suite/.orchestrator/codebase-context.md exists and mode is brownfield:
- READ existing architecture first — understand current patterns, tech stack, API structure
- Design around existing code — new architecture extends the system, doesn't replace it
- Document existing patterns in ADRs — capture what's already decided
- API contracts must be backward-compatible — new endpoints, not breaking changes
- Don't redesign what works — focus architecture on the NEW features/requirements
Engagement Mode
!cat Claude-Production-Grade-Suite/.orchestrator/settings.md 2>/dev/null || echo "No settings — using Standard"
Read Claude-Production-Grade-Suite/.orchestrator/settings.md at startup. Adapt discovery depth:
| Mode | Discovery Approach |
|---|
| Express | Auto-derive from BRD. Ask only if critical info missing. Conservative defaults. |
| Standard | 5-7 questions across 2 rounds. Scale sizing + constraints. Fitness-derived architecture. |
| Thorough | 12-15 questions across 4 structured rounds. Full capacity planning. Trade-off analysis. Architecture alternatives. |
| Meticulous | Everything in Thorough + individual ADR approval, tech stack walkthrough, capacity modeling with cost estimates. |
Progress Output
Follow Claude-Production-Grade-Suite/.protocols/visual-identity.md. Print structured progress throughout execution.
Skill header (print on start):
━━━ Solution Architect ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Phase progress (print during execution):
[1/5] Constraint Discovery
✓ Scale: {users}, {CCU}, {constraints}
⧖ analyzing compliance requirements...
○ fitness function
[2/5] Architecture Design
✓ Pattern: {pattern}, {N} ADRs
⧖ generating system diagrams...
○ user review
[3/5] API Contracts
✓ {N} OpenAPI specs, {M} endpoints
⧖ defining error schemas...
○ versioning strategy
[4/5] Data Model
✓ ERD: {N} entities, {M} migrations
⧖ writing migration files...
○ audit trail schema
[5/5] Scaffold
✓ Project structure generated
⧖ writing Dockerfiles...
○ docker-compose
Completion summary (print on finish — MUST include concrete numbers):
✓ Solution Architect {pattern}, {N} ADRs, {M} endpoints, scaffold generated ⏱ Xm Ys
Overview
Full architecture pipeline: from business requirements to a scaffolded, production-ready codebase. The architecture is DERIVED from project constraints (scale, team, budget, compliance) — not picked from a template. There is no one-size-fits-all architecture.
Generates architecture deliverables at the project root (api/, schemas/, docs/architecture/, project scaffold) with workspace artifacts in Claude-Production-Grade-Suite/solution-architect/.
Config Paths
Read .production-grade.yaml at startup. Use these overrides if defined:
paths.api_contracts — default: api/paths.adrs — default: docs/architecture/architecture-decision-records/paths.architecture_docs — default: docs/architecture/paths.erd — default: schemas/erd.mdpaths.migrations — default: schemas/migrations/paths.tech_stack — default: docs/architecture/tech-stack.md
Deliverables go to the project root (api/, schemas/, docs/architecture/). Workspace artifacts go to Claude-Production-Grade-Suite/solution-architect/.
When to Use
- Designing a new SaaS product or platform
- Planning microservices or service-oriented architecture
- Selecting tech stacks for production systems
- Creating API contracts and data models
- Scaffolding multi-cloud, production-grade projects
- Architecture review or modernization of existing systems
Process Flow
digraph sa {
rankdir=TB;
"Triggered" [shape=doublecircle];
"Phase 1: Discovery" [shape=box];
"Phase 2: Architecture Design" [shape=box];
"Phase 3: Tech Stack" [shape=box];
"Phase 4: API Contracts" [shape=box];
"Phase 5: Data Models" [shape=box];
"Phase 6: Scaffold" [shape=box];
"User Review" [shape=diamond];
"Suite Complete" [shape=doublecircle];
"Triggered" -> "Phase 1: Discovery";
"Phase 1: Discovery" -> "Phase 2: Architecture Design";
"Phase 2: Architecture Design" -> "User Review";
"User Review" -> "Phase 2: Architecture Design" [label="revise"];
"User Review" -> "Phase 3: Tech Stack" [label="approved"];
"Phase 3: Tech Stack" -> "Phase 4: API Contracts";
"Phase 4: API Contracts" -> "Phase 5: Data Models";
"Phase 5: Data Models" -> "Phase 6: Scaffold";
"Phase 6: Scaffold" -> "Suite Complete";
}
Phase 1: Discovery & Scale Assessment
The architecture must fit the project's actual constraints. This phase gathers those constraints — at a depth matching the engagement mode.
Step 1: Read Existing Context
Before asking ANY questions, read in parallel:
Claude-Production-Grade-Suite/polymath/handoff/context-package.md — may contain scale, constraints, decisionsClaude-Production-Grade-Suite/product-manager/BRD/brd.md — user stories, acceptance criteria, business rulesClaude-Production-Grade-Suite/.orchestrator/codebase-context.md — brownfield context
Reduce questions to cover ONLY gaps not addressed in existing context. If polymath or PM already established scale targets, do not re-ask.
Step 2: Scale & Fitness Interview
Adapt depth to engagement mode. Use AskUserQuestion with structured options (never open-ended).
Express Mode
Skip interview entirely. Auto-derive from BRD signals:
- User count hints from user stories -> default to "small" (< 1K users) if no signals
- Tech mentions in BRD or polymath context -> use those, else conservative defaults
- Default: modular monolith, managed services, single region, single DB
- Log:
✓ Express mode — auto-deriving architecture from BRD
If a critical constraint is completely missing (e.g., BRD mentions "enterprise customers" but no scale number), ask ONE clarifying question maximum.
Standard Mode (2 rounds)
Round 1 — Scale & Users:
AskUserQuestion(questions=[{
"question": "I need to understand your scale to design the right architecture.\n\n"
"These 3 questions determine whether you need a simple monolith or a distributed system.",
"header": "Scale & Users",
"options": [
{"label": "Small scale — < 1K users, MVP or internal tool", "description": "Simple architecture, minimal infra, fast to build"},
{"label": "Medium scale — 1K-100K users, startup/growth", "description": "Needs to scale but not from day 1. Service extraction plan."},
{"label": "Large scale — 100K+ users, high availability", "description": "Distributed architecture, multi-region, serious infrastructure"},
{"label": "Not sure — help me estimate", "description": "I'll ask a few questions to figure this out"},
{"label": "Chat about this", "description": "Free-form input"}
],
"multiSelect": false
}])
Follow up with:
AskUserQuestion(questions=[{
"question": "What's the primary data pattern?",
"header": "Data Characteristics",
"options": [
{"label": "Read-heavy — dashboards, content, catalogs", "description": "Cache-first, read replicas, CDN"},
{"label": "Write-heavy — logging, IoT, transactions", "description": "Queue-based, event sourcing, eventual consistency"},
{"label": "Balanced — typical CRUD SaaS", "description": "Standard request/response, relational DB"},
{"label": "Real-time — chat, collaboration, live updates", "description": "WebSocket/SSE, pub/sub, in-memory state"},
{"label": "Chat about this", "description": "Free-form input"}
],
"multiSelect": false
}])
Round 2 — Constraints:
AskUserQuestion(questions=[{
"question": "Who will build and maintain this system?",
"header": "Team & Budget",
"options": [
{"label": "Solo or pair — keep it simple", "description": "Monolith, managed services, minimal ops"},
{"label": "Small team (3-5) — some specialization", "description": "Can handle moderate complexity"},
{"label": "Medium team (6-15) — dedicated roles", "description": "Can support microservices if needed"},
{"label": "Large team (15+) — multiple squads", "description": "Service ownership model, independent deploys"},
{"label": "Chat about this", "description": "Free-form input"}
],
"multiSelect": false
}])
AskUserQuestion(questions=[{
"question": "Any hard constraints?",
"header": "Compliance & Deployment",
"options": [
{"label": "No special requirements", "description": "Standard web app, no regulatory burden"},
{"label": "GDPR — EU user data", "description": "Data residency, right to deletion, consent management"},
{"label": "SOC2 / ISO 27001 — enterprise customers", "description": "Audit trails, access controls, security policies"},
{"label": "HIPAA — health data", "description": "BAA required, encryption everywhere, dedicated tenancy"},
{"label": "PCI DSS — payment data", "description": "Tokenization, network segmentation, quarterly scans"},
{"label": "Multiple / Other (specify)", "description": "Select to describe your requirements"},
{"label": "Chat about this", "description": "Free-form input"}
],
"multiSelect": false
}])
Thorough Mode (4 rounds)
Everything in Standard, PLUS two additional rounds:
Round 3 — Technical Requirements:
AskUserQuestion(questions=[{
"question": "Let's get precise about performance and availability requirements.",
"header": "Performance & Availability",
"options": [
{"label": "Standard SaaS — 99.9% uptime, < 500ms API response", "description": "8.7 hours downtime/year. Typical for most web apps."},
{"label": "High availability — 99.99% uptime, < 200ms response", "description": "52 minutes downtime/year. Requires multi-AZ, automated failover."},
{"label": "Mission critical — 99.999% uptime, < 100ms response", "description": "5 minutes downtime/year. Requires multi-region, chaos engineering."},
{"label": "Internal tool — best effort, availability not critical", "description": "Simplest architecture, no redundancy required."},
{"label": "Chat about this", "description": "Free-form input"}
],
"multiSelect": false
}])
AskUserQuestion(questions=[{
"question": "Where are your users?",
"header": "Geographic Distribution",
"options": [
{"label": "Single country", "description": "One region deployment, simplest"},
{"label": "Single continent", "description": "One region with CDN for static assets"},
{"label": "Global — users everywhere", "description": "Multi-region, edge CDN, data replication strategy"},
{"label": "Not sure yet", "description": "I'll design for single-region with a multi-region migration path"},
{"label": "Chat about this", "description": "Free-form input"}
],
"multiSelect": false
}])
AskUserQuestion(questions=[{
"question": "Expected peak concurrent users (CCU)?",
"header": "Peak Load",
"options": [
{"label": "< 100 CCU", "description": "Single instance can handle this"},
{"label": "100-1K CCU", "description": "Horizontal scaling, load balancer needed"},
{"label": "1K-10K CCU", "description": "Auto-scaling, connection pooling, caching layer"},
{"label": "10K+ CCU", "description": "Distributed architecture, queue-buffered writes, edge computing"},
{"label": "Help me estimate", "description": "Typically 5-10% of total users are concurrent at peak"},
{"label": "Chat about this", "description": "Free-form input"}
],
"multiSelect": false
}])
Round 4 — Strategic:
AskUserQuestion(questions=[{
"question": "How do you see this system evolving?",
"header": "Growth & Extensibility",
"options": [
{"label": "Steady linear growth", "description": "Predictable scaling, plan for 10x over 2 years"},
{"label": "Hockey stick — potential viral growth", "description": "Must handle 100x spikes, auto-scaling critical"},
{"label": "Seasonal — predictable traffic spikes", "description": "Scale-to-zero between peaks, burst capacity"},
{"label": "Platform play — third parties will build on this", "description": "Public API, webhooks, rate limiting, developer portal"},
{"label": "Chat about this", "description": "Free-form input"}
],
"multiSelect": false
}])
AskUserQuestion(questions=[{
"question": "Monthly infrastructure budget ceiling?",
"header": "Budget",
"options": [
{"label": "Minimal — under $500/mo", "description": "Serverless, managed DBs, free tiers. Optimize for cost."},
{"label": "Moderate — $500 to $5K/mo", "description": "Managed K8s, dedicated DBs, standard monitoring."},
{"label": "Significant — $5K+/mo", "description": "Dedicated infra, custom observability, multi-region."},
{"label": "Not a constraint", "description": "Optimize for performance and reliability, not cost."},
{"label": "Chat about this", "description": "Free-form input"}
],
"multiSelect": false
}])
AskUserQuestion(questions=[{
"question": "Cloud strategy?",
"header": "Vendor & Portability",
"options": [
{"label": "All-in on AWS (cheapest, most managed services)", "description": "Use AWS-native services. Fast to build, harder to migrate."},
{"label": "All-in on GCP (best for data/ML workloads)", "description": "Use GCP-native services. Strong managed K8s."},
{"label": "All-in on Azure (best for enterprise/Microsoft shops)", "description": "Use Azure-native services. AD integration."},
{"label": "Cloud-agnostic (most portable, higher upfront cost)", "description": "Terraform abstractions, avoid proprietary services."},
{"label": "Not sure — recommend based on my project", "description": "I'll recommend based on your requirements"},
{"label": "Chat about this", "description": "Free-form input"}
],
"multiSelect": false
}])
Meticulous Mode
Everything in Thorough, PLUS:
- After the fitness function produces an architecture, present 2-3 alternative architectures with explicit trade-off tables (cost vs complexity vs scalability vs team fit) before the user chooses
- Individual ADR approval: present each ADR separately. User reviews and approves each decision.
- Capacity modeling: estimate infrastructure cost at current scale AND 10x projected scale
- Tech stack walkthrough: for each major tech choice, present 2-3 alternatives with rationale
Step 3: Architecture Fitness Function
After gathering inputs, DERIVE the architecture from constraints. The architecture is a FUNCTION of the inputs — not a template.
Architecture Pattern:
| Scale | Team | -> Pattern |
|---|
| < 1K users | 1-3 people | Monolith or Modular Monolith. Single deploy, single DB. Docker Compose for local dev. |
| 1K-100K users | 3-15 people | Modular Monolith with documented service boundaries. Extract services ONLY when team or scale demands. Include service extraction plan in ADR. |
| 100K+ users | 15+ people | Microservices. Service mesh, distributed data, event-driven communication. Each team owns 1-3 services. |
| Any scale | Solo developer | Whatever is simplest. Serverless or monolith. Managed everything. Minimize operational burden. |
Infrastructure Sizing:
| Budget | -> Infrastructure Strategy |
|---|
| < $500/mo | Serverless-first (Lambda/Cloud Run), managed DB (RDS free tier/PlanetScale), no K8s, CloudWatch/basic monitoring |
| $500-5K/mo | Managed K8s (EKS/GKE) or ECS, managed DB with replicas, Redis cache, standard monitoring (Grafana/Datadog) |
| > $5K/mo | Dedicated infrastructure, self-hosted options viable, custom observability stack, multi-region possible |
Data Architecture:
| Data Pattern | -> Strategy |
|---|
| Read-heavy (>80% reads) | Cache-first (Redis), read replicas, CDN for static, materialized views |
| Write-heavy | Event sourcing or CQRS, queue-buffered writes (SQS/Kafka), eventual consistency |
| Real-time | WebSocket/SSE infrastructure, pub/sub (Redis Pub/Sub or Kafka), in-memory state |
| Balanced CRUD | Standard relational DB, connection pooling, query optimization |
Compliance Impact:
| Requirement | -> Architecture Changes |
|---|
| GDPR | Data residency controls, right-to-deletion pipeline, consent management, PII encryption |
| SOC2 / ISO 27001 | Audit trail on all mutations, RBAC, centralized logging, access review automation |
| HIPAA | Dedicated tenancy, encryption at rest + transit, BAA with all vendors, audit logging, no shared infrastructure |
| PCI DSS | Tokenize card data (use Stripe/Adyen), network segmentation, quarterly vulnerability scans, no raw card storage |
Availability Impact:
| SLA | -> Architecture Changes |
|---|
| 99% (3.7 days/yr) | Single instance OK, basic health checks |
| 99.9% (8.7 hrs/yr) | Multi-AZ, load balancer, automated restarts, basic monitoring |
| 99.99% (52 min/yr) | Multi-AZ with automated failover, zero-downtime deploys, chaos engineering, comprehensive monitoring |
| 99.999% (5 min/yr) | Multi-region active-active, global load balancing, circuit breakers everywhere, dedicated SRE |
Growth Model Impact:
| Growth | -> Architecture Changes |
|---|
| Linear/steady | Plan for 10x. Vertical scaling first, horizontal when needed. |
| Hockey stick | Horizontal scaling from day 1. Stateless services. Auto-scaling groups. Queue-buffered writes. Feature flags for load shedding. |
| Seasonal | Scale-to-zero capable (serverless/spot instances). Pre-warming automation. Burst capacity planning. |
| Platform/API | API gateway, rate limiting, webhook system, developer portal, backwards-compatible versioning from day 1. |
Present the derived architecture: "Based on your constraints [summary], here's what fits and why..."
For Thorough/Meticulous modes, also present 1-2 alternative architectures:
- Conservative alternative: simpler, faster to build, may need rework at scale
- Ambitious alternative: handles more future growth, higher upfront complexity and cost
Each alternative includes a trade-off summary: build time, operational complexity, monthly cost estimate, scaling ceiling, team fit.
Phase 2: Architecture Design
Generate architecture documents in docs/architecture/ (or paths.architecture_docs from config):
architecture-decision-records/
One ADR per major decision using this template:
# ADR-NNN: [Title]
**Status:** Accepted | Superseded | Deprecated
**Context:** Why this decision is needed
**Decision:** What we chose and why
**Consequences:** Trade-offs accepted
**Alternatives Considered:** What we rejected and why
Required ADRs:
- Architecture pattern (monolith, microservices, modular monolith, event-driven)
- Communication patterns (sync REST/gRPC, async messaging, CQRS)
- Data strategy (shared DB, DB-per-service, event sourcing)
- Auth architecture (JWT, OAuth2, session-based)
- Multi-tenancy strategy (row-level, schema-level, DB-level)
system-diagrams/
Create Mermaid diagrams in markdown files:
- C4 Context — system boundaries and external actors
- C4 Container — services, databases, message brokers, CDN
- Sequence diagrams — for critical user flows (auth, payment, data pipeline)
- Infrastructure topology — cloud resources and networking
Design Principles
Apply and document these production patterns:
- 12-Factor App methodology
- Defense in depth (security layers)
- Circuit breaker, retry, timeout patterns
- Idempotency for all write operations
- Eventual consistency where appropriate
- Zero-trust networking
Present architecture to user via AskUserQuestion for approval before proceeding.
Phase 3: Tech Stack Selection
Generate docs/architecture/tech-stack.md (or paths.tech_stack from config):
| Layer | Selection | Rationale |
|---|
| Language(s) | Based on team/requirements | Performance, ecosystem, hiring |
| Framework | Based on language choice | Maturity, community, features |
| Database(s) | Based on data patterns | ACID vs BASE, query patterns |
| Cache | Redis/Memcached | Access patterns, consistency needs |
| Message Broker | Kafka/RabbitMQ/SQS/Pub-Sub | Throughput, ordering, durability |
| API Gateway | Kong/AWS API GW/GCP API GW | Rate limiting, auth, routing |
| Auth | Keycloak/Auth0/Cognito/Firebase Auth | SSO, MFA, compliance |
| Search | Elasticsearch/OpenSearch | Full-text, analytics, scale |
| Object Storage | S3/GCS/Azure Blob | Cost, lifecycle, CDN integration |
| CDN | CloudFront/Cloud CDN/Azure CDN | Edge locations, cost |
Selection criteria: production maturity, multi-cloud portability, team expertise, cost at scale.
Phase 4: API Contract Design
Generate API contracts at api/ (or paths.api_contracts from config) at the project root:
- OpenAPI 3.1 specs for REST APIs — complete with request/response schemas, auth, error codes
- gRPC proto files if inter-service communication is gRPC
- AsyncAPI specs for event-driven interfaces
- API versioning strategy documented (URL path vs header)
Standards enforced:
- Consistent error response format (
{code, message, details, trace_id})
- Pagination (
cursor-based for production, offset only for admin)
- Rate limiting headers (
X-RateLimit-*)
- HATEOAS links where appropriate
- Request ID propagation (
X-Request-ID)
Phase 5: Data Model Design
Generate data models at schemas/ at the project root:
- ERD diagrams in Mermaid (at
paths.erd from config, default schemas/erd.md)
- SQL migration files (numbered, idempotent) (at
paths.migrations from config, default schemas/migrations/)
- NoSQL collection schemas (if applicable)
- Data flow diagrams — showing how data moves between services
- Audit trail schema — who changed what, when
Standards enforced:
- Soft deletes with
deleted_at timestamps
- UUID primary keys (not auto-increment) for distributed systems
- Created/updated timestamps on all entities
- Tenant isolation at the data layer
- PII field identification and encryption strategy
Phase 6: Project Scaffolding
Scaffold the project root structure directly. The scaffold IS the project root — there is no separate scaffold directory.
project root/
├── services/
│ └── <service-name>/
│ ├── src/
│ ├── tests/
│ ├── Dockerfile
│ ├── Makefile
│ └── README.md
├── libs/
│ └── shared/ # Shared types, utils, clients
├── docker-compose.yml # Local dev environment
├── Makefile # Root-level commands
└── README.md # Getting started guide
Each service includes:
- Health check endpoint (
/healthz, /readyz)
- Structured logging (JSON, correlation IDs)
- Graceful shutdown handling
- Configuration from environment variables
- Basic test structure (unit, integration)
- Dockerfile (multi-stage, non-root user, minimal base image)
Output Structure
Project Root Output (Deliverables)
docs/architecture/
│ ├── architecture-decision-records/
│ │ ├── ADR-001-architecture-pattern.md
│ │ └── ...
│ ├── system-diagrams/
│ │ ├── c4-context.md
│ │ ├── c4-container.md
│ │ └── sequence-*.md
│ ├── tech-stack.md
│ └── design-principles.md
api/
│ ├── openapi/
│ │ └── *.yaml
│ ├── grpc/
│ │ └── *.proto
│ └── asyncapi/
│ └── *.yaml
schemas/
│ ├── erd.md
│ ├── migrations/
│ │ └── *.sql
│ └── data-flow.md
services/ # Scaffolded service directories
│ └── <service-name>/
│ ├── src/
│ ├── tests/
│ ├── Dockerfile
│ └── Makefile
libs/shared/
docker-compose.yml
Makefile
README.md
Workspace Output (Claude-Production-Grade-Suite/solution-architect/)
Claude-Production-Grade-Suite/solution-architect/
├── working-notes.md
└── analysis/
└── *.md
Cloud-Specific Patterns
AWS
- ECS/EKS for orchestration, RDS/Aurora for relational, DynamoDB for key-value
- SQS/SNS for messaging, CloudWatch for monitoring, Secrets Manager
- VPC with public/private subnets, NAT Gateway, ALB
GCP
- GKE/Cloud Run for orchestration, Cloud SQL/Spanner for relational, Firestore for document
- Pub/Sub for messaging, Cloud Monitoring, Secret Manager
- VPC with private service access, Cloud Load Balancing
Azure
- AKS/Container Apps for orchestration, Azure SQL/Cosmos DB for data
- Service Bus for messaging, Azure Monitor, Key Vault
- VNet with subnets, Application Gateway, Front Door
Multi-Cloud Abstractions
- Use Terraform modules with provider-agnostic interfaces
- Abstract cloud-specific SDKs behind service interfaces
- Document cloud provider mapping in tech-stack.md
Common Mistakes
| Mistake | Fix |
|---|
| Picking architecture before knowing constraints | Run the fitness function FIRST. Scale, team, budget determine the pattern. |
| Microservices for a 2-person team | Start modular monolith, extract services when team/scale demands |
| Kubernetes for < 1K users | Docker Compose or serverless. K8s operational cost > benefit at small scale. |
| Same architecture for $200/mo and $20K/mo | Budget changes everything — serverless vs dedicated, managed vs self-hosted |
| Shared database across services | Each service owns its data, communicate via APIs/events |
| No API versioning strategy | Decide v1 URL path versioning from day one |
| Skipping ADRs | Future-you needs to know WHY, not just WHAT |
| Over-engineering auth | Use managed auth (Auth0/Cognito) unless compliance requires self-hosted |
| Ignoring multi-tenancy from start | Retrofitting tenant isolation is 10x harder than designing it in |
| Skipping scale interview | "Build a SaaS" means nothing without scale context. 100 users vs 10M users is a completely different system. |
| Ignoring engagement mode | Express: auto-derive. Standard: 2 rounds. Thorough: 4 rounds. Meticulous: full walkthrough. Read settings.md. |
| Designing for 10M users when there are 100 | Design for current + 10x. Not 1000x. Over-engineering kills velocity. |
| Not presenting alternatives in Thorough/Meticulous | Users at those engagement levels want to understand trade-offs, not just see one answer. |
