codebase-design

Generated source view for the actual executable engineering/codebase-design skill. The durable routing article is Agent Engineering Skills. Source: skills/engineering/codebase-design/SKILL.md

Runtime Source

Bundled Resources

These files are part of the executable skill folder and must be preserved with the skill source.

Description

Design deep modules, clean seams and small interfaces, and remove special cases, fallbacks and tech debt. Use when improving architecture, comparing interfaces, planning the smallest correct version, or on /improve, /torvalds or /lamport.

Skill Source

---
name: codebase-design
description: >-
  Design deep modules, clean seams and small interfaces, and remove special cases, fallbacks and
  tech debt. Use when improving architecture, comparing interfaces, planning the smallest correct
  version, or on /improve, /torvalds or /lamport.
origin: personal
source_slug: codebase-design
---

# Codebase Design

Use a small shared vocabulary for code shape: deep modules, small interfaces, clear
seams, and tests through the same interface callers use.

## Vocabulary

- **Module**: anything with an interface and implementation.
- **Interface**: every fact a caller must know: types, invariants, ordering, error
  modes, config, and performance behavior.
- **Implementation**: what sits behind the interface.
- **Seam**: the place where behavior can vary without editing callers.
- **Adapter**: a concrete implementation at a seam.
- **Depth**: leverage behind a small interface.
- **Locality**: changes and bugs stay concentrated.

Avoid using "component", "service", "API", and "boundary" when these terms are more
precise.

## Design Checks

Ask these before adding abstractions:

- What interface does the caller actually need?
- What complexity are we choosing to simplify, and what complexity are we
  refusing to hide?
- If we delete this module, does complexity vanish or reappear across callers?
- Are there two real adapters, or only one hypothetical seam?
- Can tests exercise behavior through the public interface?
- Is policy owned in the module, or split across callers?
- Does this create locality, or just another pass-through layer?
- Can a new engineer skim the file names, exported names, and section order and
  understand the domain story before reading function bodies?

## Code Taste Checks

Use this when a design smells "clever" but not trustworthy:

- **Abstraction taste:** callers should forget repeated policy, not hidden
  state, auth, timing, provider errors, or side effects.
- **Domain depth:** a good module has a small interface and enough behavior
  behind it to solve a real domain problem.
- **Predictable change:** the next change should have one obvious owner.
- **Verifiability:** the public interface should be testable with realistic
  failures, not only happy-path mocks.
- **Written tie-breakers:** if a taste decision repeats, route it into a
  test or doctor when it can be checked, else into `AGENTS.md`, a style
  page, or a skill.

## Output

For code review or design work, produce a short table:

| Area | Current shape | Risk | Better interface | Proof |
| --- | --- | --- | --- | --- |

Only recommend a new module when the deletion test passes and there is a concrete test
surface.

## References

- Read `DEEPENING.md` when evaluating how to deepen a shallow module and how its dependencies affect the test seam.
- Read `DESIGN-IT-TWICE.md` when Kevin wants multiple interface options or a chosen deepening candidate needs design alternatives.

## Related Skills

- `improve` for broad codebase audits and plan banking.
- `generate-interface` for interface extraction/refactoring.
- `no-sus-code-doctor` for strict ship-quality review.
- `domain-modeling` when the seam depends on domain language.

Wiki references: `wiki/style/code-taste.md`, `wiki/style/dedalus-style-guide.md`.

Upstream: `github.com/mattpocock/skills/skills/engineering/codebase-design/SKILL.md`
at `5d78bd0903420f97c791f834201e550c765699f8`.

<!-- folded-skills:auto:start -->
## Folded Skill References

These former standalone skills are bundled here as references to keep the runtime list compact. Load only the reference that matches the user's exact product, framework, or failure mode. Where a reference disagrees with this skill, this skill wins.

| Former skill | Reference | Description |
| --- | --- | --- |
| `domain-modeling` | [`references/skills/domain-modeling/SKILL.md`](references/skills/domain-modeling/SKILL.md) | Build and sharpen a project's domain model. Use when the user wants to pin down domain terminology, define a ubiquitous language, create or update CONTEXT.md / CONTEXT-MAP.md, record an ADR, resolve overloaded terms, or when another planning/code skill needs shared domain vocabulary. Adapted from mattpocock/skills. |
| `fail-closed-case-matching` | [`references/skills/fail-closed-case-matching/SKILL.md`](references/skills/fail-closed-case-matching/SKILL.md) | Dedalus philosophy on conditional logic, error paths, and why we never write fallbacks. Use when writing or reviewing any branching logic that selects between strategies, modes, or error-recovery paths. |
| `generate-interface` | [`references/skills/generate-interface/SKILL.md`](references/skills/generate-interface/SKILL.md) | Define or refactor subsystem interfaces into small, explicit contracts with clear ownership, narrow scope, stable semantics, and README-first documentation. Use when designing a new API, collapsing ad hoc module boundaries into a few coherent interfaces, hardening internal contracts, or rewriting subsystem docs so engineers can understand the system by reading README.md files, docstrings, and code only. |
| `improve` | [`references/skills/improve/SKILL.md`](references/skills/improve/SKILL.md) | Survey any codebase as a senior advisor and produce prioritized, self-contained implementation plans for OTHER models/agents to execute. Strictly read-only on source code — never implements, fixes, or refactors anything itself. Use when asked to audit a codebase, find improvement opportunities (bugs, security, performance, test coverage, tech debt, migrations, DX), suggest features or where to take the project next (roadmap, product direction), or generate handoff plans for another agent to implement. |
| `improve-codebase-architecture` | [`references/skills/improve-codebase-architecture/SKILL.md`](references/skills/improve-codebase-architecture/SKILL.md) | Scan a codebase for deepening opportunities, present a visual architecture report, then grill through the selected candidate. Use when Kevin invokes /improve-codebase-architecture, asks for architecture deepening, ball-of-mud cleanup, or agent-navigability improvements. |
| `invariant-first-coding` | [`references/skills/invariant-first-coding/SKILL.md`](references/skills/invariant-first-coding/SKILL.md) | Reason from proven invariants before coding. Use when reviewing fallback logic, narrowing types, handling conversions, deciding whether an error path is real or impossible, removing overdefensive code, or when the user questions whether code is being too theatrical, too hedged, or not fail-closed enough. |
| `lamport` | [`references/skills/lamport/SKILL.md`](references/skills/lamport/SKILL.md) | Simplify a problem by replacing sequence reasoning with state invariants. Use when the user invokes /lamport, asks for Lamport-style reasoning, or when a task has many cases, phases, interactions, or edge conditions that are hard to reason about directly. |
| `minimal-first-implementation` | [`references/skills/minimal-first-implementation/SKILL.md`](references/skills/minimal-first-implementation/SKILL.md) | Build the smallest correct version first. Name every case, implement only what has a real consumer, return typed errors for the rest. Use when designing new systems, extracting shared packages, or deciding how much to build before shipping. |
| `torvalds` | [`references/skills/torvalds/SKILL.md`](references/skills/torvalds/SKILL.md) | Design engineering principles for removing special cases. Use when designing new systems, extracting shared packages, refactoring conditional logic, deciding whether to add a flag or change the interface, or when the user invokes "good taste" or asks for a cleaner algorithm. |
| `zero-tech-debt` | [`references/skills/zero-tech-debt/SKILL.md`](references/skills/zero-tech-debt/SKILL.md) | Rework a recent change as if the intended UX and architecture existed from day one, deleting compatibility cruft and accidental complexity. Use when Kevin invokes /zero-tech-debt, asks to clean AI-generated tech debt, says the code feels patched-on, or wants a feature refactored toward the final product surface rather than preserved history. |
<!-- folded-skills:auto:end -->

---

Timeline

• 2026-11-02 | Generated a browseable source page from the actual executable skill file. Source: skills/engineering/codebase-design/SKILL.md