Codebase design

Design deep modules with substantial behavior behind small interfaces, placed at clean seams, and testable directly through those interfaces.

Modes

Select the design mode before Step 1:

• Greenfield mode. Draft schemas, bounded contexts, and initial interface contracts from scratch.
• Refactor mode. Audit existing database schemas, migration files, and routes to encapsulate existing complexity behind deep modules.

Workflow

Follow these five steps in sequence.

Step 1. Domain context and schema ingestion

Read the project context and verify actual data schemas before modifying or creating modules.

1. Inspect AGENTS.md, CODEBASE.md, or CLAUDE.md in the project root if present. Use the domain nouns, bounded contexts, and naming conventions defined there.
2. Audit database schemas and migration files:
   • For projects with existing databases, inspect migration directories (such as database/migrations/, prisma/schema.prisma, or src/db/).
   • Ground all entity attributes, foreign keys, and relations in verified schema files on disk. Never invent columns or assume database fields based on general model training.
   • For greenfield repositories without existing migrations, mark the status as greenfield initialization and draft the initial schema explicitly without unverified assumptions.
3. Infer domain boundaries and seams directly from verified migrations, route declarations, and existing data models.

Completion criterion. The agent names modules, methods, and attributes using verified project domain terms and disk-backed database schemas.

Step 2. Design It Twice offer

Offer the user an exploratory multi-agent design pass before committing to a single interface.

Ask the user directly.

"Do you want to run a Design It Twice pass with parallel sub-agents to explore 2 to 3 contrasting interface designs, or proceed directly with a single design?"

• If the user accepts, consult references/design-it-twice.md and dispatch sub-agents using invoke_subagent.
• If the user declines, proceed directly to Step 3.

Completion criterion. Record user preference in .agents/state/codebase-design/decision.md with explicit line design_it_twice: accepted or design_it_twice: declined.

Step 3. Deep module and seam formulation

Formulate the interface and identify module boundaries using deep module principles.

1. Apply the deletion test. Imagine deleting the module. If complexity vanishes, the module is a shallow pass-through wrapper and should be merged or deleted. If complexity reappears across multiple callers, keep the module. Consult references/codebase-health-and-hotspots.md for git churn hotspot detection, deletion test execution, and architecture diagrams.
2. Minimize interface surface and reject line count metrics. Measure depth by power gained per unit of interface learned, never by lines of code ratio. Reduce public methods, simplify parameters, and design functions to return pure values instead of mutating state.
3. Classify dependencies across seams. Consult references/deepening.md to classify external touchpoints into in-process, local-substitutable, remote owned, or true external.
4. Enforce seam discipline. Follow the rule that one adapter represents a hypothetical seam, while two adapters represent a real seam. Do not introduce interface ports unless at least two concrete adapters exist.
5. Simplicity first and reuse hierarchy. Take the first option that fully works. Prioritize an existing codebase helper or pattern first, the standard library or platform feature second, an installed dependency third, and minimum new code last. Never add a dependency for a few lines. Never introduce abstractions, generics, or configurability layers for single-use code.
6. Shortcut discipline and essential boundaries. When taking an intentional implementation shortcut, mark it in code using shortcut: <the limit>, <when to upgrade>. Never cut trust boundary validation, data loss error handling, security invariants, or accessibility in the name of minimalism.
7. Align interface with test surface. Ensure callers and automated tests cross the same external seam. Do not leak internal test hooks into the public interface.
8. Subtract before you add. When evolving or refactoring a system, remove complexity first, then build. Sequence removal before construction. Delete dead code, redundant validation checks, and unused stub references before adding new capabilities. Leave the design simpler and more capable behind the same or smaller surface than you found it.
9. Migrate callers then delete legacy APIs. When introducing a new internal module interface, migrate all in-tree callers and purge the deprecated API in the same wave. Avoid long-lived compatibility shims, forwarding aliases, or wrapper layers for internal code. Update tests to assert the new contract, and delete tests that only protect pre-refactor implementation details.

Completion criterion. Interface specification file .agents/state/codebase-design/interface-spec.md exists on disk with headings ## Inputs, ## Outputs, ## Error states, and ## Seam placement.

Step 4. User review gate

Present the proposed interface design to the user before writing implementation code.

Cover these technical details:

• Module responsibility and what implementation logic sits behind it.
• Public interface signature and parameter types.
• Seam placement and adapter classifications.
• Automated testing strategy through the public interface.

Wait for explicit user approval. If the user requests adjustments, update the interface and repeat the review.

Completion criterion. Explicit user confirmation approving the interface design.

Step 5. Transition to implementation planning

Invoke the writing-plans skill to generate a phased implementation plan.

Pass the following envelope:

source_skill: codebase-design
source_spec_path: .agents/state/codebase-design/interface-spec.md
mode: Author

Completion criterion. The writing-plans invocation returns a plan path, and .agents/state/codebase-design/handoff.json exists on disk with plan_path matching the returned path and spec_path matching source_spec_path.

Core vocabulary

Use these architectural terms consistently:

Boundary isolation

Design module interfaces and contracts only. Do not write functional implementation code, run database migrations, or alter production runtime files during design specification.

Quick audit checklist

Run this check before finishing the skill execution: