# Codebase Design

Design or improve module interfaces using deep-module heuristics.

- Repository: https://github.com/stevesolun/ctx (589 stars)
- Category: Design
- License: MIT
- Last updated: 2026-10-14
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add stevesolun/ctx --skill codebase-design -g -a claude-code -y`
Codex: `npx skills add stevesolun/ctx --skill codebase-design -g -a codex -y`
Cursor: `npx skills add stevesolun/ctx --skill codebase-design -g -a cursor -y`
Gemini CLI: `npx skills add stevesolun/ctx --skill codebase-design -g -a gemini-cli -y`

## Description

Design or improve module interfaces using deep-module heuristics. Use when deciding where a seam belongs, reducing caller-facing complexity, improving testability or navigability, or comparing module designs.

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

# Codebase Design

Seek **deep modules**: substantial useful behavior behind a small, stable
interface. Use the concepts below as design lenses, while matching the
repository's established domain language.

## Working vocabulary

- **Module**: a coherent unit with an interface and implementation, at any scale.
- **Interface**: everything callers must know, including invariants and failure
  modes, not just a type signature.
- **Seam**: a location where behavior can vary without editing its callers.
- **Adapter**: an implementation that connects at a seam.
- **Depth**: useful capability relative to interface complexity.
- **Leverage**: capability gained by callers; **locality**: change and knowledge
  concentrated for maintainers.

Translate these terms to the project's vocabulary when that makes the design
clearer. Consistency with the codebase is more valuable than enforcing a private
lexicon.

## Design workflow

1. Map representative callers, responsibilities, dependencies, and existing
   contracts.
2. Look for coordination or policy that can move behind a smaller interface.
3. Place seams where variation, ownership, or test isolation justifies them.
4. Compare alternatives when the choice is consequential.
5. Validate the candidate with representative caller code and tests.

## Heuristics, not laws

The rest: https://github.com/stevesolun/ctx/blob/HEAD/.agents/skills/codebase-design/SKILL.md