🧠 Cursor Rule — Break Down Long Functions into Composable Utilities

Summary

Large functions become rigid, error-prone, and difficult to test. Break them down into small, focused utilities that each solve a single problem. Use Replit Agent runtime checks to confirm unchanged behavior after each extraction step.

Objectives

• Reduce cognitive load by shrinking function complexity
• Improve testability through isolated utilities
• Reuse logic across modules without duplication
• Maintain external behavior while modernizing internals

Principles

1. A function should express intention, not implementation details.

2. Pure logic (no side effects) should be extracted first because it is safest to refactor.

3. Keep the public interface unchanged during refactors so external dependencies remain stable.

4. Refactor incrementally—extract and validate in small steps rather than rewriting everything.

Implementation Pattern

Below is the recommended step-by-step workflow for breaking down long functions:

Step 1 — Identify Responsibility Clusters

Look for natural boundaries inside the long function:

• Parsing input
• Validation
• Transformation or computation
• Side effects (DB writes, API calls)
• Response formatting

Each cluster becomes a potential utility.

Step 2 — Extract Pure Logic First

Pure transforms are predictable and testable.

Example extractions:

• price = applyTax(total)
• formatted = normalizeInput(raw)

These utilities require no mocks and rarely break.

Step 3 — Extract Side Effects Into Named Adapters

Side-effect steps become wrappers like:

• saveOrder(model)
• sendNotification(event)

This keeps your logic layer clean.

Step 4 — Recompose the Original Function

Rewrite your main function in readable, high-level steps that call your new utilities.

The goal: The top-level function reads like documentation.

Step 5 — Validate Behavior With Runtime Checks

After each extraction:

• Compare before/after outputs
• Use console logs or Agent traces
• Ensure unchanged edge-case handling
• Confirm exceptions still propagate correctly

Step 6 — Add Tests for Each Extracted Utility

Unit tests validate each utility independently.

Integration tests ensure the recomposed function still behaves the same.

Anti-Pattern (Before)

'function processOrder(input) {

// parse

// validate

// compute totals

// apply discounts

// enrich with customer data

// call pricing service

// write to database

// publish event

// format response

}'

Problems:

• Impossible to test parts individually
• Debugging requires stepping through entire flow
• Small changes risk unintended side effects
• Logic cannot be reused by other modules

Recommended Pattern (After)

'function parseOrder(input) { ... }

function validateOrder(parsed) { ... }

function computeTotals(parsed) { ... }

function enrichCustomer(model) { ... }

function persistOrder(model) { ... }

function buildResponse(model) { ... }

function processOrder(input) {

const parsed = parseOrder(input)

validateOrder(parsed)

let model = computeTotals(parsed)

model = enrichCustomer(model)

persistOrder(model)

return buildResponse(model)

}'

Benefits:

• Each function is independently testable
• Logic is reusable across multiple features
• Debugging becomes faster and clearer
• Behavior remains identical while maintainability improves

Best Practices

• Name utilities based on behavior—parseX, validateY, transformZ.
• Pass only the needed fields to utilities, not full objects.
• Keep utilities pure whenever possible.
• Refactor in small, reversible steps; confirm behavior with each iteration.
• Group utilities into logical modules with minimal public surfaces.

Agent Prompts

"Identify responsibility clusters inside this long function and propose extraction steps."

"Refactor this function into smaller utilities while preserving external behavior."

"Run before/after comparisons for given inputs and confirm identical outputs."

"Create unit tests for extracted utilities."

Notes

• Do not modify public function signatures unless refactoring the API intentionally.
• Add logs temporarily during extraction to validate changes.
• Prefer utility-first decomposition before introducing patterns like services or classes.