codebase-design

Designs deep modules with small interfaces placed at clean seams.

7|1|Updated Mar 29, 2024
One-click install
npx skills add https://github.com/aBgAmeuR/harmony --skill codebase-design-abgameur
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: codebase-design
Source: https://github.com/aBgAmeuR/harmony/tree/main/.agents/skills/codebase-design
Command: npx skills add https://github.com/aBgAmeuR/harmony --skill codebase-design-abgameur

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Codebases accumulate shallow modules whose interfaces are nearly as complex as their implementations, making code hard to test, navigate, and change. This Skill provides a shared vocabulary and decision framework for designing deep modules that hide complexity behind small interfaces. ## Core Features & Use Cases - Deep-module vocabulary: Precise definitions of module, interface, seam, adapter, depth, leverage, and locality so teams and AI agents name things consistently. - Deepening guidance: Classifies dependencies (in-process, local-substitutable, remote-owned, true external) and prescribes ports-and-adapters strategies plus replace-don't-layer testing. - Design It Twice workflow: Spawns parallel sub-agents to produce radically different interface designs, then compares them on depth, locality, and seam placement. - Use Case: When refactoring a cluster of shallow service classes, use this Skill to identify the right seam, define a minimal interface, and restructure tests to target the interface rather than internals. ## 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 puts a large amount of behaviour 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?

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

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, asserting observable outcomes rather than internal state. Delete old unit tests on the shallow modules, since tests at the interface replace them and survive internal refactors.

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.