Skip to content
Skills Library
Programming · Planning

codebase-design

/codebase-design

Design and evaluate module interfaces, depth, seams, adapters, locality, and testability. Use when deciding what a module should hide, what callers should know, where dependencies should vary, whether an abstraction earns its cost, or how to make one subsystem easier to test and modify. Use for split/join decisions about pipeline stages, shared knowledge, oversized modules, or representation-driven special cases. Also use when another skill needs consistent deep-module vocabulary.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Design and evaluate module interfaces, depth, seams, adapters, locality, and testability. Use when deciding what a module should hide, what callers should know, where dependencies should vary, whether an abstraction earns its cost, or how to make one subsystem easier to test and modify. Use for split/join decisions about pipeline stages, shared knowledge, oversized modules, or representation-driven special cases. Also use when another skill needs consistent deep-module vocabulary.

Original author description

Design and evaluate module interfaces, depth, seams, adapters, locality, and testability. Use when deciding what a module should hide, what callers should know, where dependencies should vary, whether an abstraction earns its cost, or how to make one subsystem easier to test and modify. Use for split/join decisions about pipeline stages, shared knowledge, oversized modules, or representation-driven special cases. Also use when another skill needs consistent deep-module vocabulary.

How it works

  1. Workflow
  2. Vocabulary
  3. Report
Original SKILL.md headings · 166 lines, 1,140 words
SKILL.md preview
---
name: codebase-design
description: >-
  Design and evaluate module interfaces, depth, seams, adapters, locality, and
  testability. Use when deciding what a module should hide, what callers should
  know, where dependencies should vary, whether an abstraction earns its cost,
  or how to make one subsystem easier to test and modify. Use for split/join
  decisions about pipeline stages, shared knowledge, oversized modules, or
  representation-driven special cases.
  Also use when another skill needs consistent deep-module vocabulary.
---

# Codebase Design

Concentrate complexity behind useful interfaces. A good module gives callers
substantial capability while keeping knowledge, change, bugs, and verification
local.

When another skill loads this one, apply the vocabulary and analysis below inside
that skill's workflow and output format. When invoked directly, complete the full
workflow and return the module-design report.

## Workflow

### 1. Frame the module

Identify the module under review, its responsibility, callers, dependencies, public
entry points, observable behavior, and constraints. A module may be a function,
class, component, package, service, feature, or tier-spanning slice.

Use the repository's framework terms for concrete artifacts and *module* for their
design role.

**Complete when:** the module, its callers, its current contract, and the desired
outcome are explicit.

### 2. Map interface burden

List everything a caller must know to use the module correctly:

- operations and data shapes;
- invariants and valid ordering;
- errors and recovery responsibilities;
- configuration and lifecycle;
- performance or concurrency characteristics;
- implementation details repeated or coordinated by callers.

Treat the interface as this full burden, not only its type signature or network API.
Trace each claim to callers, exports, tests, or runtime behavior.

**Complete when:** every demonstrated piece of caller knowledge is accounted for and
implementation knowledge leaking through the interface is identified.

### 3. Assess depth and locality

Judge the behavior centralized by the module against the interface callers must
learn. Apply the **deletion test**: if the module disappeared, would its complexity
spread into callers or vanish? Spreading complexity indicates useful leverage;
vanishing complexity suggests a shallow pass-through.

Look for repeated orchestration, change amplification, duplicated error handling,
scattered policy, and tests that bypass the public interface. Measure depth through
caller knowledge and centralized behavior rather than implementation size.

**Complete when:** the module's depth, leverage, and locality are supported by
specific caller and change evidence.

### 4. Decide what belongs together

For a proposed split or join, inventory the nonobvious knowledge each phase or
module needs: format rules, invariants, policy decisions, and reasons to change.
Trace duplicated knowledge, including back-door assumptions absent from signatures,
to concrete code or contracts. Walk a representative format, invariant, or policy
change: which implementations and callers must change together?

Compare keeping, joining, and splitting the relevant responsibilities by total
caller **and** implementation burden: interfaces and coordination added, knowledge
hidden or duplicated, change amplification, locality, and demonstrated independent
variability. Prefer one owner for knowledge that must change together; preserve
meaningful responsibilities that can vary independently and necessary caller policy.
Execution order, LOC, or short methods alone do not justify a split; shared input
or execution proximity alone do not justify a join.

For example, reading and parsing stages that both encode the same wire grammar
may belong behind one protocol interface. Parsing and authorization sharing request
data still need distinct trust responsibilities and a narrow validated contract.
Preserve ownership, trust/security, deployment, and generated/framework-required
boundaries through explicit contracts rather than collapsing them to remove overlap.
If evidence is missing, identify the change or caller trace needed before choosing.

**Complete when:** each proposed grouping has a knowledge/change trace and a
join-versus-split rationale, including what remains independently owned. When
composed by another workflow, keep this analysis in its existing output format.

### 5. Inspect seams and adapters

A **seam** is a place where behavior can vary without editing the caller. An
**adapter** is a concrete implementation occupying a role at that seam. Reserve
**boundary** for domain, ownership, process, deployment, or trust boundaries.

