skills.rest
shaahy
shaahyCOMMUNITY
Explore all skills by this author →
GitHub

codebase-design

Designs deep modules with small interfaces placed at clean seams.

Updated Aug 3, 2026
Search Tags:#refactoring#testability#software architecture#module design#interface#ports and adapters#seam
One-click install
npx skills add https://github.com/shaahy/quicknav-desktop --skill codebase-design-shaahy
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: codebase-design
Source: https://github.com/shaahy/quicknav-desktop/tree/main/A%20%E6%95%99%E7%A8%8B%E9%9B%86%E5%90%88/Matt%20Pocock%20Skills%20%E6%8A%80%E8%83%BD%E9%80%9F%E6%9F%A5/source-snapshot/skills/engineering/codebase-design
Command: npx skills add https://github.com/shaahy/quicknav-desktop --skill codebase-design-shaahy

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases often accumulate shallow modules whose interfaces are nearly as complex as their implementations, making code hard to test, navigate, and refactor. This Skill provides a shared vocabulary and design principles for creating deep modules that hide complexity behind small interfaces. ## Core Features & Use Cases - Deep-module vocabulary: Defines precise terms (module, interface, seam, adapter, depth, leverage, locality) so teams and AI agents discuss architecture consistently. - Dependency-aware deepening: Classifies dependencies (in-process, local-substitutable, remote-owned, true external) and prescribes ports-and-adapters strategies for each when merging shallow modules. - Design It Twice workflow: Spawns parallel sub-agents to propose radically different interfaces for a candidate module, then compares them on depth, locality, and seam placement. - Use Case: When refactoring a cluster of shallow service classes, use this Skill to decide where the seam goes, design a minimal interface, and write tests at that interface instead of layering mocks. ## Quick Start Ask the AI to review a module in your codebase and propose a deeper interface using the codebase-design vocabulary.

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 interface?▼

A deep module hides a large amount of behavior behind a small interface. Reduce the number of methods, simplify parameters, and hide complexity inside the implementation so callers get more leverage per unit of interface they learn.

What is the difference between a seam and an interface?▼

A seam is the location where a module's interface lives and where behavior can be altered without editing that place. The interface is everything a caller must know to use the module, including invariants, ordering, and error modes.

When should I introduce a port and adapter?▼

Introduce a port only when at least two adapters are justified, typically a production adapter and a test adapter. A single-adapter seam is just indirection and should be avoided.

How do I test a deepened module?▼

Write tests at the deepened module's interface, treating the interface as the test surface. Delete old unit tests on the shallow modules and assert on observable outcomes rather than internal state.

What is the Design It Twice process?▼

Design It Twice spawns three or more parallel sub-agents, each producing a radically different interface under distinct constraints such as minimal surface or maximum flexibility. The designs are then compared on depth, locality, and seam placement.

Related Skills

Explore More Software Engineering Skills→
J0JngJ0Jng
7

codebase-design

Designs deep modules with small interfaces, clean seams, and testable adapters.

Community
Intermediate
notquenotque
415

architecture-deepening

Identify shallow code modules and propose deepened interface alternatives.

Community
Advanced
testdoubletestdouble
198

refactor

Refactor code iteratively with test-gated validation after each step.

Official
Advanced
AlteriomAlteriom

prd-to-ddd-design

Convert PRDs into DDD models with bounded contexts, aggregates, and domain events.

Official
Advanced