AGENT SKILL

ams-clean-architecture

暂无简介

License 许可
MIT
所属仓库
TanNhatCMS/jarvis
最近更新
2026-11-07
Stars
★ 0
Forks
1

03 SKILL.md 正文

Clean Architecture

Overview

Clean Architecture (and its cousin Hexagonal/Ports-and-Adapters) is a dependency discipline: business logic sits at the center, depending on nothing; infrastructure (databases, frameworks, UI) sits at the edges, depending inward through abstractions. The result: domain logic testable without databases or frameworks, and infrastructure replaceable without touching the domain.

The through-line: the Dependency Rule — source code dependencies point inward only. Frameworks are details.

When to use

  • Structuring a new application for long-term maintainability.
  • Untangling business logic from framework/database coupling.
  • Making domain logic unit-testable without infrastructure.
  • Reviewing layering violations in a codebase.
  • Deciding where new code belongs in a layered app.

Core concepts

  • The Dependency Rule. Inner layers know nothing of outer layers. Domain → (nothing). Application → domain. Infrastructure → application + domain (implements their interfaces). A use case never imports a database driver; the database adapter implements the use case's repository interface.
  • Layers. Entities (domain objects + business rules) → Use Cases / Application services (orchestrate entities toward user goals) → Interface Adapters (controllers, presenters, repository implementations) → Frameworks & Drivers (DB, web framework, UI). Name them per your stack, but keep the direction.
  • Ports and adapters. The application defines ports (interfaces: OrderRepository, PaymentGateway); infrastructure provides adapters (PostgresOrderRepository, StripePaymentGateway). The app never names a concrete infrastructure class — only the port.
  • Dependency inversion in practice. High-level modules define the abstractions they need; low-level modules implement them. Composition root (main/startup) wires concrete adapters. This inverts the "natural" direction where app code calls the DB directly.
  • Screaming architecture. The top-level structure should say what the app does (orders, billing, shipping) not what it's built with (controllers, models, utils). Package by feature/ component first, layer within.
  • Testability as a side effect. When the domain depends on nothing, unit tests need no mocks of infrastructure — pure, fast, deterministic. Adapters get thin integration tests against real infrastructure.

Practical workflow

  1. Identify the core domain. What are the business rules that must survive a framework change? That's the center. Everything else is a detail.
  2. Define ports from the application's needs. What does the use case need? (findOrderById, chargeCard) — interfaces shaped by the caller, not by the database's convenience.
  3. Write the domain + use cases first. Pure logic, no framework imports, tested without infrastructure. This is the valuable 80% — build it where it's cleanest.
  4. Add adapters at the edges. Controllers translate HTTP → use-case calls; repositories translate domain ↔ persistence; gateways wrap external APIs. Adapters are thin and boring.
  5. Wire at the composition root. main/startup creates concrete adapters and injects them. Only here does the app know it's Postgres and not SQLite.
  6. Enforce the rule. Architecture tests (dependency checkers: no import from domain to infrastructure) in CI. The rule erodes without enforcement — one convenient shortcut at a time.

Layer sketch:

src/
├── domain/            # entities, value objects, domain services, domain events
│   └── order/         #   Order, Money, OrderPlaced — zero external imports
├── application/       # use cases + ports (interfaces)
│   └── order/         #   PlaceOrderUseCase, OrderRepository (port), PaymentGateway (port)
├── adapters/          # implementations of ports + delivery mechanisms
│   ├── persistence/   #   PostgresOrderRepository implements OrderRepository
│   ├── web/           #   OrderController → PlaceOrderUseCase
│   └── payment/       #   StripePaymentGateway implements PaymentGateway
└── main.ts            # composition root: wires adapters into use cases

Common pitfalls

  • Interface-per-class cargo cult. Creating IOrderService for every class "for clean architecture." Ports exist at architectural boundaries (app ↔ infrastructure), not between every two classes.
  • Anemic use cases, fat adapters. All logic leaking into controllers or repositories while "use cases" just delegate. The application layer should own orchestration and business flow.
  • Leaky abstractions. Repository interfaces shaped like the ORM (findBySql, lazy-loading entities) — the infrastructure dictating terms. Ports are designed by the application.
  • Over-layering simple apps. Four layers + DTOs + mappers for a CRUD admin panel. Apply the discipline proportionally — the Dependency Rule matters most where logic is complex and long-lived.
  • DTO/mapper explosion. Six near-identical types (entity, DTO, view model, …) with manual mappers nobody maintains. Map at boundaries where shapes genuinely differ; don't multiply types ritually.
  • No enforcement. The architecture documented in a wiki, violated in the code within a month. Dependency-rule tests in CI or it didn't happen.
  • Framework in the domain. ORM decorators on entities, HTTP types in use cases — the "details" leaking inward. Keep the center ignorant; adapt at the edges.

04 同仓库更多 Skills

TanNhatCMS
TanNhatCMS/jarvis

web-scrape

Turn web pages into LLM-ready markdown via the Firecrawl API (renders JS, anti-bot handling). Use when browser_open/fetch fails on JS-heavy pages, or when you need clean markdown/structured extraction from a site. Requires FIRECRAWL_API_KEY.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

design-taste-frontend

tasteskill v2, the anti-slop frontend skill. Art direction for websites, distilled from a study of 247 curated gallery sites (One Page Love, Awwwards Sites of the Day). Deals researched directions (idea, composition, type, palette, photographs, section blueprints) from a library, enforces a strict no-slop house style with a real-browser inspector, and runs a look-and-fix loop on screenshots. Use this whenever you build, design, redesign, restyle, polish or review a landing page, marketing site, portfolio, product page, one-pager, hero or any public-facing web page, in any stack (HTML/CSS, React, Next.js, Vue, Svelte, Astro, Tailwind) — also when the user says a page looks generic, templated, "AI-made", sloppy, or asks to make it look designed, premium, award-level or less like every other site. Not for dashboards or app screens.

★ 0
TanNhatCMS
TanNhatCMS/jarvis

test-driven-development

Use when implementing any feature or bugfix, before writing implementation code

★ 0
TanNhatCMS
TanNhatCMS/jarvis

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

★ 0
TanNhatCMS
TanNhatCMS/jarvis

requesting-code-review

Use when completing tasks, implementing major features, or before merging to verify work meets requirements

★ 0
TanNhatCMS
TanNhatCMS/jarvis

brainstorming

You MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).

★ 0