modular-code

Modular Code Organization

⭐2.2kstars🔀157forks📁View on GitHub🕐Updated Jan 10, 2026

When & Why to Use This Skill

This Claude skill provides comprehensive guidelines and actionable strategies for organizing Python code into modular, maintainable files. It optimizes codebases for both human readability and AI-assisted development by enforcing ideal file size limits (150-500 lines) and providing clear refactoring patterns to prevent cognitive overload and tool performance issues.

Use Cases

  • Refactoring monolithic Python files that exceed 1000+ lines into smaller, domain-specific modules to improve maintainability.
  • Optimizing codebase structure to prevent AI context truncation and improve the accuracy of AI-assisted coding tools by staying within the 'sweet spot' for context windows.
  • Establishing standardized file size and naming conventions for team-based software development projects to ensure architectural consistency.
  • Identifying natural split points in complex logic based on domain concepts, abstraction layers, or I/O boundaries to create a cleaner package structure.
namemodular-code
descriptionModular Code Organization
user-invocablefalse

Modular Code Organization

Write modular Python code with files sized for maintainability and AI-assisted development.

File Size Guidelines

Lines Status Action
150-500 Optimal Sweet spot for AI code editors and human comprehension
500-1000 Large Look for natural split points
1000-2000 Too large Refactor into focused modules
2000+ Critical Must split - causes tooling issues and cognitive overload

When to Split

Split when ANY of these apply:

  • File exceeds 500 lines
  • Multiple unrelated concerns in same file
  • Scroll fatigue finding functions
  • Tests for the file are hard to organize
  • AI tools truncate or miss context

How to Split

Natural Split Points

  1. By domain concept: auth.py → auth/login.py, auth/tokens.py, auth/permissions.py
  2. By abstraction layer: Separate interface from implementation
  3. By data type: Group operations on related data structures
  4. By I/O boundary: Isolate database, API, file operations

Package Structure

feature/
├── __init__.py      # Keep minimal, just exports
├── core.py          # Main logic (under 500 lines)
├── models.py        # Data structures
├── handlers.py      # I/O and side effects
└── utils.py         # Pure helper functions

DO

  • Use meaningful module names (data_storage.py not utils2.py)
  • Keep __init__.py files minimal or empty
  • Group related functions together
  • Isolate pure functions from side effects
  • Use snake_case for module names

DON'T

  • Split files arbitrarily by line count alone
  • Create single-function modules
  • Over-modularize into "package hell"
  • Use dots or special characters in module names
  • Hide dependencies with "magic" imports

Refactoring Large Files

When splitting an existing large file:

  1. Identify clusters: Find groups of related functions
  2. Extract incrementally: Move one cluster at a time
  3. Update imports: Fix all import statements
  4. Run tests: Verify nothing broke after each move
  5. Document: Update any references to old locations

Current Codebase Candidates

Files over 2000 lines that need attention:

  • Math compute modules (scipy, mpmath, numpy) - domain-specific, may be acceptable
  • patterns.py - consider splitting by pattern type
  • memory_backfill.py - consider splitting by operation type

Sources