Modular Software Design

Use this skill before coding when a task involves new modules, changed boundaries, public APIs, services, repositories, domain objects, adapters, layers, or architecture refactoring.

Goal: reduce total system complexity. Optimize for lower cognitive load, fewer unknown unknowns, localized change, and simpler caller experience. Do not optimize for more classes, fewer lines, architecture-pattern compliance, or local cleverness.

Required Output Before Coding

For non-trivial changes, produce a compact design brief before implementation. Use templates/design-brief.md when useful.

Task:
Complexity goal:
Candidate modules and interfaces:
Hidden implementation knowledge:
Alternative designs considered:
Chosen design and rationale:
Leakage/pass-through risks:
Layering plan:
Tests and interface documentation:

Do not proceed directly to implementation unless the change is purely mechanical or the user explicitly asks to skip design.

Core Concepts to Apply

A deep module provides high functionality behind a small, simple interface. Its implementation may be complex, but callers do not need to know its internal decisions, sequencing, data representation, vendor behavior, persistence, validation, retries, or special cases.

A module is suspicious when its interface is nearly as complex as its implementation, mainly forwards calls, mirrors another layer, exposes raw implementation shapes, or forces callers to coordinate internal steps.

Use the detailed rules in:

• references/decision-rules.md for split/merge, layering, leakage, pass-through, and interface decisions.
• references/review-checklist.md for design review gates.
• examples/module-design-examples.md for good and bad examples.

Workflow

1. State the complexity goal. Identify the change amplification, cognitive load, hidden coupling, or unknown unknowns the design should reduce.
2. Identify concepts, not steps. Avoid temporal decomposition such as parser/validator/processor/responder unless those are true abstractions. Prefer concepts that own decisions or invariants.
3. Draft at least two designs. Compare module depth, public surface area, leakage, pass-through code, layer fit, change impact, and caller burden.
4. Define interfaces before implementation. For each module, document purpose, public operations, inputs, outputs, errors, invariants, side effects, caller responsibilities, hidden knowledge, and non-goals.
5. Audit the design. Check for shallow modules, leakage, pass-through methods or variables, duplicate abstractions across layers, temporal decomposition, boolean-flag APIs, special-case spread, and fragile call ordering.
6. Choose the design with the lowest total complexity. Prefer one deeper module over several shallow modules when separation only exports coordination burden.
7. Implement against the chosen contract. Keep public APIs minimal, push repeated caller burden downward, and update names/comments when the abstraction becomes clearer.
8. Report the architectural result. Summarize what complexity was hidden, which interfaces were created or changed, what alternatives were rejected, and what tradeoffs remain.

Decision Rules Summary

• Prefer fewer, more powerful operations over many tiny methods.
• Name APIs by caller intent, not implementation steps.
• Expose domain concepts and stable value types, not tables, rows, framework objects, vendor DTOs, transport objects, or raw status codes.
• Split modules when they hide different knowledge or change for different reasons.
• Merge modules when the split creates pass-through APIs, shared private knowledge, or caller-managed sequencing.
• Each layer must provide a different abstraction; do not duplicate the same CRUD-shaped interface across controller/service/manager/repository layers.
• Pull complexity downward when it eliminates repeated caller logic or hides volatile decisions; stop when the abstraction becomes speculative, surprising, or god-object-like.
• Design errors and special cases out of existence when possible through defaults, normalization, invariants, or domain concepts.
• Expose only errors that callers can act on.
• Treat comments and names as part of the interface design.

Mandatory Design Gates

Before coding, answer:

1. What total complexity does this design reduce?
2. Which module is deepest, and why?
3. What implementation knowledge is hidden?
4. What is the smallest useful public interface?
5. What are the rejected alternatives?
6. Where could information leak?
7. Are there pass-through methods or pass-through variables?
8. Do layers use distinct abstractions?
9. Are special cases centralized or designed away?
10. What future change should be easier after this design?

If answers are weak, revise the design before coding.

Applying to a Specific Coding Task

When the user asks for implementation, first produce the design brief unless the task is trivial. Then implement only the selected design. During coding, stop and revise the design if you introduce a pass-through API, leak implementation details across a boundary, duplicate a layer abstraction, or add caller-visible special-case sequencing.

Critiquing Existing Architecture

When asked to review existing code or architecture, use templates/architecture-critique.md. Focus on complexity symptoms first: change amplification, cognitive load, hidden coupling, unknown unknowns, leakage, pass-throughs, shallow modules, temporal decomposition, and duplicated layer abstractions. Recommend small strategic refactorings before broad rewrites.