AgentSkillsCN

python-design-modularity

适用于在 Python 代码库中设计模块边界、规划重构，或审查架构时使用。同样适用于面对错综复杂的依赖关系、上帝类、深层继承层次、所有权不明，或面临风险的结构性变化时使用。

SKILL.md
--- frontmatter
name: python-design-modularity
description: 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.

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