ams-clean-architecture
暂无简介
- License 许可
- MIT
- 最近更新
- 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
- Identify the core domain. What are the business rules that must survive a framework change? That's the center. Everything else is a detail.
- 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. - 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.
- Add adapters at the edges. Controllers translate HTTP → use-case calls; repositories translate domain ↔ persistence; gateways wrap external APIs. Adapters are thin and boring.
- 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. - Enforce the rule. Architecture tests (dependency checkers: no
importfrom 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
IOrderServicefor 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
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.
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.
test-driven-development
Use when implementing any feature or bugfix, before writing implementation code
systematic-debugging
Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
requesting-code-review
Use when completing tasks, implementing major features, or before merging to verify work meets requirements
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).