Agent-Skills.md

Agent Skills: Architecture Patterns

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.

document-asset-creationID: yonatangross/orchestkit/architecture-patterns

Repository

yonatangross/orchestkit
yonatangrossLicense: MIT
13314

Install this agent skill to your local

pnpm dlx add-skill https://github.com/yonatangross/orchestkit/tree/HEAD/src/skills/architecture-patterns

Skill Files

Browse the full folder contents for architecture-patterns.

Download Skill

Loading file tree…

src/skills/architecture-patterns/SKILL.md

Skill Metadata

Name
architecture-patterns
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.

Architecture Patterns

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 references/ loaded on-demand.

Quick Reference

| Category | Rules | Impact | When to Use | |----------|-------|--------|-------------| | Clean Architecture | 3 | HIGH | SOLID principles, hexagonal architecture, ports & adapters, DDD | | Project Structure | 2 | HIGH | Folder conventions, nesting depth, import direction, barrel files | | Backend Layers | 3 | HIGH | Router/service/repository separation, DI, file naming | | Test Standards | 3 | MEDIUM | AAA pattern, naming conventions, coverage thresholds | | Right-Sizing | 2 | HIGH | Architecture tier selection, over-engineering prevention, context-aware enforcement |

Total: 13 rules across 5 categories

Quick Start

# Clean Architecture: Dependency Inversion via Protocol
class IUserRepository(Protocol):
    async def get_by_id(self, id: str) -> User | None: ...

class UserService:
    def __init__(self, repo: IUserRepository):
        self._repo = repo  # Depends on abstraction, not concretion

# FastAPI DI chain: DB -> Repository -> Service
def get_user_service(db: AsyncSession = Depends(get_db)) -> UserService:
    return UserService(PostgresUserRepository(db))

# Project Structure: Unidirectional Import Architecture
shared/lib  ->  components  ->  features  ->  app
(lowest)                                    (highest)

# Backend Layers: Strict Separation
Routers (HTTP) -> Services (Business Logic) -> Repositories (Data Access)

Clean Architecture

SOLID principles, hexagonal architecture, ports and adapters, and DDD tactical patterns for maintainable backends.

| Rule | File | Key Pattern | |------|------|-------------| | Hexagonal Architecture | ${CLAUDE_SKILL_DIR}/references/clean-hexagonal-ports-adapters.md | Driving/driven ports, adapter implementations, layer structure | | SOLID & Dependency Rule | ${CLAUDE_SKILL_DIR}/references/clean-solid-dependency-rule.md | Protocol-based interfaces, dependency inversion, FastAPI DI | | DDD Tactical Patterns | ${CLAUDE_SKILL_DIR}/references/clean-ddd-tactical-patterns.md | Entities, value objects, aggregate roots, domain events |

Key Decisions

| Decision | Recommendation | |----------|----------------| | Protocol vs ABC | Protocol (structural typing) | | Dataclass vs Pydantic | Dataclass for domain, Pydantic for API | | Repository granularity | One per aggregate root | | Transaction boundary | Service layer, not repository | | Event publishing | Collect in aggregate, publish after commit |

Project Structure

Feature-based organization, max nesting depth, unidirectional imports, and barrel file prevention.

| Rule | File | Key Pattern | |------|------|-------------| | Folder Structure & Nesting | ${CLAUDE_SKILL_DIR}/references/structure-folder-conventions.md | React/Next.js and FastAPI layouts, 4-level max nesting, barrel file rules | | Import Direction & Location | ${CLAUDE_SKILL_DIR}/references/structure-import-direction.md | Unidirectional imports, cross-feature prevention, component/hook placement |

Blocking Rules

| Rule | Check | |------|-------| | Max Nesting | Max 4 levels from src/ or app/ | | No Barrel Files | No index.ts re-exports (tree-shaking issues) | | Component Location | React components in components/ or features/ only | | Hook Location | Custom hooks in hooks/ or features/*/hooks/ only | | Import Direction | Unidirectional: shared -> components -> features -> app |

Backend Layers

FastAPI Clean Architecture with router/service/repository layer separation and blocking validation.

| Rule | File | Key Pattern | |------|------|-------------| | Layer Separation | ${CLAUDE_SKILL_DIR}/references/backend-layer-separation.md | Router/service/repository boundaries, forbidden patterns, async rules | | Dependency Injection | ${CLAUDE_SKILL_DIR}/references/backend-dependency-injection.md | Depends() chains, auth patterns, testing with DI overrides | | File Naming & Exceptions | ${CLAUDE_SKILL_DIR}/references/backend-naming-exceptions.md | Naming conventions, domain exceptions, violation detection |

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.

| Rule | File | Key Pattern | |------|------|-------------| | AAA Pattern & Isolation | ${CLAUDE_SKILL_DIR}/references/testing-aaa-isolation.md | Arrange-Act-Assert, test isolation, parameterized tests | | Naming Conventions | ${CLAUDE_SKILL_DIR}/references/testing-naming-conventions.md | Descriptive behavior-focused names for Python and TypeScript | | Coverage & Location | ${CLAUDE_SKILL_DIR}/references/testing-coverage-location.md | Coverage thresholds, fixture scopes, test file placement rules |

Coverage Requirements

| Area | Minimum | Target | |------|---------|--------| | Overall | 80% | 90% | | Business Logic | 90% | 100% | | Critical Paths | 95% | 100% | | New Code | 100% | 100% |

Right-Sizing

Context-aware backend architecture enforcement. Rules adjust strictness based on project tier detected by scope-appropriate-architecture.

Enforcement procedure:

  1. Read project tier from scope-appropriate-architecture context (set during brainstorm/implement Step 0)
  2. If no tier set, auto-detect using signals in Read("${CLAUDE_SKILL_DIR}/rules/right-sizing-tiers.md")
  3. Apply tier-based enforcement matrix — skip rules marked OFF for detected tier
  4. Security rules are tier-independent — always enforce SQL parameterization, input validation, auth checks

| Rule | File | Key Pattern | |------|------|-------------| | Architecture Sizing Tiers | ${CLAUDE_SKILL_DIR}/rules/right-sizing-tiers.md | Interview/MVP/production/enterprise sizing matrix, LOC estimates, detection signals | | Right-Sizing Decision Guide | ${CLAUDE_SKILL_DIR}/rules/right-sizing-decision.md | 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 layer
from app.infrastructure.database import engine  # In domain layer!

# NEVER leak ORM models to API layer
@router.get("/users/{id}")
async def get_user(id: str, db: Session) -> UserModel:  # Returns ORM model!

# NEVER have domain depend on framework
from fastapi import HTTPException
class UserService:
    def get(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

Related Skills

  • ork:scope-appropriate-architecture - Project tier detection that drives right-sizing enforcement
  • ork:quality-gates - YAGNI gate uses tier context to validate complexity
  • ork:distributed-systems - Distributed locking, resilience, idempotency patterns
  • ork:api-design - REST API design, versioning, error handling
  • ork:testing-unit - Unit testing: AAA pattern, fixtures, mocking, factories
  • ork:testing-e2e - E2E testing: Playwright, page objects, visual regression
  • ork:testing-integration - Integration testing: API endpoints, database, contracts
  • ork:python-backend - FastAPI, SQLAlchemy, asyncio patterns
  • ork:database-patterns - Schema design, query optimization, migrations