# Modular Design Principles

Technology-agnostic guidance for modular systems: bounded contexts, clear boundaries...

- Repository: https://github.com/tech-leads-club/agent-skills (7121 stars)
- Category: Design
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add tech-leads-club/agent-skills --skill modular-design-principles -g -a claude-code -y`
Codex: `npx skills add tech-leads-club/agent-skills --skill modular-design-principles -g -a codex -y`
Cursor: `npx skills add tech-leads-club/agent-skills --skill modular-design-principles -g -a cursor -y`
Gemini CLI: `npx skills add tech-leads-club/agent-skills --skill modular-design-principles -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add tech-leads-club/agent-skills`

## Description

Technology-agnostic guidance for modular systems: bounded contexts, clear boundaries, composability, state isolation, explicit contracts, failure containment, scaffolding workflows, split/merge criteria, sub-units inside a context, and compliance review signals. Use when designing or reviewing module structure, service boundaries, package layout, cross-cutting dependencies, "how should we split this?", modularity assessments, coupling between domains, greenfield context design, or architecture discussions without assuming a specific framework, language, or repository layout. Do NOT use for executing the full Patterns 1, 5 repo decomposition pipeline or per-pattern inventories (use modular-decomposition), phased extraction roadmaps as the main deliverable (use decomposition-planning-roadmap), or end-to-end legacy migration strategy (use legacy-migration-planner).

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Modular Design Principles

Use this skill when reasoning about **structure and boundaries** in any codebase. It intentionally avoids framework names, folder conventions, and tooling, map principles to your stack locally.

## What to load

| Task | Where |
|------|--------|
| Principles table + violations + workflows (this file) | `SKILL.md` |
| Per-principle definition, agent rules, abstract examples | `references/principles.md` |

---

## Layered mental model

- **Composition roots** (applications, hosts, runners): wire modules together; keep orchestration thin.
- **Modules / bounded contexts**: cohesive units of behavior and data ownership; each should be understandable and testable on its own.
- **Shared kernels** (use sparingly): only stable, truly cross-cutting concepts; resist turning them into a grab-bag of “everything everyone needs.”

How you physically lay this out (mono repo, multi repo, packages, libraries) is a **delivery choice**, not the definition of modularity. The principles below still apply.

---

## The ten principles

The rest: https://github.com/tech-leads-club/agent-skills/blob/HEAD/packages/skills-catalog/skills/(architecture)/modular-design-principles/SKILL.md