codebase-design

State functional requirements, non-functional targets like scale and latency, and constraints first. Then decompose into deep modules where each interface is narrow relative to what it hides, choose mechanisms tied to requirements, and name the trade-offs of each option.

An ADR includes a title, status, date, deciders, context, the decision, options considered with comparison tables across complexity, cost, scalability, and team familiarity, a trade-off analysis, consequences, and action items. This skill generates that full structure.

Compare each option across complexity, cost, scalability, and team familiarity, then state what each makes easier and harder. Recommend one option with the driving requirement named, and record the outcome as an ADR.

A shallow module has an interface nearly as complex as the implementation it hides, so callers gain little abstraction. The fix is to deepen the module or move the boundary so the interface stays narrow and no internal details leak to callers.

Use the evaluate pass when a design proposal already exists and you want a critique. It reports findings such as shallow modules, leaked internals, misplaced seams, missing non-functional answers, and unstated trade-offs, each with a named fix.