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
.cursor/rules/module-shape.mdcWhat 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-shapeand 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.mdcFrontmatter: description, globs, alwaysApply
1Plugin marketplace
/plugin marketplace add rohitg00/pro-workflow/plugin install pro-workflow@pro-workflow2Manually: put the files in place
.claude/rules/module-shape.mdThe paths frontmatter field limits the files: move globs from the source into paths
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.github/instructions/module-shape.instructions.mdThe applyTo field sets which files it applies to: move globs from the source into applyTo
Manually: put the files in place
.devin/rules/module-shape.mdManually: put the files in place
.clinerules/module-shape.mdStep 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