codebase-design

Design deep modules and clean interfaces for codebases.

1|Updated Mar 19, 2026

Search Tags:#architecture #refactoring #interfaces #adapters #seams #codebase design

Ready to run

npx skills add https://github.com/ian-pascoe/dotfiles-chezmoi --skill codebase-design-ian-pascoe

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: codebase-design
Source: https://github.com/ian-pascoe/dotfiles-chezmoi/tree/main/dot_agents/skills/codebase-design
Command: npx skills add https://github.com/ian-pascoe/dotfiles-chezmoi --skill codebase-design-ian-pascoe

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This Skill helps you decide where behavior should live, how to expose it through a small interface, and how to keep change concentrated behind a clean seam.

Core Features & Use Cases

Defines a shared architectural vocabulary for modules, interfaces, seams, adapters, depth, leverage, and locality.
Guides deepening decisions by classifying dependencies and choosing the right seam and testing strategy.
Supports parallel exploration of alternative interfaces when a module could be shaped in several ways.
Useful when refactoring a shallow cluster, making code more testable, or designing an AI-navigable codebase.

Quick Start

Use the codebase-design skill to assess this module, identify the best seam, and propose a smaller interface that concentrates behavior behind it.

Frequently Asked Questions about codebase-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I design deep modules with clean interfaces for better codebase testability?▼

To design deep modules with clean interfaces, you classify dependencies, identify the right seam, and concentrate behavior behind a small surface. This approach improves testability, locality, and AI navigability by replacing shallow layers with high-leverage adapters.

What is a seam in software architecture and when do I need an adapter?▼

A seam in software architecture is a clean boundary where behavior can be modified or replaced without altering the rest of the system. You need an adapter when categorizing dependencies to isolate changes and improve module testability behind a small interface.

How do I refactor a shallow module cluster to improve codebase navigability?▼

To refactor a shallow module cluster, you assess the current shape, identify the best seam, and propose a smaller interface that deepens the module. This concentrates behavior behind a clean boundary, improving locality and AI navigability.

Can I compare alternative interface designs for the same module in parallel?▼

Yes, you can compare alternative interface designs in parallel. The skill supports exploring multiple ways a module could be shaped, guiding you to choose the right seam and evaluate trade-offs for maximum architectural leverage.

What is the best way to choose the right seam for dependency categorization?▼

The best way to choose a seam for dependency categorization is to evaluate which boundary allows behavior to be replaced efficiently. This involves classifying dependencies and selecting an adapter strategy that isolates changes behind a deep module interface.

When should I not use shallow layers in my codebase architecture?▼

You should avoid shallow layers when a module could be shaped into a deep module with a smaller interface. Shallow layers lack leverage, spreading behavior across boundaries, whereas deep modules concentrate behavior behind clean seams for better testability.