architecture-patterns · yonatangross — Claude Code skill: what it does
architecture-patterns enforces clean architecture, backend layer boundaries, and directory limits. Triggers when designing module boundaries or running refactoring tasks.
MIT 236 installs ★ 305 updated 2026-11-14
npx skills add yonatangross/orchestkit --skill architecture-patterns -a claude-codeWhat architecture-patterns does
The skill bundles 13 architecture enforcement rules across five domains: clean architecture, folder layout, backend layer isolation, test standards, and right-sizing. It enforces strict separation where routers manage HTTP concerns, services orchestrate business logic without framework request objects, and repositories isolate persistence. In Python backends, it guides dependency inversion using Protocol abstractions and FastAPI dependency chains.
Project structure rules stop folder nesting beyond four levels from src/ or app/, forbid barrel file re-exports in index.ts to protect tree-shaking, and enforce unidirectional import flow. Testing rules require the Arrange-Act-Assert pattern, isolated fixtures, and strict test coverage standards that reach 100% on new code.
Because user-invocable is set to false, you do not trigger this skill via a slash command; the agent references its rules autonomously during architecture work. Calibrating rule strictness relies on the companion scope-appropriate-architecture skill.
What it helps with
- Prevent database queries from leaking into HTTP routers
- Enforce maximum four-level directory nesting across the codebase
- Eliminate barrel file re-exports that break bundler tree-shaking
- Validate test coverage against a 90% minimum for business logic
Example prompts for the agent
- Review this FastAPI service and verify router-service-repository separation
- Check our frontend folder structure against the unidirectional import rule
- Audit new test suites to confirm they follow Arrange-Act-Assert patterns
How to install architecture-patterns
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill architecture-patterns -a claude-code2Manually: put the files in place
~/.claude/skills/architecture-patterns/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/architecture-patterns/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill architecture-patterns -a codex2Manually: put the files in place
.agents/skills/architecture-patterns/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill architecture-patterns -a cursor2Manually: put the files in place
.cursor/skills/architecture-patterns/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install yonatangross/orchestkit src/skills/architecture-patterns2Manually: put the files in place
.github/skills/architecture-patterns/SKILL.md1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill architecture-patterns -a gemini-cli2Platform CLI
gemini skills install https://github.com/yonatangross/orchestkit --path src/skills/architecture-patternsManually: put the files in place
.devin/skills/architecture-patterns/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill architecture-patterns -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 architecture-patterns
How do I install architecture-patterns in Claude Code?
Run npx skills add yonatangross/orchestkit --skill architecture-patterns -a claude-code in your terminal.
Can I run architecture-patterns with a slash command?
No. The configuration marks it with user-invocable: false, meaning the model consults these architecture rules automatically when reviewing or generating system code.
What backend layers does this skill enforce?
It enforces strict boundaries between HTTP routers, business logic services, and persistence repositories, banning database calls in routers and HTTP exceptions in services.
Source text
SKILL.md · MIT
---
name: architecture-patterns
license: MIT
compatibility: "Claude Code 2.1.277+."
description: "Clean and layered architecture patterns, project structure and test-standard validation. Use when designing system boundaries or enforcing structure. For tier sizing, use scope-appropriate-architecture."
skills: [scope-appropriate-architecture]
user-invocable: false
disable-model-invocation: false
effort: high
metadata:
owner-agent: "backend-system-architect"
category: document-asset-creation
version: "2.1.0"
author: "OrchestKit"
complexity: "high"
tags: "architecture, clean-architecture, validation, structure, enforcement, testing-standards, right-sizing, over-engineering, context-aware"
allowed-tools: "Read Glob Grep WebFetch WebSearch"
paths: ["src/**", "package.json", "tsconfig.json"]
---
<!-- directive-density: intentional (teaches anti-patterns; NEVER markers describe real layering violations, not aspirational guidance) -->
# 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 `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).
## Quick Reference
| Category | Rules | Impact | When to Use |
|----------|-------|--------|-------------|
| [Clean Architecture](#clean-architecture) | 3 | HIGH | SOLID principles, hexagonal architecture, ports & adapters, DDD |
| [Project Structure](#project-structure) | 2 | HIGH | Folder conventions, nesting depth, import direction, barrel files |
| [Backend Layers](#backend-layers) | 3 | HIGH | Router/service/repository separation, DI, file naming |
| [Test Standards](#test-standards) | 3 | MEDIUM | AAA pattern, naming conventions, coverage thresholds |
| [Right-Sizing](#right-sizing) | 2 | HIGH | Architecture tier selection, over-engineering prevention, context-aware enforcement |
**Total: 13 rules across 5 categories**
## Quick Start
```python
# 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 | `rules/clean-hexagonal.md` | Driving/driven ports, adapter implementations, layer structure |
| SOLID & Dependency Rule | `rules/clean-dependency-rule.md` | Protocol-based interfaces, dependency inversion, FastAPI DI |
| DDD Tactical Patterns | `rules/clean-ports-adapters.md` | Entities, value objects, aggregate roots, domain events |
Design review checklist: `checklists/solid-checklist.md`. Domain entity scaffold: `scripts/domain-entity-template.py`.
### 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 | `rules/structure-folders.md` | React/Next.js and FastAPI layouts, 4-level max nesting, barrel file rules |
| Import Direction & Location | `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 | `rules/backend-layers.md` | Router/service/repository boundaries, forbidden patterns, async rules |
| Dependency Injection | `rules/backend-di.md` | Depends() chains, blocked DI patterns, violation detection |
| File Naming & Exceptions | `rules/backend-repository.md` | Naming conventions, async rules, domain exceptions |
House scars for this category (exception-to-HTTP status map, import-level violation greps, DI override teardown): `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.
| Rule | File | Key Pattern |
|------|------|-------------|
| AAA Pattern & Isolation | `rules/testing-aaa.md` | Arrange-Act-Assert, test isolation, parameterized tests |
| Naming Conventions | `references/testing-naming-conventions.md` | Descriptive behavior-focused names for Python and TypeScript |
| Coverage & Location | `rules/testing-coverage.md` | Coverage thresholds, fixture scopes, and (per `references/ork-delta.md`) the no-co-location rule |
### 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("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 | `rules/right-sizing-tiers.md` | Interview/MVP/production/enterprise sizing matrix, LOC estimates, detection signals |
| Right-Sizing Decision Guide | `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)
```python
# 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
```
## 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 | Alistair Cockburn, https://alistair.cockburn.us/hexagonal-architecture/ and Architecture Patterns with Python, https://www.cosmicpython.com/ |
| SOLID principles tutorial (Protocol-based) | Architecture Patterns with Python, https://www.cosmicpython.com/ and Python Protocol spec, https://typing.python.org/en/latest/spec/protocol.html |
| DDD tactical patterns (entities, value objects, aggregates, domain events) | Architecture Patterns with Python, https://www.cosmicpython.com/ |
| FastAPI dependency injection, auth dependencies, DI test overrides | FastAPI docs (context7: /tiangolo/fastapi), https://fastapi.tiangolo.com/tutorial/dependencies/ and skill ork:python-backend |
| Router/service/repository layer walkthrough | FastAPI bigger applications, https://fastapi.tiangolo.com/tutorial/bigger-applications/ and skill ork:python-backend |
| Full FastAPI clean-architecture example app | FastAPI full-stack template, https://github.com/fastapi/full-stack-fastapi-template |
| Next.js folder layout and structure-violation catalog | Next.js project structure docs, https://nextjs.org/docs/app/getting-started/project-structure (skill vercel:nextjs) |
| AAA pattern, isolation, parameterized tests, fixture scoping, coverage config | Skill ork:testing-unit; pytest docs, https://docs.pytest.org/en/stable/ and Vitest coverage, https://vitest.dev/config/#coverage |
## 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-extras: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
© OrchestKit · MIT · yonatangross/orchestkit
Similar skills
All skills for Backend and APIs →architecture-patterns by other authors comes first.