modular-design-principles

Guides modular architecture design using ten technology-agnostic boundary and coupling principles.

Updated Sep 15, 2026
One-click install
npx skills add https://github.com/Peterson-Benhame/agent-skills --skill modular-design-principles-peterson-benhame
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: modular-design-principles
Source: https://github.com/Peterson-Benhame/agent-skills/tree/main/packages/skills-catalog/skills/%28architecture%29/modular-design-principles
Command: npx skills add https://github.com/Peterson-Benhame/agent-skills --skill modular-design-principles-peterson-benhame

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Teams struggle to decide where to draw module boundaries, when to split or merge services, and how to review architecture for coupling problems without framework-specific rules. This Skill provides technology-agnostic principles and workflows for designing, reviewing, and auditing modular systems. ## Core Features & Use Cases - Ten Modularity Principles: Covers well-defined boundaries, composability, state isolation, explicit contracts, failure containment, and observability, with per-principle agent rules in references/principles.md. - Bounded Context Workflow: Step-by-step process for scoping new modules, defining public contracts, state ownership, and integration consistency. - Split/Merge Decision Criteria: A six-criteria test (language, rate of change, scale, consistency, ownership, pain signals) to decide when to split or merge modules. - Compliance Review Signals: P0/P1/P2 severity heuristics for auditing dependency leaks, reach-through persistence, and cascading failures. - Use Case: When reviewing whether a growing monolith's billing and inventory code should become separate services, apply the six-criteria test and compliance signals to produce a reasoned recommendation. ## Quick Start Ask the agent to review your module structure or evaluate whether a specific part of the codebase should be split into its own bounded context.

Frequently Asked Questions about modular-design-principles

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I decide when to split a module or service?

Apply the six-criteria test: check for divergent vocabulary, different rates of change, distinct scale or SLO needs, incompatible transaction boundaries, separate team ownership, and observable integration pain. Favor splitting only when several criteria are true; otherwise keep fewer boundaries.

How do I design a bounded context for a new domain?

Follow the eight-step workflow: name the context with ubiquitous language, define responsibilities and exclusions, establish state ownership, specify the public contract, document integrations with consistency and failure behavior, define invariants, verify test isolation, and plan observability.

Does this guidance require a specific framework or language?

No, the principles are deliberately technology-agnostic with no framework names, folder conventions, or tooling assumptions. You map the principles to your own stack, and use stack-specific documentation for implementation details.

What are signs of poor module boundaries in a codebase?

Common violations include reach-through persistence across modules, leaky public APIs exposing internals, business logic in transport adapters, unscoped cross-boundary transactions, and colliding names for different concepts. The compliance pass rates these as P0, P1, or P2 severity signals.

When should I not split a module even if it is large?

Avoid splitting when boundaries would be artificial, when it would duplicate logic without a clear single writer, or when the team cannot own the extra contracts and operations. File size or folder aesthetics alone are not valid reasons to split.