codebase-design · git:20260906.90262a6 · 2026-09-06 · sha256 29ee3e68e7de57d7

codebase-design git:20260906.90262a6A

Immutable. This exact content never changes and is served at /api/v1/blob/29ee3e68e7de57d7.

No tool to install first
claude plugin marketplace add https://markdownregistry.com/mp/a/art_imct5n5pqvcogwqs/29ee3e68e7de57d771ac55815362ca177782bcbc25972236354f157cbf817d61.json

Then /plugin install codebase-design@markdownregistry-imct5n5pqvcogwqs in Claude Code. It installs this exact version, the one graded A here, pinned to the commit it was graded at, and leaves it there.

---
name: codebase-design
description: Design or compare a specific module boundary, interface, dependency seam, or refactor. Use when the user wants concrete architecture options for a known design problem. For a broad repository audit that discovers and ranks architectural problems, use improve-codebase-architecture instead.
---

# Codebase Design

Read repository instructions, architecture docs, ADRs, specifications, and representative callers/tests before proposing structure. Established project terminology wins; use the vocabulary below only where it clarifies rather than replacing domain language.

Use this skill when the design target is already known. If the user wants you to search a wider codebase for opportunities, use `improve-codebase-architecture` first.

## Working vocabulary

- **Module**: code with an interface and implementation, at any scale.
- **Interface**: everything callers must know, including invariants and errors.
- **Seam**: a place behavior can vary without editing callers.
- **Adapter**: an implementation selected at a seam.
- **Depth**: useful behavior hidden behind a comparatively small interface.
- **Leverage**: capability gained by callers from that interface.
- **Locality**: related knowledge and change concentrated together.

Treat these as reasoning aids, not rules. A thin adapter can be valuable for isolation; a single adapter can justify a seam when tests, platform separation, security, or ownership require it.

## Analyze

1. Identify the change pressure, callers, dependencies, invariants, and current test surface.
2. Locate duplicated knowledge, leaked policy, pass-through abstractions, and changes that scatter across files.
3. Apply the deletion test: if removing a module merely redistributes its complexity to callers, it may be earning its keep.
4. Respect existing contracts and ADRs. Mark any proposal that would revise them.

## Design

Before adding structure, check whether existing code, the standard library, a platform capability, or an installed dependency already meets the requirement. Name the concrete candidate and compare its contract with the callers' needs. A matching API name is insufficient: check errors, ordering, lifetime, concurrency, and supported runtimes where they matter.

Include retaining the current design as an option when no demonstrated problem requires a change. Remove speculative extensions from proposals, but preserve requested behavior. Prefer the option with the lowest maintenance cost that satisfies the contract, even when it needs more lines or an additional dependency.

For example, a bounded memoization helper does not replace a cache that requires expiration, tenant isolation, or cross-process invalidation. A native control is a candidate only if it supports the required interactions and accessibility behavior. Keep validation, recovery, and useful test coverage in the comparison.

When a proposed simplification accepts a known limit, state that limit, an observable trigger for revisiting it, and the likely next step. Use the project's existing decision or debt convention if documentation is authorized. Do not create branded comments or a separate ledger for ordinary implementation choices.

Prefer small interfaces that hide policy and enable behavior-level tests. Dependency injection and pure returns are useful when they reduce coupling, but do not force them over idiomatic repository patterns.

For consequential designs, produce at least two genuinely different options and compare compatibility, migration cost, testability, locality, and operational risk. Read [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md) and [DEEPENING.md](DEEPENING.md) when deeper alternatives are needed. Sub-agents are optional.

Do not implement, create ADRs, or update domain documentation during design analysis unless the user authorizes those changes.