reference clean architecture

    1

    Implement Clean Architecture and hexagonal patterns to decouple business logic from frameworks and databases.

    Free

    2 usesSecurity scanned

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    reference clean architecture

    Example session with this skill installed

    I have a fat FastAPI router handling user registration, DB commits, and email sending. Help me refactor this into Clean Architecture layers.

    • Read your context and instructions
    • Compiled the reference clean architecture

    I will refactor the user registration logic by separating the HTTP concerns from the business rules and database persistence.

    User Registration Refactor

    LayerFile / ComponentResponsibility
    Entitydomain/user.pyPure Python dataclass for User with password validation logic. No ORM.
    Repositoryinfra/user_repo.pyUserRepository interface and SqlUserRepository implementation using SQLAlchemy.
    Use Caseapp/register_user.pyOrchestrates the flow: check existing, hash password, save via UoW, trigger email.
    Adapterapi/v1/auth.pyFastAPI router that validates UserRegisterRequest and calls the use case.
    
    # use_cases/register_user.py
    from dataclasses import dataclass
    from domain.user import User
    from infra.unit_of_work import UnitOfWork
    
    def register_user_use_case(uow: UnitOfWork, email: str, raw_password: str) -> User:
        with uow:
            if uow.users.get_by_email(email):
                raise UserAlreadyExistsError(email)
            
            user = User.create(email=email, password=raw_password)
            uow.users.save(user)
            # Transaction commits here on successful exit
            return user
    

    Next steps

    1. Define the UserRepository Protocol/Interface to keep the Use Case decoupled from SQLAlchemy.
    2. Implement the UnitOfWork context manager to wrap the db.session lifecycle.
    3. Configure import-linter in your .importlinter file to prevent domain from importing infra.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    When backend services grow, they often collapse into "fat controllers" and spaghetti logic that is impossible to test or refactor. This skill provides a strict blueprint for implementing Clean Architecture, hexagonal design, and ports-and-adapters patterns to decouple business logic from frameworks and databases.

    What it does

    • Enforce Layering Rules by defining strict dependency directions between Entities, Use Cases, Repositories, and Adapters.
    • Implement Unit of Work patterns to manage database transactions at the use-case boundary rather than the repository level.
    • Design Boundary Enforcement strategies using stack-specific tools like import-linter, ArchUnit, or eslint-plugin-boundaries to prevent architectural drift.
    • Scaffold New Services with consistent naming conventions and directory structures for Python, TypeScript, Java, and Go.
    • Migrate Legacy Code using the strangler-fig pattern to incrementally move logic out of monolithic files without risky rewrites.

    How it works

    1. Layer Assignment starts by placing every new or existing file into one of the four architectural layers based on its imports and responsibilities.
    2. Boundary Tooling setup involves configuring automated CI checks that fail if an inner layer (like an Entity) attempts to import an outer layer (like an ORM).
    3. Transaction Mapping moves commit logic from repositories to a Unit of Work context manager called by the Use Case.
    4. Consistency Audit verifies that naming conventions for Entities, Repositories, and DTOs match the domain model.

    Frameworks & tools

    Language-agnostic logic with specific implementation guides for Python (FastAPI, SQLAlchemy), TypeScript (NestJS, TypeORM), Java (Spring Boot), and Go. Uses import-linter, dependency-cruiser, and ArchUnit for automated enforcement.

    Why this beats prompting it yourself

    Most LLMs default to "active record" patterns and "fat controllers" because that is what appears most in public training data. This skill forces a professional, decoupled architecture that stays maintainable as the project scales, preventing the common trap of leaking database details into business rules.

    Use cases

    • Decoupling a core business engine from a specific framework like FastAPI or Express.
    • Adding a CLI or Cron entry point to a service that was originally built only for HTTP.
    • Breaking down a 2000-line "fat router" file into testable, single-purpose use cases.
    • Establishing architectural standards for a new monorepo that multiple teams will contribute to.

    Known limitations

    Not suitable for small scripts, single-file CLI utilities, or throwaway prototypes where layering overhead exceeds the benefits. Requires manual configuration of third-party linter tools in CI.

    Not for small scripts or prototypes. Requires configuring external tools like import-linter or ArchUnit in CI. Does not support pure frontend/UI architecture.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before any payment.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    2 uses

    Times used to date

    Free forever

    No account required to browse

    Trust & safety

    Security scan

    Security scan passed 28 days ago

    • Free with an Agensi account

    Permissions

    Read Files
    Listed28 days ago

    What's inside

    Frequently Asked Questions

    This skill solves the 'spaghetti code' problem by enforcing strict separation between business rules and external tools like databases or APIs, making your codebase significantly easier to test, maintain, and swap out frameworks later.

    The skill provides implementation guides for Python (FastAPI), TypeScript (NestJS), Java (Spring Boot), and Go, and it can be adapted to any language that supports object-oriented or functional programming patterns.

    Unlike general prompts that often default to simple 'Active Record' patterns, this skill is specifically tuned to resist architectural drift by configuring automated enforcement tools like ArchUnit or import-linter in your CI/CD pipeline.

    You will receive a complete set of architectural templates, directory structure blueprints, configuration files for boundary-enforcement tools, and step-by-step migration strategies for legacy code.

    While this skill handles the logic and structure, you will need to manually install and configure the recommended third-party linting tools (such as dependency-cruiser or ArchUnit) within your specific environment to enable automated enforcement.

    This skill is designed for complex, long-lived backend services; it is not recommended for simple scripts, prototypes, or single-purpose CLI tools where the overhead of multiple layers would outweigh the benefits.

    New in APIs & Backend