Architecture validation and patterns for clean architecture, backend structure enforcement, project structure validation, test standards, and context-aware sizing. Use when designing system boundaries, enforcing layered architecture, validating project structure, defining test standards, or choosing the right architecture tier for project scope.
Instrucciones de origen · Vista previa de solo lectura
name
architecture-patterns
license
MIT
compatibility
Claude Code 2.1.220+.
description
Architecture validation and patterns for clean architecture, backend structure enforcement, project structure validation, test standards, and context-aware sizing. Use when designing system boundaries, enforcing layered architecture, validating project structure, defining test standards, or choosing the right architecture tier for project scope.
Consolidated architecture validation and enforcement patterns covering clean architecture, backend layer separation, project structure conventions, and test standards. Each category has individual rule files in rules/ loaded on-demand. House scars and dated decisions rescued from retired reference tutorials live in references/ork-delta.md; the tutorials themselves are upstream's job (see "Upstream coverage" below).
House scars for this category (exception-to-HTTP status map, import-level violation greps, DI override teardown): ${CLAUDE_PLUGIN_ROOT}/skills/architecture-patterns/references/ork-delta.md.
Layer Boundaries
Layer
Responsibility
Forbidden
Routers
HTTP concerns, request parsing, auth checks
Database operations, business logic
Services
Business logic, validation, orchestration
HTTPException, Request objects
Repositories
Data access, queries, persistence
HTTP concerns, business logic
Test Standards
Testing best practices with AAA pattern, naming conventions, isolation, and coverage thresholds.
ORM, auth, error handling, testing recommendations per tier, over-engineering tax
Tier-Based Rule Enforcement
Rule
Interview
MVP
Production
Enterprise
Layer separation
OFF
WARN
BLOCK
BLOCK
Repository pattern
OFF
OFF
WARN
BLOCK
Domain exceptions
OFF
OFF
BLOCK
BLOCK
Dependency injection
OFF
WARN
BLOCK
BLOCK
OpenAPI documentation
OFF
OFF
WARN
BLOCK
Manual override: User can set tier explicitly to bypass auto-detection (e.g., "I want enterprise patterns for this take-home to demonstrate skill").
Decision Flowchart
Is this a take-home or hackathon?
YES --> Flat architecture. Single file or 3-5 files. Done.
NO -->
Is this a prototype or MVP with < 3 months runway?
YES --> Simple layered. Routes + services + models. No abstractions.
NO -->
Do you have > 5 engineers or complex domain rules?
YES --> Clean architecture with ports/adapters.
NO --> Layered architecture. Add abstractions only when pain appears.
When NOT to Use
Not every project needs architecture patterns. Match complexity to project tier:
Pattern
Interview
Hackathon
MVP
Growth
Enterprise
Simpler Alternative
Repository pattern
OVERKILL (~200 LOC)
OVERKILL
BORDERLINE
APPROPRIATE
REQUIRED
Direct ORM calls in service (~20 LOC)
DI containers
OVERKILL (~150 LOC)
OVERKILL
LIGHT ONLY
APPROPRIATE
REQUIRED
Constructor params or module-level singletons (~10 LOC)
Event-driven arch
OVERKILL (~300 LOC)
OVERKILL
OVERKILL
SELECTIVE
APPROPRIATE
Direct function calls between services (~30 LOC)
Hexagonal architecture
OVERKILL (~400 LOC)
OVERKILL
OVERKILL
BORDERLINE
APPROPRIATE
Flat modules with imports (~50 LOC)
Strict layer separation
OVERKILL (~250 LOC)
OVERKILL
WARN
BLOCK
BLOCK
Routes + models in same file (~40 LOC)
Domain exceptions
OVERKILL (~100 LOC)
OVERKILL
OVERKILL
BLOCK
BLOCK
Built-in ValueError/HTTPException (~5 LOC)
Rule of thumb: If a pattern shows OVERKILL for the detected tier, do NOT use it. Use the simpler alternative. A take-home with hexagonal architecture signals over-engineering, not skill.
Anti-Patterns (FORBIDDEN)
# CLEAN ARCHITECTURE# NEVER import infrastructure in domain layerfrom app.infrastructure.database import engine # In domain layer!# NEVER leak ORM models to API layer@router.get("/users/{id}")asyncdefget_user(id: str, db: Session) -> UserModel: # Returns ORM model!# NEVER have domain depend on frameworkfrom fastapi import HTTPException
classUserService:
defget(self, id: str):
raise HTTPException(404) # Framework in domain!# PROJECT STRUCTURE# NEVER create files deeper than 4 levels from src/# NEVER create barrel files (index.ts re-exports)# NEVER import from higher layers (features importing from app)# NEVER import across features (use shared/ for common code)# BACKEND LAYERS# NEVER use database operations in routers# NEVER raise HTTPException in services# NEVER instantiate services without Depends()# TEST STANDARDS# NEVER mix test files with source code# NEVER use non-descriptive test names (test1, test, works)# NEVER share mutable state between tests without reset
Upstream coverage (do not restate)
Long-form tutorials on these topics were removed from this skill (2026-07-31 wrap-plus-delta campaign). Read them at the first-party source; only floors, scars, and house decisions belong here (see references/ork-delta.md).
Topic
First-party source
Hexagonal architecture, ports and adapters walkthrough
