# Ahgraber Skills Python Design Modularity > Python Design and Modularity - Skill: `tomevault-io/ahgraber-skills-python-design-modularity` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/ahgraber-skills-python-design-modularity` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/ahgraber-skills-python-design-modularity/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/ahgraber-skills-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` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/ahgraber) — claim your Tome and manage your conversions.