Skip to main content
skill CX Codex

scope-appropriate-architecture — Claude Code skill

scope-appropriate-architecture classifies projects into six tiers and picks patterns that fit their scope, preventing microservices for MVPs. Activates during design and complexity checks.

MIT 179 installs ★ 305 updated 2026-11-07

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a claude-code
Open on GitHub

What scope-appropriate-architecture does

The skill divides projects into six tiers — from interview assignments to enterprise — and sets a complexity ceiling for each: which patterns are appropriate and which are overkill. For an interview assignment, flat files and SQLite. For an MVP, a monolith with Postgres and ready-made auth via Clerk. For enterprise, hexagonal architecture and message queues. A table lists technologies by tier: databases, authentication, state, CI/CD.

For tiers one through three, it recommends SaaS over custom builds: Stripe for payments, Resend for email, Algolia for search. Repository pattern is marked overkill for interviews, appropriate for growth stage, required for enterprise. Microservices are prohibited until tier four. The skill is loaded by other OrchestKit skills during context discovery and passes the detected tier downstream to constrain decision-making.

Install with npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture and a platform flag. Works in Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. Requires Node.js for npx installation.

What it helps with

  • pick a database that matches task scale
  • decide if microservices are needed at launch
  • choose testing level for an MVP
  • determine when CQRS is overkill
  • decide whether to build auth or use a service

Example prompts for the agent

  • What architecture tier fits a weekend prototype?
  • Check if this project is over-engineered for its scope.
  • Does a three-feature startup need hexagonal architecture?

How to install scope-appropriate-architecture

1Skills CLI (Vercel)

npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a claude-code

2Manually: put the files in place

~/.claude/skills/scope-appropriate-architecture/SKILL.md

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

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

Questions about scope-appropriate-architecture

How to install scope-appropriate-architecture in Claude Code?

Run npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a claude-code. The skill appears in ~/.claude/skills/scope-appropriate-architecture/SKILL.md.

What does scope-appropriate-architecture do?

Detects one of six project tiers and shows which architectural patterns fit and which are overkill. For interview assignments, it prohibits repository pattern. For MVPs, microservices. For enterprise, everything is allowed.

Which platforms support the skill?

Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI and OpenCode. Each platform requires its own flag during npx installation.

Source text

SKILL.md · MIT
---
name: scope-appropriate-architecture
license: MIT
compatibility: "Claude Code 2.1.277+"
description: "Classifies a project into 6 tiers to right-size its architecture and prevent over-engineering. Use when choosing patterns for a project's scope."
user-invocable: false
context: inherit
effort: low
model: haiku
metadata:
  category: architecture
  version: "1.0.0"
  author: "OrchestKit"
  complexity: "low"
  tags: "architecture, yagni, over-engineering, scope, patterns"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
---

# Scope-Appropriate Architecture

Right-size every architectural decision to the project's actual needs. Not every project needs hexagonal architecture, CQRS, or microservices.

**Core principle:** Detect the project tier first, then constrain all downstream pattern choices to that tier's complexity ceiling.

---

## The 6 Project Tiers

| Tier | LOC Ratio | Architecture | DB | Auth | Tests |
|------|-----------|-------------|-----|------|-------|
| **1. Interview/Take-home** | 1.0-1.3x | Flat files, no layers | SQLite / JSON | None or basic | 8-15 focused |
| **2. Hackathon/Prototype** | 0.8-1.0x | Single file if possible | SQLite / in-memory | None | Zero |
| **3. Startup/MVP** | 1.0-1.5x | MVC monolith | Managed Postgres | Clerk/Supabase Auth | Happy path + critical |
| **4. Growth-stage** | 1.5-2.0x | Modular monolith | Postgres + Redis | Auth service | Unit + integration |
| **5. Enterprise** | 2.0-3.0x | Hexagonal/DDD | Postgres + queues | OAuth2/SAML | Full pyramid |
| **6. Open Source** | 1.2-1.8x | Minimal API surface | Configurable | Optional | Exhaustive public API |

**LOC Ratio** = total lines / core business logic lines. Higher ratio = more infrastructure code relative to business value.

---

## Auto-Detection Signals

| Signal | Tier Indicator |
|--------|---------------|
| README contains "take-home", "assignment", "interview" | Tier 1 |
| Time limit mentioned (e.g., "4 hours", "weekend") | Tier 1-2 |
| < 10 files, no CI, no Docker | Tier 1-2 |
| `.github/workflows/` present | Tier 3+ |
| `package.json` with 20+ dependencies | Tier 3+ |
| Kubernetes/Terraform files present | Tier 4-5 |
| `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md` | Tier 6 |
| Monorepo with `packages/` or `apps/` | Tier 4-5 |

**When confidence is low:** Ask the user with `AskUserQuestion`.

---

## Pattern Appropriateness Matrix

| Pattern | Interview | Hackathon | MVP | Growth | Enterprise |
|---------|-----------|-----------|-----|--------|------------|
| Repository pattern | OVERKILL | OVERKILL | BORDERLINE | APPROPRIATE | REQUIRED |
| Event-driven arch | OVERKILL | OVERKILL | OVERKILL | SELECTIVE | APPROPRIATE |
| DI containers | OVERKILL | OVERKILL | LIGHT ONLY | APPROPRIATE | REQUIRED |
| Separate DTO layers | OVERKILL | OVERKILL | 1 EXTRA | 2 LAYERS | ALL LAYERS |
| Microservices | NEVER | NEVER | NEVER | EXTRACT ONLY | APPROPRIATE |
| CQRS | OVERKILL | OVERKILL | OVERKILL | OVERKILL | WHEN JUSTIFIED |
| Hexagonal architecture | OVERKILL | OVERKILL | OVERKILL | BORDERLINE | APPROPRIATE |
| DDD (bounded contexts) | OVERKILL | OVERKILL | OVERKILL | SELECTIVE | APPROPRIATE |
| Message queues | OVERKILL | OVERKILL | BORDERLINE | APPROPRIATE | REQUIRED |
| API versioning | SKIP | SKIP | URL prefix | Header-based | Full strategy |
| Error handling | try/catch | console.log | Error boundary | Error service | RFC 9457 |
| Logging | console.log | none | Structured JSON | Centralized | OpenTelemetry |

