Architecture Patterns

What it does

When your agent uses it

• Designing system boundaries
• Enforcing layered architecture
• Validating project structure
• Defining test standards

Example prompts

• “/architecture-patterns”

Requirements

• Python 3
• Compatibility (from SKILL.md): Claude Code 2.1.277+.
• Pre-approved tools (allowed-tools): Read, Glob, Grep, WebFetch, WebSearch

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

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

What it can do on your machine

Read from SKILL.md and the folder at commit 0ef71d2. It shows what the files ask for, not the result of running them.

• Tool permissions

  Pre-approves these tools, so the agent can use them without asking each time:

  • Read
  • Glob
  • Grep
  • WebFetch
  • WebSearch

  From allowed-tools in the SKILL.md frontmatter.

• Runs code

  Ships 1 file in scripts/, which the agent can run.

  From the folder's file list and the shell code blocks in SKILL.md.

• Network

  Links to these hosts (documentation or services it may open):

  • cosmicpython.com
  • fastapi.tiangolo.com
  • alistair.cockburn.us
  • typing.python.org
  • github.com
  • nextjs.org
  • docs.pytest.org
  • vitest.dev

  From URLs in SKILL.md, links to its own repository left out.

• Credentials

  Names no API keys, tokens, secrets or passwords.

  From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

• Compatibility

  Claude Code 2.1.277+.

  From compatibility in the SKILL.md frontmatter.

Context cost

Architecture Patterns loads about 3.4k tokens when it runs, and up to ~6.9k if it reads all its reference files. Until then it costs about 92 tokens; SKILL.md has 982 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it

~92

When it runs · the whole SKILL.md, loaded when a task matches

~3.4k

With references · SKILL.md plus every file in references/, read only if the agent opens them

~6.9k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from yonatangross/orchestkit at commit 0ef71d2, republished under its MIT licence (© yonatangross). 982 words, ~3,389 tokens.

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.

allowed-tools

Read, Glob, Grep, WebFetch, WebSearch

compatibility

Claude Code 2.1.277+.

license

MIT

skills

scope-appropriate-architecture

user-invocable

false

disable-model-invocation

false

effort

high

metadata.owner-agent

backend-system-architect

metadata.category

document-asset-creation

metadata.version

2.1.0

metadata.author

OrchestKit

metadata.complexity

high

<!-- directive-density: intentional (teaches anti-patterns; NEVER markers describe real layering violations, not aspirational guidance) -->

# 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)

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.

# 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

© yonatangross, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 24 other files (scripts, references) in src/skills/architecture-patterns of yonatangross/orchestkit.

• SKILL.md
• checklists/solid-checklist.md
• metadata.json
• references/naming-conventions.md
• references/ork-delta.md
• references/structure-import-direction.md
• references/testing-naming-conventions.md
• rules/_sections.md
• rules/_template.md
• rules/backend-di.md
• rules/backend-layers.md
• rules/backend-repository.md
• rules/clean-dependency-rule.md
• rules/clean-hexagonal.md
• rules/clean-ports-adapters.md
• rules/right-sizing-decision.md
• rules/right-sizing-tiers.md
• rules/structure-conventions.md
• … and 7 more

Open the folder on GitHubat commit 0ef71d2