К основному содержанию
скилл CX Codex

modular-design-principles — скилл для Claude Code

Скилл modular-design-principles даёт правила модульной архитектуры и изолированных контекстов без привязки к стеку. Помогает спроектировать границы модулей и найти неявную связность.

MIT ★ 7 191 обновлён 2026-10-24

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add tech-leads-club/agent-skills --skill modular-design-principles -a claude-code
Открыть на GitHub

Что делает modular-design-principles

Скилл содержит свод из десяти технологически нейтральных архитектурных принципов, каталог типичных нарушений и процесс создания ограниченных контекстов (bounded contexts). В составе идут файл SKILL.md с основными правилами и справочник references/principles.md с примерами для агента. Ассистент опирается на модель из корней композиции, контекстов и минимальных общих ядер (shared kernels). Оркестрация остаётся тонкой. Выбор между монорепозиторием и отдельными библиотеками считается лишь способом поставки, а не признаком модульности.

В чек-лист нарушений входят прямой доступ к чужому хранилищу (reach-through persistence), размазанные транзакции, логика внутри транспортных адаптеров и утечка внутренних интерфейсов наружу. Для спорных решений скилл предлагает тест разделения. По умолчанию автор рекомендует держать границы монолитными, пока не возникнут разные темпы изменений или конфликты терминов.

Скилл не строит дорожные карты миграции легаси и не разбирает репозитории по пяти паттернам: для них автор отсылает к modular-decomposition и legacy-migration-planner. Без сопоставления абстрактных правил с реальной структурой проекта рекомендации останутся голыми схемами.

Какие задачи решает

  • спроектировать границы модулей и контракты взаимодействия
  • выявить прямой доступ к чужим базам данных в обход API
  • оценить необходимость разделения или слияния доменов
  • убрать бизнес-логику из транспортных адаптеров

Примеры запросов агенту

  • Проверь архитектуру пакетов проекта на типичные нарушения модульности и утечки состояния.
  • Спроектируй ограниченный контекст для модуля биллинга по шагам из руководства.
  • Оцени по критериям разделения, нужно ли выносить модуль авторизации в отдельный пакет.

Как установить modular-design-principles

1Через Skills CLI (Vercel)

npx skills add tech-leads-club/agent-skills --skill modular-design-principles -a claude-code

2Вручную: положить файлы

~/.claude/skills/modular-design-principles/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/modular-design-principles/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о modular-design-principles

Как установить modular-design-principles в Claude Code?

Выполните команду npx skills add tech-leads-club/agent-skills --skill modular-design-principles -a claude-code. Инструмент добавит файл скилла в каталог агента.

Для каких задач этот скилл не подходит?

Он не составляет дорожные карты миграции легаси и не выполняет декомпозицию репозиториев по пяти паттернам. Для этого служат скиллы legacy-migration-planner и modular-decomposition.

Привязан ли скилл к конкретному языку программирования?

Нет, принципы сформулированы независимо от языка, фреймворка или структуры папок. Вы сами переносите абстрактные границы и контракты на используемый стек.

Исходный текст

SKILL.md · MIT
---
name: modular-design-principles
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).
---

# 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

| # | Principle | Intent |
|---|-----------|--------|
| 1 | **Well-defined boundaries** | A small, stable **public surface**; everything else is internal. Consumers depend on contracts, not internals. |
| 2 | **Composability** | Modules can be used alone or combined without special knowledge of each other’s internals. |
| 3 | **Independence** | No hidden shared mutable state across boundaries; each module should be testable in isolation (with fakes or test doubles at the edges). |
| 4 | **Individual scale** | Resources (compute, storage, rate limits, batch size) can be tuned **per module** where it matters, without rewriting others. |
| 5 | **Explicit communication** | Cross-module interaction uses **documented contracts** (APIs, events, messages, shared types) — not incidental coupling. |
| 6 | **Replaceability** | Dependencies on other modules are expressed through **interfaces or protocols** so implementations can change. |
| 7 | **Deployment independence** | Modules do not assume they share a process, host, or release cadence unless that is an explicit architectural decision. |
| 8 | **State isolation** | Each module **owns** its persistent state and naming; no silent sharing of the same logical data store or ambiguous global names across boundaries. |
| 9 | **Observability** | Each module can be diagnosed on its own: logs, metrics, traces, health — attributable to the unit that emitted them. |
| 10 | **Fail independence** | Failures are **contained** (timeouts, bulkheads, circuit breaking, idempotency) so one module’s outage does not blindly cascade. |

**Principle 8** is often the hardest: ambiguous ownership of data or names is a frequent source of “works until it doesn’t” integration bugs.

For **depth** (rules for agents + abstract examples per principle), load `references/principles.md`.

---

## Typical violations (stated abstractly)

