
python-clean-architecture
Claude Code plugin to scaffold, review, and refactor Python projects with clean code and architecture. Design principles and patterns implemented the Pythoni…
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
⚠ Unverified source (community-unclaimed, low activity) — reveal the prompt
⚠ Unverified source (community-unclaimed, low activity). Inspect the repo before letting your agent install it. Install and set up python-clean-architecture (claude-plugin project) into my current project. Found on https://claudeers.com/python-clean-architecture Repo: https://github.com/MKToronto/python-clean-architecture Homepage/docs: https://mktoronto.github.io/python-clean-architecture/ Detected install method: claude-plugin → /plugin install python-clean-architecture@MKToronto/python-clean-architecture Category: plugins. Platforms: cli, api. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: dormant; community-verified: false. Confirm the source before running anything.
⚠ Unverified / not recently updated — review before pasting a run-this config.
/plugin marketplace add MKToronto/python-clean-architecture /plugin install python-clean-architecture@MKToronto/python-clean-architecture
git clone https://github.com/MKToronto/python-clean-architecture
// compatibility
| Platforms | cli, api |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | Python |
python-clean-architecture — Claude Code Plugin
A Claude Code plugin that provides Clean Architecture guidance for Python/FastAPI projects. Scaffold, review, and refactor Python projects with design principles and Pythonic patterns — directly inside Claude Code.
Attribution
The principles, patterns, and architectural approach in this plugin are inspired by and synthesized from Arjan Codes' courses:
- The Software Designer Mindset — Seven core design principles (cohesion, coupling, abstractions, composition, creation/use separation, data-first design, simplicity)
- Pythonic Patterns — Classic GoF patterns reimagined for Python using Protocol, Callable, functools.partial, and closures
- Complete Extension — Three-layer FastAPI architecture (Routers → Operations → Database) with Protocol-based dependency injection
The specific Pythonic framing (Protocol-based DI, functional pattern progression, three-layer FastAPI architecture) originates from his teaching. This plugin distills those principles into actionable guidance for Claude Code — it is not a reproduction of course content. If you find this useful, consider supporting Arjan's work at arjancodes.com, github.com/arjancodes, and youtube.com/arjancodes.
Installation
- Add the marketplace:
/plugin marketplace add MKToronto/python-clean-architecture
- Install the plugin:
/plugin install python-clean-architecture@python-clean-architecture
- Restart Claude Code (
/exitthenclaude) to load the plugin.
Or download the repo and test locally without installing:
git clone https://github.com/MKToronto/python-clean-architecture.git
claude --plugin-dir /path/to/python-clean-architecture
Updating
/plugin marketplace update python-clean-architecture
Then restart Claude Code (/exit then claude).
Usage
Automatic (Skill)
The skill triggers automatically when you ask Claude Code to:
- "Scaffold a new FastAPI project"
- "Set up clean architecture"
- "Refactor to clean architecture"
- "Add a new endpoint / router / use case / repository"
- "Review my code structure"
- "Apply design patterns in Python"
- "Decouple my code"
- "Make my code testable"
Or mention: layered architecture, dependency injection, Protocol-based design, Pythonic design patterns.
Slash Commands
/review-architecture Review current directory
/review-architecture src/ Review a specific directory
/review-architecture app/main.py Review a specific file
The review checks:
- Architecture layers — Three-layer separation, no layer skipping, router as composition root
- 7 design principles — Cohesion, coupling, abstractions, composition, creation/use, data-first, simplicity
- 22 code quality rules — Naming, nesting, types, error handling, imports, structure
- Pythonic patterns — All 25 patterns checked (Strategy as Callable, Factory as dict mapping, Protocol over ABC, etc.)
Findings are reported by severity (Critical / Important / Suggestions) with file/line references and fix snippets.
All Commands
Review & Analysis:
/review-architecture [path] Full architecture review (standard or in-depth)
/review-api-design [path] Review REST API endpoints for HTTP conventions
/check-quality [path] Quick check against 22 code quality rules
/suggest-patterns [path] Recommend Pythonic design patterns for your code
/decouple [path] Find tight coupling and suggest DI improvements
Refactoring:
/make-pythonic [path] Refactor to Pythonic patterns (ABC→Protocol, if/elif→dict, etc.)
/extract-god-class [path] Find and split god classes into focused collaborators
Learning:
/learn-architecture [topic] Learn a design or architecture topic — theory + the Pythonic way + your code
/learn-architecture explains rather than edits. Pick any topic from the skill (the 7 principles, three-layer architecture, the 25 Pythonic patterns, GRASP, DDD, code smells, REST, Python craft) and get either a Lesson (structured walkthrough) or a Drill (interactive Socratic Q&A). Every topic is grounded twice: a canonical illustration from the bundled hotel-API example, plus an analysis of your code — whether the concept already applies, could apply, or should apply (a violation to fix). Each lesson ends with trade-offs, the "commonly confused with" comparison (Strategy vs State, Adapter vs Facade…), and self-check questions.
Scaffolding & Testing:
/scaffold-api <project-name> Generate a new FastAPI project with clean architecture
/add-endpoint <entity-name> Scaffold a new endpoint across all three layers
/scaffold-tests [path] Generate stub-based tests for existing operations
/scaffold-api generates a full project structure with Pydantic models, operations, routers, database layer, and tests. /add-endpoint adds a new entity to an existing project — it creates files across all three layers (router + operations + DB model + Pydantic models + tests) and wires them into main.py. /scaffold-tests generates DataInterfaceStub-based tests for existing operations without requiring a database.
What's Inside
python-clean-architecture/
├── .claude-plugin/
│ ├── plugin.json
│ └── marketplace.json
├── README.md
├── LICENSE
├── commands/
│ ├── review-architecture.md
│ ├── review-api-design.md
│ ├── check-quality.md
│ ├── suggest-patterns.md
│ ├── decouple.md
│ ├── make-pythonic.md
│ ├── extract-god-class.md
│ ├── learn-architecture.md
│ ├── scaffold-api.md
│ ├── scaffold-tests.md
│ └── add-endpoint.md
└── skills/clean-architecture/
├── SKILL.md
├── references/
│ ├── design-principles.md
│ ├── layered-architecture.md
│ ├── testable-api.md
│ ├── testing-advanced.md
│ ├── rest-api-design.md
│ ├── code-quality.md
│ ├── classes-and-dataclasses.md
│ ├── function-design.md
│ ├── data-structures.md
│ ├── error-handling.md
│ ├── monadic-error-handling.md
│ ├── types-and-type-hints.md
│ ├── project-organization.md
│ ├── context-managers.md
│ ├── decorators.md
│ ├── async-patterns.md
│ ├── pydantic-validation.md
│ ├── pattern-matching.md
│ ├── grasp-principles.md
│ ├── domain-driven-design.md
│ ├── pythonic-patterns.md
│ └── patterns/ (25 pattern files)
│ ├── strategy.md
│ ├── registry.md
│ ├── command.md
│ ├── builder.md
│ ├── repository.md
│ ├── cqrs.md
│ └── ...
└── examples/
└── fastapi-hotel-api/
├── main.py
├── models/
├── operations/
├── routers/
└── db/
Key Concepts
Three-Layer Architecture
Routers (API) → Operations (business logic) → Database (persistence)
Each layer depends only on the layer below. The router is the composition root where concrete DB implementations are injected into operations via the DataInterface Protocol.
Seven Design Principles
- High Cohesion — Single responsibility per unit
- Low Coupling — Minimize dependencies, Law of Demeter
- Depend on Abstractions — Protocol + Callable for DI
- Composition over Inheritance — Never mixins, shallow hierarchies only
- Separate Creation from Use — Dict mapping, creator functions, one composition root
- Start with the Data — Information Expert, fix data structures first
- Keep Things Simple — DRY, KISS, YAGNI (but avoid hasty abstractions)
Pythonic Pattern Defaults
- Protocol over ABC (unless shared superclass state needed)
functools.partialover wrapper classes- Closures over factory class hierarchies
Callabletype aliases over single-method abstract classes- Dict mapping over if/elif chains
- Readability over dogmatic functional purity
25 design patterns implemented the Pythonic way:
Core Patterns:
- Strategy —
Callabletype alias, pass functions as args - Abstract Factory — Tuples of functions +
functools.partial - Bridge —
Callabletype alias replaces abstract reference - Command — Functions returning undo closures
- Pub/Sub — Dict-based
subscribe(event, handler)/post_event(event, data) - Registry —
dict[str, Callable]mapping +**kwargsunpacking - Template Method — Free function + Protocol parameter
- Pipeline —
functools.reducefor composition - Callback / Wrapper / Builder — Functional patterns for event handling, interface translation, and configuration
Extended Patterns:
- Value Objects — Subclass built-in types with
__new__validation, or frozen dataclass - Event Sourcing — Immutable events, append-only EventStore, projection functions
- CQRS — Separate write model + read projection, projector function after writes
- Builder — Fluent API with
Selfreturn type,.build()returns frozen product - Unit of Work — Context manager wrapping transaction: commit on success, rollback on error
- Singleton — Module-level instance (preferred), or metaclass with
_instancesdict - State — Protocol-based state objects, context delegates to current state
- Adapter — Protocol interface +
functools.partialfor single-method adaptation - Facade — Simplified interface class,
functools.partialto bind dependencies - Retry —
@retrydecorator with exponential backoff, fallback strategies - Lazy Loading —
functools.cache,cached_property, generators,__getattr__ - Repository — Protocol interface for CRUD, concrete implementations per storage backend
- Fluent Interface — Methods return
selffor chaining, domain-specific verbs for readability - Plugin Architecture — Config-driven creation,
importlibauto-discovery, self-registering modules
Example Output
See the full example review — a color-coded /review-architecture run against a test bookstore-api project (15 findings with before/after code).
Also available for
- Codex CLI — python-clean-architecture-codex (agent skill for Codex)
// faq
What is python-clean-architecture?
Claude Code plugin to scaffold, review, and refactor Python projects with clean code and architecture. Design principles and patterns implemented the Pythonic way. Inspired by Arjan Codes. . It is open-source on GitHub.
Is python-clean-architecture free to use?
python-clean-architecture is open-source under the MIT license, so it is free to use.
What category does python-clean-architecture belong to?
python-clean-architecture is listed under plugins in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/python-clean-architecture)
// retro hit counter
[](https://claudeers.com/python-clean-architecture)
// reviews
// guestbook
// related in Claude Plugins
A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.
Claude Code is an agentic coding tool that lives in your terminal, understands your codebase, and helps you code faster by executing routine tasks, explainin…
"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/
financial-services — a Claude ecosystem project on GitHub.