Skip to main content
rule CX Codex

module-shape — Claude Code rule: module design and setup

The module-shape rule keeps public module APIs small while hiding complexity inside. Use it when designing modules or reviewing tests and dependencies.

MIT ★ 2,966 updated 2026-09-29

Install into Cursor · Manually: put the files in place All methods and platforms ↓
.cursor/rules/module-shape.mdc
Open on GitHub

What module-shape does

The rule asks for a small public surface with meaningful work behind it. Algorithms, branching, state, retries, and caching stay inside the module instead of leaking through many exports. Before adding an export, check whether an existing one can take the behavior; before removing one, consider whether the module should be folded into its only caller.

Pass external dependencies into business logic rather than constructing clients, loading configuration, or reading the clock there. Return values instead of mutating inputs. Mocks belong at system boundaries such as third-party HTTP APIs, databases without a real test instance, clocks, random sources, and the filesystem. If business logic creates an external client itself, the rule treats that as a design error. Boundary mocks should match concrete endpoints so each test exposes the calls it uses.

What it helps with

  • shrink a module’s public API
  • hide branching and state behind a module boundary
  • inject external clients through function arguments
  • spot mocks for internal code during review

Example prompts for the agent

  • Review this module using module-shape and flag exports that do not earn their place.
  • Rewrite this function so the external client arrives as an argument and the result is returned.
  • Check the tests for mocks of internal classes and move mocking to system boundaries.

How to install module-shape

Manually: put the files in place

.cursor/rules/module-shape.mdc

Frontmatter: description, globs, alwaysApply

Step by step, with commands for each platform: Cursor rules: .mdc files, four modes and what replaced .cursorrules

Questions about module-shape

How do I install module-shape in Claude Code?

Add the marketplace with /plugin marketplace add rohitg00/pro-workflow, install the plugin with /plugin install pro-workflow@pro-workflow, then place the rule at .claude/rules/module-shape.md.

What does the module-shape rule do?

It guides module design around a narrow public API, hidden internal complexity, injected dependencies, returned values, and mocks at system boundaries.

Which dependencies may be mocked under this rule?

Mock third-party HTTP APIs, databases when a real test instance is unavailable, the clock, random sources, and the filesystem. Internal modules and classes should be instantiated directly.

Source text

module-shape.mdc · MIT
---
description: Prefer modules with a narrow public surface and a thick internal implementation. Inject external dependencies at the boundary. Mock only at system edges.
globs:
alwaysApply: true
---

# Module Shape

## Surface vs. depth

A module's **surface** is every symbol a caller can touch: exported
functions, class methods, config parameters, flags. A module's **depth**
is everything hidden behind that surface: algorithms, branching, state
machines, retries, caching.

Aim for **narrow surface, thick depth**. A three-method module that hides
a hundred lines of branching is strong. A thirty-method module whose
methods each forward a single call to a dependency is weak — it leaks
complexity upward without doing work.

When adding a public export, first ask whether an existing one can absorb
the new behavior. When removing, first ask whether the module has gone
shallow and should be inlined into its only caller.

## Dependency direction

Accept dependencies as arguments. Do not construct external clients,
fetch configuration, or read the clock inside business logic.

```ts
// strong: the caller owns lifecycle, the test swaps the gateway
function chargeOrder(order, gateway) { return gateway.charge(order.total); }

// weak: business logic welds itself to a vendor and a credential source
function chargeOrder(order) {
  const gateway = new AcmePay(process.env.ACME_KEY);
  return gateway.charge(order.total);
}
```

Return values, do not mutate inputs. `computeDiscount(cart) -> Discount`
beats `applyDiscount(cart) -> void`. Pure returns are traceable; hidden
mutation is not.

## Where mocks belong

Mock at system boundaries only: third-party HTTP APIs, databases when a
real test instance is not available, the clock, random sources, the
filesystem when tests must stay hermetic.

Do not mock your own modules, internal classes, or anything you can
instantiate cheaply. A test whose setup is twenty lines of mock wiring is
telling you the module underneath is too shallow — fix the shape, not
the test.

At the real boundaries, prefer **endpoint-shaped** mocks over generic
ones. `{ getUser(id), createOrder(data) }` beats `{ request(path, opts) }`
because each mock returns one shape, test setup contains no conditionals,
and a reader can see which calls a test exercises.

## Checklist when reviewing

- [ ] Does every public symbol justify its presence? Delete or merge the rest.
- [ ] Are dependencies passed in, or constructed inside?
- [ ] Do tests mock anything the module itself owns? If yes, the shape is wrong.

© Rohit Ghumare · MIT · rohitg00/pro-workflow

Similar IDE rules

All IDE rules for Code review and refactoring →

From the same set83

The whole set →
file-watcher file-watcher configures Claude Code hooks to react to changes in configuration files, dependencies, and environment files. CX Codex +1 ★ 2,966repo stars commit Runs project checks, reviews staged changes, and creates a focused git commit. Use it when a change is ready to be recorded. CX Codex +1 ★ 2,966repo stars mcp-audit mcp-audit analyzes connected MCP servers for token overhead, redundancy, and unused configurations. Run when sessions slow down or before connecting a new server. CX Codex +1 ★ 2,966repo stars tdd tdd guides Claude Code through a strict test-driven development loop: write a failing test, pass it with minimal code, and clean up. CX Codex +1 ★ 2,966repo stars improve-architecture improve-architecture audits code structure, identifies tangles in boundaries and dependencies, and proposes a ranked list of minimal moves that relieve the strain—no rewrite, only a plan you approve first. CX Codex +1 ★ 2,966repo stars parallel-worktrees parallel-worktrees — a skill for Claude Code that creates isolated git worktrees for parallel coding sessions. While tests or builds run in one window, start a new task in another without waiting or switching context. CX Codex +1 ★ 2,966repo stars compact-guard compact-guard is a Claude Code skill that records task state before context compaction and helps restore it afterward. Run it before /compact or when an auto-compaction warning appears. CX Codex +1 ★ 2,966repo stars handoff Generates a structured handoff document for passing work to another Claude session or your future self. Records status, decisions, learnings, and a resume point. CX Codex +1 ★ 2,966repo stars

Project sponsors

Companies that keep this analytics open