**Rule of thumb:** If a pattern shows OVERKILL for the detected tier, do NOT use it. Suggest the simpler alternative instead.

---

## Technology Quick-Reference by Tier

| Choice | Interview | Hackathon | MVP | Growth | Enterprise |
|--------|-----------|-----------|-----|--------|------------|
| **Database** | SQLite / JSON file | In-memory / SQLite | Managed Postgres | Postgres + Redis | Postgres + queues + cache |
| **Auth** | Hardcoded / none | None | Clerk / Supabase Auth | Auth service | OAuth2 / SAML / SSO |
| **State mgmt** | useState | useState | Zustand / Context | Zustand + React Query | Redux / custom + cache |
| **CSS** | Inline / Tailwind | Tailwind | Tailwind | Tailwind + design tokens | Design system |
| **API** | Express routes | Single file handler | Next.js API routes | FastAPI / Express | Gateway + services |
| **Deployment** | localhost | Vercel / Railway | Vercel / Railway | Docker + managed | K8s / ECS |
| **CI/CD** | None | None | GitHub Actions basic | Multi-stage pipeline | Full pipeline + gates |
| **Monitoring** | None | None | Error tracking only | APM + logs | Full observability stack |

---

## Build vs Buy Decision Tree (Tiers 1-3)

For Interview, Hackathon, and MVP tiers, **always prefer buying over building**:

| Capability | BUY (use SaaS) | BUILD (only if) |
|-----------|----------------|-----------------|
| Auth | Clerk, Supabase Auth, Auth0 | Core product IS auth |
| Payments | Stripe | Core product IS payments |
| Email | Resend, SendGrid | Core product IS email |
| File storage | S3, Cloudflare R2 | Compliance requires on-prem |
| Search | Algolia, Typesense Cloud | > 10M docs or custom ranking |
| Analytics | PostHog, Mixpanel | Unique data requirements |

**Time savings:** Auth alone is 2-4 weeks build vs 2 hours integrate.

---

## Upgrade Path

When a project grows beyond its current tier, upgrade incrementally:

```
Tier 2 (Prototype) → Tier 3 (MVP)
  Add: Postgres, basic auth, error boundaries, CI

Tier 3 (MVP) → Tier 4 (Growth)
  Add: Redis cache, background jobs, monitoring, module boundaries

Tier 4 (Growth) → Tier 5 (Enterprise)
  Add: DI, bounded contexts, message queues, full observability
  Extract: First microservice (only the proven bottleneck)
```

**Key insight:** You can always add complexity later. You cannot easily remove it.

---

## When This Skill Activates

This skill is loaded by:
- `brainstorm` Phase 0 (context discovery)
- `implement` Step 0 (context discovery)
- `quality-gates` YAGNI check
- Any skill that needs to right-size a recommendation

The detected tier is passed as context to constrain downstream decisions.

---

## Related Skills

- `ork:brainstorm` - Uses tier detection in Phase 0 to constrain ideas
- `ork:implement` - Uses tier detection in Step 0 to constrain architecture
- `ork:quality-gates` - YAGNI gate references this skill's tier matrix
- `ork:architecture-patterns` - Architecture validation (constrained by tier)

---

## References

Load on demand with `Read("references/<file>")`:
| File | Content |
|------|---------|
| `interview-takehome.md` | Tiers 1-2 in detail |
| `startup-mvp.md` | Tier 3 patterns and decisions |
| `enterprise.md` | Tiers 4-5 patterns and justification criteria |
| `open-source.md` | Tier 6 unique considerations |

© OrchestKit · MIT · yonatangross/orchestkit

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set86

The whole set →
product-frameworks This skill provides product frameworks for business analysis, prioritization, metrics, and research. Use it to shape a business case, PRD, or user research plan. CX Codex +1 194installs golden-dataset golden-dataset is a Claude Code skill for evaluation dataset lifecycle patterns, covering curation, versioning, quality thresholds, and Langfuse experiment runs. CX Codex +1 193installs mcp-patterns mcp-patterns — a skill for Claude Code and Codex that guides Model Context Protocol server design. Activates when configuring transports, adding OAuth, wiring tool handlers, or hardening MCP security. CX Codex +1 191installs browser-tools browser-tools is a Claude Code skill that adds safety rules for browser automation with agent-browser, including scraping ethics, request pacing, local URLs, and authentication. It runs automatically during browser automation. CX Codex +1 191installs storybook-mcp-integration The storybook-mcp-integration Claude Code skill connects Storybook MCP tools to work with existing components. The agent can find component docs, open story previews, and run story tests. CX Codex +1 166installs help This skill scans the installed OrchestKit skills and sorts them into categories. It helps you find the workflow or skill that matches a task. CX Codex +1 166installs business-case business-case is a Claude Code skill that calculates ROI, NPV, IRR, payback period and TCO. It runs when an agent builds a financial case or compares build vs buy. CX Codex +1 162installs testing-e2e testing-e2e provides Playwright E2E standards, page object patterns, and axe-core accessibility checks. Activates when editing tests or playwright.config.*. CX Codex +1 160installs

Project sponsors

Companies that keep this analytics open