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
npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a claude-codeWhat 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-code2Manually: put the files in place
~/.claude/skills/scope-appropriate-architecture/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/scope-appropriate-architecture/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a codex2Manually: put the files in place
.agents/skills/scope-appropriate-architecture/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a cursor2Manually: put the files in place
.cursor/skills/scope-appropriate-architecture/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install yonatangross/orchestkit src/skills/scope-appropriate-architecture2Manually: put the files in place
.github/skills/scope-appropriate-architecture/SKILL.md1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a gemini-cli2Platform CLI
gemini skills install https://github.com/yonatangross/orchestkit --path src/skills/scope-appropriate-architectureManually: put the files in place
.devin/skills/scope-appropriate-architecture/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill scope-appropriate-architecture -a opencodeClaude.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 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