codebase-design

Design deep modules with small, stable caller-facing contracts and justified seams.

3|Updated Nov 8, 2014
One-click install
npx skills add https://github.com/mintuz/.dotfiles --skill codebase-design-mintuz
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: codebase-design
Source: https://github.com/mintuz/.dotfiles/tree/main/agents/.agents/skills/codebase-design
Command: npx skills add https://github.com/mintuz/.dotfiles --skill codebase-design-mintuz

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? It helps engineers decide how to structure in-process modules and packages so that callers learn less, policy changes concentrate in one owner, and shallow pass-through layers or god modules are avoided. ## Core Features & Use Cases - Deep module design: Define a cohesive responsibility, inventory the full caller-facing contract burden (types, invariants, ordering, errors, effects, performance), and hide decisions behind a small stable interface. - Deepening and migration guidance: Use the references to consolidate duplicated policy, classify dependencies by ownership, trust, consistency, and test fidelity, and migrate safely with behavior tests and temporary compatibility facades. - Design It Twice comparison: Generate genuinely different contract alternatives, compare them against the same caller scenarios, and recommend one with explicit trade-offs. - Use Case: When several callers repeat the same validation, sequencing, and provider mapping logic, use this Skill to design one module that owns that policy, specify its contract and seams, and plan the incremental migration. ## Quick Start Ask the agent to use codebase-design to propose a module contract for the duplicated checkout-pricing logic spread across the order and invoice services.

Frequently Asked Questions about codebase-design

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

FAQPage Schema
How do I design a deep module with a small interface?

Define one coherent responsibility, inventory everything callers must know today, then hide policy, sequencing, and provider mechanics behind a contract covering types, invariants, errors, effects, and performance. Verify the common caller learns and coordinates less.

How to decide whether code should be combined or split into modules?

Apply the behavior-preserving inlining test: if inlining spreads policy or sequencing knowledge across callers, the module earns its place; if callers get simpler with no duplicated knowledge, it is shallow. Preserve separate modules when they evolve, fail, or deploy independently.

When should I create a seam or adapter in a module design?

Create a seam only for concrete needs such as substitution, independent testing, volatility isolation, ownership, trust, or runtime failure. Adapter count is evidence, not a rule; a production adapter plus a faithful test interactor can justify a seam.

What is the difference between codebase-design and structure-codebase?

codebase-design covers logical responsibility and contract shape, while structure-codebase handles physical paths, packages, exports, dependency direction, and folder migration. Use api-design for public or externally versioned contracts instead.

How do I safely migrate callers to a deeper module contract?

Establish behavior tests first, define the target contract, move one decision at a time in small slices, and use a temporary compatibility facade with a stated removal condition. Retire old modules only after equivalent behavior coverage and mutation evidence exist.