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.
- Author
- kriscard ↗
- Repository
- kriscard-claude-plugins ↗
- Licence
- MIT
- Last repository change
- 27.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.
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
- Workflow
- Vocabulary
- Report
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
| Repository | Score | Licence |
|---|---|---|
| This page · kriscard/kriscard-claude-plugins | 100 | MIT |
| mikeleg/skills | 100 | MIT |
| VincenzoImp/pitcrew | 100 | MIT |
| akillness/jeo-skills | 100 | MIT |
| JamalLyons/Agent-Skills | 100 | MIT |
| zenobi-us/dotfiles | 100 | MIT |
| FrancoStino/opencode-skills-collection | 100 | MIT |
| yassimba/loom | 100 | Apache-2.0 |
| niekcandaele/claude-helpers | 100 | MIT |
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.