/modularity — Modular Design Enforcement

The Rules

Rule 1: File Size Limits

Rule 2: Single Responsibility Per File

• "What does this file do?" must have a one-sentence answer.
• If the answer contains "and," the file does too much — split it.
• If two developers could work on different parts of the file simultaneously on unrelated tasks, it should be two files.

Rule 3: Change Locality

• STOP. The design has a coupling problem.
• Identify which files are changing for the same reason — they should share an abstraction.
• Identify which files are changing for different reasons — they need a cleaner interface between them.

Rule 4: Interface-First Design

1. Define the module's public interface — what it exposes to consumers.
2. Define its dependencies — what it imports/requires.
3. The interface should be understandable without reading the implementation.
4. Consumers should never need to know implementation details.

Rule 5: Context-Window-Aware Decomposition

"Can Claude read this file, its tests, and the files it directly depends on — all at once — without exceeding context or needing to compact?"

Rule 6: Dependency Direction

• Dependencies flow ONE direction (no circular imports).
• High-level modules depend on abstractions, not low-level details.
• If module A imports module B and module B imports module A, extract the shared concern into module C.

Rule 7: Co-location

WRONG (layer-based):
  controllers/user.ts
  controllers/order.ts
  services/user.ts
  services/order.ts
  models/user.ts
  models/order.ts

RIGHT (feature-based):
  user/controller.ts
  user/service.ts
  user/model.ts
  order/controller.ts
  order/service.ts
  order/model.ts

user/

Applying This Skill

During Planning (brainstorming / writing-plans)

• Every planned file has a one-sentence responsibility
• No planned file exceeds the soft line limit for its type
• The file structure is organized by feature/domain, not layer
• Any single task in the plan touches at most 3-5 source files
• Every module's public interface is defined before its implementation
• Dependencies flow in one direction — no circular imports
• The context test passes: any task requires reading <1500 lines total

During Implementation (executing-plans)

• Check file size after each commit. If approaching the soft limit, split NOW.
• If a function grows beyond 30 lines, extract sub-functions or a helper module.
• If you're adding a new feature and touching >5 files, stop and ask: "Is there a missing abstraction?"

During Review (code-review / receiving-code-review)

• No file exceeds the hard limit
• Each file's responsibility is clear and singular
• Change locality: the PR touches a reasonable number of files
• No circular dependencies introduced
• New modules have well-defined interfaces

When Modifying Existing Code

• You are NOT required to fix all violations in unrelated files.
• You ARE required to not make violations worse.
• If the file you're modifying already exceeds the hard limit, include a split as part of your change.
• If your change would push a file past the soft limit, split first.

Splitting Strategies

auth.ts

auth/login.ts

auth/register.ts

auth/token.ts

api.ts

api/routes.ts

api/middleware.ts

api/validation.ts

utils.ts

string-utils.ts

date-utils.ts

array-utils.ts

Anti-Patterns

Rationalization Prevention