ahgraber/python-design-modularity

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