1. **Colliding concepts** — the same name or schema for different things in different modules, or duplicate “global” definitions that diverge over time.
2. **Reach-through persistence** — one module reading or writing another module’s tables, buckets, or documents **without** going through an agreed contract.
3. **Centralized data ownership** — a single persistence layer that registers and exposes **all** stores for **all** modules, encouraging hidden coupling.
4. **Logic at the edge** — business rules in transport adapters (HTTP handlers, UI, CLI) instead of domain/application code.
5. **Edge talking to storage directly** — adapters depending on low-level persistence APIs instead of use cases or application services.
6. **Unscoped transactions** — writes that span boundaries without clear transaction ownership and failure semantics.
7. **Leaky exports** — repositories, internal services, or implementation types exposed as the module’s public API.
8. **Facades that aren’t thin** — “public” entry points that embed querying, mapping, or policy instead of delegating to the right layer inside the module.

---

## Creating a bounded context (workflow)

Use when introducing a **new** cohesive area of the system (greenfield module or extracted domain).

1. **Scope and language** — Name the context; list core nouns/verbs (**ubiquitous language**). Reject vague names that collide with other contexts.
2. **Responsibilities** — What decisions happen **only** here? What is explicitly *out* of scope?
3. **State ownership** — Which facts are **authoritative** in this context? Where are they stored conceptually (even if storage tech is undecided)?
4. **Public contract** — Operations and/or events other contexts may use. Version or evolve this contract intentionally.
5. **Integrations** — For each neighbor: sync call, async message, shared read model, or batch sync? Document **consistency** (immediate, eventual) and **failure** behavior.
6. **Invariants and lifecycles** — What must always be true inside this boundary? What starts/completes a lifecycle?
7. **Isolation check** — Can you test core behavior **without** spinning up unrelated contexts (fakes at ports)?
8. **Observability** — How will you trace a request or job through **this** context with clear identifiers?

**Cross-module interaction** (while designing): prefer the **minimal** contract; define **timeouts**, **retries**, **idempotency** for async; avoid “temporary” direct store access as a shortcut.

---

## When to split or merge

**Default:** **fewer boundaries** until real pain appears — “flat is often better” than premature fragmentation. Splitting adds coordination, versioning, and operational cost.

### Six-criteria test (favor split when several are true)

| # | Criterion | Question |
|---|-----------|----------|
| 1 | **Language** | Do the sub-areas use **different vocabulary** or conflicting definitions of the same word? |
| 2 | **Rate of change** | Do parts **change on different cadences** or for unrelated reasons (most edits touch one side)? |
| 3 | **Scale / SLO** | Do parts need **different** throughput, latency, or availability targets? |
| 4 | **Consistency** | Do they need **different transaction boundaries** (cannot share one atomic write model cleanly)? |
| 5 | **Ownership** | Would **different teams** or clear ownership lines reduce conflict and review churn? |
| 6 | **Pain signal** | Is there **observable** integration pain: ripple effects, fear of change, unclear who owns a bug? |

**Cohesion / coupling (qualitative).** Favor **high cohesion** inside a module and **low, explicit coupling** between modules. If the only motivation is “files got big” or “folder aesthetics,” **merge or wait**.

### When to merge or not split yet

- Boundaries are **artificial** (same language, same lifecycle, constant cross-calls).
- Splitting would **duplicate** logic or data without a clear **single writer** rule.
- Team is not ready to **own** contracts, versioning, and ops for extra units.

### Decision prompts (short)

- Would separation **reduce** accidental coupling more than it **increases** coordination cost?
- Is there a natural **ubiquitous language** boundary, or only a technical seam?

---

## Sub-units inside a bounded context

Sometimes one outer boundary is right, but inside it there are **named sub-areas** (subdomains, feature areas). Principles still apply **within** the context.

**Ownership**

- Each sub-unit should **own** its slice of model and persistence concerns where possible — avoid one mega registration layer that wires **every** store and repository for **every** sub-unit in one place (encourages reach-through and hidden coupling).

**Cross-sub-unit access**

- Prefer **internal application APIs** or **thin internal facades** (same context, explicit surface) over peers importing each other’s storage types directly.
- For async flows, prefer **enriched payloads** so handlers do not **chat** across sub-units for data that could travel with the event/command.

**Shared kernel inside the context**

- Small, stable shared types or enums can live in a **narrow shared area** — but resist a growing “utils” dump that becomes the real coupling point.

**Anti-pattern:** A single “persistence” or “data” sub-module that becomes the **only** place that knows about all tables/documents for all sub-units, and everyone else reaches through it — same problems as cross-context reach-through, **inside** the boundary.

---

## Architecture compliance pass

Use for **reviews** or **audits** without assuming tooling. Treat items as **signals**, not proof — confirm with domain experts.

### Dependency and API signals

- **Inbound vs outbound:** Dependencies should align with your chosen architecture (e.g. domain at the center, adapters outside). **Inward** leaks of infrastructure types into core logic are a smell.
- **Public surface:** Can you list **exported** operations/events/types without including storage or internal services? If not, boundaries are leaky.
- **Neighbor imports:** Types or clients from **module A** used in **module B** — are they only **contract** types, or persistence/implementation types?

### Persistence and data signals

- **Reach-through:** References to another context’s **physical** data (schema, collection, bucket name) outside an agreed contract.
- **Naming collisions:** Same logical name for different things, or shared global IDs without a documented mapping rule.
- **Transaction ownership:** Writes that span contexts without a clear **saga**, **outbox**, or **single-owner** rule and documented failure cases.

