Claude Skill

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

LLM Mart · 0 points · 1 views 0 listing impressions 0 install-command copies
Download kriscard-skills-skills_dev_codebase-design-08395f4.zip · 3 KB

Install

skills CLI npx skills add https://github.com/kriscard/Skills/tree/main/skills/dev/codebase-design
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install kriscard-skills@llmmart
Git git clone https://github.com/kriscard/Skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole kriscard/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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.

Files (skills)
  • SKILL.md 8.7 KB
    ---
    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.
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.