playbooks

home / skills / partme-ai / full-stack-skills / ddd-clean-architecture

ddd-clean-architecture skill

/skills/ddd-clean-architecture

This skill provides guidance on clean architecture, outlining layer separation, dependency rules, and architectural patterns to structure robust applications.

npx playbooks add skill partme-ai/full-stack-skills --skill ddd-clean-architecture

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
703 B
---
name: ddd-clean-architecture
description: Provides comprehensive guidance for clean architecture including layer separation, dependency rules, and architectural patterns. Use when the user asks about clean architecture, needs to implement clean architecture principles, or structure applications with clean architecture.
license: Complete terms in LICENSE.txt
---

## When to use this skill

Use this skill whenever the user wants to:
- [待完善：根据具体工具添加使用场景]

## How to use this skill

[待完善：根据具体工具添加使用指南]

## Best Practices

[待完善：根据具体工具添加最佳实践]

## Keywords

[待完善：根据具体工具添加关键词]

Overview

This skill provides practical, implementation-focused guidance for applying Clean Architecture principles across application stacks. It explains layer separation, dependency rules, common patterns, and actionable steps to structure code for maintainability and testability. The guidance is language-agnostic but includes Python-centric examples and recommendations.

How this skill works

The skill inspects architecture decisions and suggests layer boundaries (entities, use cases, interfaces/adapters, frameworks) and dependency directions to enforce separation of concerns. It recommends concrete patterns for ports-and-adapters, dependency inversion, and data flow, and outlines folder/module organization and testing strategies. It highlights anti-patterns, migration steps for legacy code, and code-level practices to keep business rules independent from frameworks.

When to use it

  • Starting a new project that needs long-term maintainability and testability
  • Refactoring a monolith or legacy codebase to reduce coupling and improve modularity
  • Designing APIs, services, or libraries where business rules must be isolated from delivery concerns
  • Preparing codebases for easier automated testing and CI/CD
  • Onboarding teams to a consistent architecture approach across multiple services

Best practices

  • Define clear layer responsibilities: Entities (core models), Use Cases (business rules), Interface Adapters (controllers/gateways), Frameworks/Drivers (DB, web)
  • Always invert dependencies so higher-level layers do not depend on lower-level implementations
  • Keep models used by domain logic free of frameworks or persistence annotations
  • Use small, focused use-case classes or interactors with explicit input/output models
  • Write unit tests for use cases and entities; use integration tests for adapters and frameworks
  • Migrate iteratively: extract use cases and interfaces, then replace implementations behind stable ports

Example use cases

  • Implementing a payment flow where business rules must be verifiable independent of payment provider SDKs
  • Refactoring an API service so controllers only orchestrate use cases and contain no business logic
  • Building a CLI tool whose core logic can be reused later in a web or background worker context
  • Creating a plugin-friendly architecture where adapters for different storage or messaging systems can be swapped without changing domain code
  • Designing microservices where each service encapsulates its domain and exposes ports for integration

FAQ

How do I start applying Clean Architecture to an existing codebase?

Start by identifying core business logic and extracting it into domain entities and use-case classes. Introduce interfaces (ports) and move framework-specific code into adapters behind those interfaces. Incrementally replace calls to concrete implementations with interface calls.

Should repositories or ORMs be part of the domain model?

No. Keep persistence concerns in adapter layers. Define repository interfaces in the domain/use-case layer and implement them in an infrastructure adapter that uses the ORM.

How granular should layers and modules be?

Favor small, cohesive modules that reflect business boundaries. Avoid excessive fragmentation; group related use cases and entities logically so navigation and tests remain straightforward.