Find where dependencies are accepted versus constructed, where tests and production
use different paths, and where callers select or coordinate implementations. Treat a
seam as earned when variation is demonstrated by multiple adapters, a test double, a
platform difference, or a known source of change.

**Complete when:** each proposed or existing seam has a demonstrated source of
variation and its placement is justified independently from its interface design.

### 6. Design a deeper alternative

Move stable policy and repeated knowledge behind the interface while preserving
necessary caller control. Prefer the smallest coherent interface that owns the full
responsibility. Compare the current design with the proposed design through:

- caller knowledge removed or added;
- behavior and policy centralized;
- changes localized;
- errors and invariants owned;
- testing through the same interface callers use;
- migration cost and compatibility.

When one representation forces repeated empty, root, or sentinel checks across ordinary
operations, compare it with an invariant that lets the normal operation handle those cases.
For example, an empty range can represent no visible selection when copying or deleting that
range already preserves the required behavior. Trace the branches and caller obligations removed,
not just the reduced `if` count. Retain meaningful business, authorization, failure, and protocol
distinctions; absence and an empty value are interchangeable only when the contract makes them so.
A surprising sentinel, a more complicated common path, or one cheap local guard does not justify a
representation change. Keep error-contract decisions with their owner and language-specific state
modeling with `typescript`; use `refactor` for authorized behavior-preserving implementation.

Keep existing behavior and public APIs unless the user authorizes a contract change.
Avoid an abstraction when it only renames operations, forwards calls, or anticipates
variation without evidence.

**Complete when:** the recommendation states what moves behind the interface, what
remains caller-owned, and why the resulting module provides more leverage.

### 7. Define verification

Specify how to prove the design improvement. Prefer observable checks such as fewer
caller responsibilities, removal of repeated coordination, tests crossing the public
interface, localized future changes, or elimination of implementation-aware call
sites. For a representation change, check normal, empty/root, and transition cases through the
public interface, including preserved distinctions and any caller knowledge actually removed.

Route a cross-system or hard-to-reverse decision to `architect`. Route authorized
behavior-preserving implementation work to `refactor`.

**Complete when:** the proposed interface, migration boundary, and checks for behavior
and design improvement are concrete enough to implement or review.

## Vocabulary

- **Module:** an interface plus an implementation.
- **Interface:** everything callers must know to use the module correctly.
- **Implementation:** behavior hidden behind the interface.
- **Depth:** useful behavior provided per unit of interface burden.
- **Seam:** a place where behavior can vary without editing the caller.
- **Adapter:** a concrete implementation filling a role at a seam.
- **Leverage:** capability callers receive per unit of interface they must learn.
- **Locality:** concentration of knowledge, change, bugs, and verification.
- **Boundary:** a domain, ownership, process, deployment, or trust division.

## Report

When invoked directly, return:

1. **Module and callers** — scope, responsibility, dependencies, and evidence.
2. **Interface burden** — what callers currently must know.
3. **Diagnosis** — depth, locality, leaks, seams, adapters, and any grouping decision.
4. **Recommended interface** — responsibilities moved, retained, or removed.
5. **Migration and verification** — compatibility, sequence, tests, and success checks.

Describe observations before judgments. Tie every recommendation to leverage,
locality, testability, or a demonstrated architectural constraint.

Versions

RepositoryScoreLicence
This page · kriscard/kriscard-claude-plugins100MIT
mikeleg/skills100MIT
VincenzoImp/pitcrew100MIT
akillness/jeo-skills100MIT
JamalLyons/Agent-Skills100MIT
zenobi-us/dotfiles100MIT
FrancoStino/opencode-skills-collection100MIT
yassimba/loom100Apache-2.0
niekcandaele/claude-helpers100MIT

Database snapshot: 13.11.2026 · package version 6acca15da9f2 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90improve-codebase-architecture
    Assess or improve an existing codebase's architecture when the user asks about module boundaries, coupling, scattered ownership, testability, change locality, deep modules, seams, or behavior-preserving structural refactoring. Use for cross-module design rather than ordinary…
  • 95workflow-codebase-design
    Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
  • 100architect
    Use when non-trivial code needs a design, codebase design or architecture needs improving, or one module needs targeted interface narrowing, seams, or testability. Not for diagrams, deploy, or irreversible changes.
  • 100improve-codebase
    Use when designing or reviewing a module's interface, deciding where a seam goes, finding shallow modules or deepening opportunities, running an architecture review, making code more testable or AI-navigable, or extracting code repeated across three or more projects into a…
  • 86design-deep-modules
    Design or compare concrete high-leverage module boundaries with small stable interfaces, hidden complexity, explicit seams, adapters, locality, and reversible migration. Use when the request asks for boundary or interface design; not for whole-architecture audits or requests…
  • 100deep-module-design
    Design deep modules with small interfaces and rank shallow, pass-through or leaky code for deepening. Use when designing a module interface, improving codebase architecture, or making code easier to test.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.