python-design-modularity

Original：🇺🇸 English

Translated

Use when designing module boundaries, planning refactors, or reviewing architecture in Python codebases. Also use when facing tangled dependencies, god classes, deep inheritance hierarchies, unclear ownership, or risky structural changes.

1installs

Sourceahgraber/skills

Added on2026-02-07

NPX Install

npx skill4agent add ahgraber/skills python-design-modularity

SKILL.md Content

View Translation Comparison →

Python Design and Modularity

Overview

Readability-first design with explicit module contracts. Keep control flow, data movement, and ownership boundaries visible so code stays maintainable and safe to change.

Treat these recommendations as preferred defaults. When a default conflicts with project constraints, suggest a better-fit alternative and call out tradeoffs and compensating controls (tests, observability, migration, rollback).

When to Use

Restructuring modules, packages, or ownership boundaries
Breaking apart god classes or deeply nested hierarchies
Choosing between composition and inheritance
Applying Functional Core / Imperative Shell separation
Planning a refactor that touches multiple modules
Reviewing code for readability or architectural clarity

When NOT to use:

Pure performance optimization — see
```
python-concurrency-performance
```
Error handling and resilience patterns — see
```
python-errors-reliability
```
Type contracts and protocol design — see
```
python-types-contracts
```
One-off script or throwaway code with no maintenance horizon

Quick Reference

Keep control flow and data movement explicit.
Keep module ownership and invariants explicit.
Prefer composition by default.
Apply Functional Core / Imperative Shell where it improves testability and separation of concerns.
Separate behavior changes from structural refactors — never mix in the same commit.

Common Mistakes

Refactoring behavior and structure simultaneously — conflates two kinds of risk, makes rollback harder, and obscures review. Do one, then the other.
Reaching for inheritance first — deep hierarchies couple unrelated concerns and make reasoning non-local. Default to composition; inherit only when the "is-a" relationship is genuinely stable.
Hidden module coupling — importing implementation details across boundaries creates invisible contracts. Expose explicit public APIs and keep internals private.
Premature abstraction — extracting a shared interface before the second or third concrete use leads to wrong abstractions that are expensive to undo. Wait for duplication to reveal the real seam.
Ignoring the Functional Core / Imperative Shell split — mixing I/O with business logic makes unit testing painful and increases the blast radius of changes. Push side effects to the edges.

Scope Note

Treat these recommendations as preferred defaults for common cases, not universal rules.
If a default conflicts with project constraints or worsens the outcome, suggest a better-fit alternative and explain why it is better for this case.
When deviating, call out tradeoffs and compensating controls (tests, observability, migration, rollback).

Invocation Notice

Inform the user when this skill is being invoked by name:
```
python-design-modularity
```
.

References

```
references/design-rules.md
```

references/readability-and-complexity.md

```
references/module-boundaries.md
```
```
references/functional-core-shell.md
```
```
references/refactor-guidelines.md
```