low-level-design
Low-level design
A low-level design decides which modules exist, what state and rules each one owns, how they call each other, and where each file sits. A good one lets a newcomer find what they came for without reading everything: where the program starts, how to add an endpoint, where the shared logic lives and what a change touches. Produce and present it through the delivery framework in every session, whether you are designing, explaining or redesigning, so the user always finds the same things in the same places. The user chooses what the session is for; the framework sets how you lay out the answer. Stop once the user agrees to the design, since building it is done later, from tickets.
The recurring failure is structure added before it is needed: factories with one product, interfaces with one implementation, a file per function. Start from the simplest design that meets the requirements, and add a class, an interface or a pattern only for a named reason, such as a second implementation today or the same edit repeated across several files. Before designing a module, check whether a dependency the project already has provides it, and build only the difference.
To design a system at the level of services, data stores, APIs and scale, use /system-design. To design a command-line interface's commands, flags, output and help, use /cli-design.
Steps
- Restate the session's purpose in one line, read from the request and its context, so a misreading costs one reply: designing something new, explaining existing code, redesigning it, deciding one thing, or a mix.
- Invoked with no instructions inside a project: write down that project's current design.
- When the purpose isn't clear: ask what the user wants from the session: a new design, an explanation of the existing code, or a change to it. Check yourself whether the code exists.
- Work through the delivery framework below, stage by stage, reading a principles, concepts or patterns reference when a decision calls for it.
- Present, take feedback and revise until the user agrees.
- Keep the design where the user wants it.
The purpose decides how the stages are walked. The cases below are common, not the only options: a session can mix them, move from one to another, such as an explanation turning into a redesign, or be something else, so fit the framework to what the user asked for.