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 (
/exit then claude) 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
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