### Operational signals

- **Blame:** Incidents where “we don’t know which module owns this row/behavior” → ownership or observability gap.
- **Cascades:** One dependency’s slowdown or failure takes down unrelated user journeys → missing **timeouts**, **bulkheads**, or **degradation** paths.

### Severity heuristic (for reporting)

| Tier | Meaning |
|------|--------|
| **P0** | Data corruption risk, security boundary violation, or cross-context persistence with no contract |
| **P1** | Unclear ownership, leaky public API, missing failure semantics at boundaries |
| **P2** | Observability gaps, composability smells, tech debt that increases future coupling |

**Maturity note:** Scoring is **qualitative** unless the team defines numeric gates. Use trends: fewer P0/P1 over time, clearer contracts.

---

## Quick checklist (before proposing structure)

- [ ] Public API is minimal; internals are not exported casually.
- [ ] Names and storage ownership are unambiguous per module.
- [ ] No cross-module persistence shortcuts without an explicit contract.
- [ ] Business rules sit behind a clear application/domain layer, not only in adapters.
- [ ] Cross-module calls have explicit failure and timeout behavior.
- [ ] Observability can answer “which module failed and why?” without spelunking.
- [ ] If the context has sub-units: each has clear ownership; no monolithic “registers everything” persistence grab-bag.

---

## Relationship to stack-specific skills

When a project has **concrete conventions** (framework modules, DI, repository patterns, folder layout, codegen, CI checks), prefer those documents for **how** to implement. Use **this** skill for **why** boundaries exist and **what** good modular design optimizes for — so stack-specific advice stays aligned with the same principles.

© tech-leads-club · MIT · tech-leads-club/agent-skills

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →
software-design-principles databricks-solutions Скилл software-design-principles для Claude Code задаёт правила архитектурного ревью, планирования рефакторинга и проверки зависимостей. Помогает согласовать слои и зоны ответственности перед слиянием PR. CX Codex +1 ★ 38звёзд репо domain-driven-design wondelai Скилл domain-driven-design для Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode: учит агента строить модель по бизнес-домену через bounded contexts, агрегаты и ubiquitous language. CX Codex +1 7 700установок domain-model-boundaries-mapper patricio0312rev Скилл domain-model-boundaries-mapper анализирует архитектуру проекта по принципам Domain-Driven Design: находит доменные модули, границы ответственности и зависимости. Помогает спланировать разделение связанных компонентов. CX Codex +1 270установок domain-architect pproenca Скилл domain-architect определяет бизнес-домены в Swift-проекте через возможности продукта, а не через имена папок. Строит карту слоёв каждого домена — от типов до UI. CX Codex +1 249установок design-code-architecture wondelai Скилл design-code-architecture для Claude Code, Cursor и других платформ проводит вас через восемь фаз архитектурного проектирования — от границ и доменной модели через выбор данных до отказоустойчивости. CX Codex +1 2 700установок architectural-design-principles databricks-solutions Скилл architectural-design-principles для Claude Code описывает слои, направление зависимостей и принципы облачных приложений. Помогает закрепить архитектурные ограничения автоматическими тестами. CX Codex +1 ★ 38звёзд репо

Из того же набора130

Весь набор →
tlc-implement Скилл tlc-implement доводит план из tlc-plan или небольшой тикет до рабочего кода через замороженные проверки, сборку и независимую верификацию. CX Codex +1 ★ 7 191звёзд репо tlc-generative-engine-optimization Скилл tlc-generative-engine-optimization готовит веб-страницы к цитированию в ChatGPT, Perplexity и Google AI Overviews. Настраивает семантическую разметку, Schema.org и файл llms.txt. CX Codex +1 ★ 7 191звёзд репо tlc-spec-lean Скилл tlc-spec-lean для Claude Code ведёт разработку функции от плана и проверяемых критериев до сборки и независимой проверки. Помогает подтвердить требования до начала работы. CX Codex +1 ★ 7 191звёзд репо create-rfc Скилл create-rfc для Claude Code. Собирает RFC по разделам: контекст, критерии решения, варианты, итог. Фиксирует направление до начала работы. CX Codex +1 ★ 7 191звёзд репо react-native-expert Скилл react-native-expert для Claude ведёт мобильный проект как старший инженер: компоненты React Native, навигация Expo Router, списки и анимации без просадок. CX Codex +1 ★ 7 191звёзд репо component-identification-sizing Скилл component-identification-sizing строит карту компонентов кодовой базы, считает их размер и показывает, что стоит разделить первым. CX Codex +1 ★ 7 191звёзд репо skill-architect Скилл skill-architect для Claude Code ведёт от идеи до готового SKILL.md: уточняет задачу, выбирает паттерн и структуру папки, проверяет описание. Помогает агенту повторять процесс одинаково. CX Codex +1 ★ 7 191звёзд репо create-adr Скилл create-adr для Claude Code — фиксирует принятые архитектурные решения в формате ADR, сохраняя контекст для будущих разработчиков. CX Codex +1 ★ 7 191звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой