codebase-design

name	codebase-design
description	Shared vocabulary and decision process for designing module interfaces and test seams. Use when Codex needs to decide where a seam belongs, judge whether a module is deep or shallow, design an interface that serves slicing and acceptance, or make code easier to test and navigate.

Codebase Design

Design deep modules: a lot of behavior behind a small interface, placed at a useful seam and testable through that interface.

Use this vocabulary exactly:

• Module: anything with an interface and implementation.
• Interface: everything callers must know to use the module correctly, including invariants and error modes.
• Implementation: what sits behind the interface.
• Depth: leverage at the interface.
• Seam: where a module's interface lives.
• Adapter: a concrete thing satisfying an interface at a seam.
• Leverage: capability gained per unit of interface learned.
• Locality: change and bugs concentrate in one place.

Avoid using "component", "service", "API", "signature", or "boundary" when these terms would be less precise.

Principles

• Interfaces should serve the current slice and acceptance path.
• Do not abstract every future possibility upfront.
• The interface is the test surface.
• One adapter means a hypothetical seam; two adapters mean a real seam.
• Use the deletion test: if deleting a module only moves complexity, it was shallow.
• Prefer internal seams inside a module over exposing test-only complexity to callers.

Workflow

1. Identify The Current Slice

Read the issue, PRD, acceptance criteria, or bug repro. Determine what behavior must be delivered or protected now.

2. Find Candidate Seams

Compare existing public interfaces, tests, call sites, adapters, and data ownership. Prefer an existing seam if it can support the slice and acceptance evidence.

3. Judge Depth

Ask:

• Does this interface hide meaningful behavior?
• Would callers become simpler?
• Would tests prove more behavior with less setup?
• Would change localize behind the interface?
• Are we adding a real seam or only indirection?

4. Recommend A Shape

Describe the recommended module, interface, seam, adapters, and test surface. Keep it tied to the current slice. Note future extension points only when they are justified by known variation.

For deeper refactors, see:

• DEEPENING.md
• DESIGN-IT-TWICE.md

Finish

Return the design recommendation, why it serves implementation and acceptance, and what should remain out of scope.