System Design
Produce the smallest design that satisfies today's stated requirements and name what would justify more. Every component, process, dependency, and abstraction is a cost that must buy a named requirement.
Fix the constraints
- Extract the actors, the jobs they need done, and the observable outcomes that define success.
- Record load, data volume, team size, delivery horizon, deployment target, and hard constraints such as compliance, latency, or an existing platform. When a value is unknown, assume the smallest plausible value, write the assumption down, and design for it. Never design for unknown scale.
- In an existing codebase, find the owning module, its current contract, conventions, runtime shape, and deployment path before proposing anything. Use
system-investigate when current behavior is unclear.
- Write non-goals: capabilities, scales, and actors the design intentionally excludes.
Design from the baseline
- Start from the baseline: one deployable process, the datastore already in use or the most boring option, synchronous calls, no new infrastructure. For a feature, the baseline is a change inside the owning module.
- Add a component, process, queue, cache, service boundary, framework, or dependency only when a stated requirement or measured constraint fails without it. Name that requirement next to the addition.
- Spend design effort on decisions that are expensive to reverse, such as the storage model, public contracts, and tenancy. Keep everything else deferrable.
- Reject additions justified by scalability, extensibility, flexibility, future-proofing, best practice, or how a larger organization solves the problem. Reject an abstraction with one consumer.
- Give each module one decision to own and one representation to hide. Do not split by technical layer or workflow step.
Check the design
- Walk each actor's main job through the design end to end. Remove anything the walk does not touch.
- Apply failure, retry, idempotency, migration, rollout, and security requirements only where a walk crosses a trust boundary, a state change, or an external system. Record the rest as deferred with the trigger that makes each relevant.
- Estimate processes, external dependencies, modules, and rough lines of code. When the estimate exceeds what the team can build and operate within the horizon, cut components or scope, not quality.
- State the strongest simpler alternative and the named requirement it fails. If it fails none, adopt it.
Use architecture-refine when the user must choose between remaining options, technical-spike for a blocking external fact, alternatives-explore for a contrarian bet, and plan-create to turn the accepted design into phases. Do not implement, write a plan, or edit repository documents unless authorized.
Result
Report the requirements and assumptions with values, non-goals, each component with the requirement it satisfies, the data flow for each main job, deferred concerns with triggers, the size estimate, the rejected simpler alternative, and open decisions. Finish when every component traces to a requirement and every excluded concern has a trigger.
1---2name: system-design3description: Design the smallest system or feature architecture that satisfies stated current requirements, for a greenfield product or a new capability in an existing codebase. Use when the user wants a proposed design with components, non-goals, and growth triggers; not for investigating existing behavior, settling one open decision, or planning phases.4---56# System Design78Produce the smallest design that satisfies today's stated requirements and name what would justify more. Every component, process, dependency, and abstraction is a cost that must buy a named requirement.910## Fix the constraints11121. Extract the actors, the jobs they need done, and the observable outcomes that define success.132. Record load, data volume, team size, delivery horizon, deployment target, and hard constraints such as compliance, latency, or an existing platform. When a value is unknown, assume the smallest plausible value, write the assumption down, and design for it. Never design for unknown scale.143. In an existing codebase, find the owning module, its current contract, conventions, runtime shape, and deployment path before proposing anything. Use `system-investigate` when current behavior is unclear.154. Write non-goals: capabilities, scales, and actors the design intentionally excludes.1617## Design from the baseline18191. Start from the baseline: one deployable process, the datastore already in use or the most boring option, synchronous calls, no new infrastructure. For a feature, the baseline is a change inside the owning module.202. Add a component, process, queue, cache, service boundary, framework, or dependency only when a stated requirement or measured constraint fails without it. Name that requirement next to the addition.213. Spend design effort on decisions that are expensive to reverse, such as the storage model, public contracts, and tenancy. Keep everything else deferrable.224. Reject additions justified by scalability, extensibility, flexibility, future-proofing, best practice, or how a larger organization solves the problem. Reject an abstraction with one consumer.235. Give each module one decision to own and one representation to hide. Do not split by technical layer or workflow step.2425## Check the design26271. Walk each actor's main job through the design end to end. Remove anything the walk does not touch.282. Apply failure, retry, idempotency, migration, rollout, and security requirements only where a walk crosses a trust boundary, a state change, or an external system. Record the rest as deferred with the trigger that makes each relevant.293. Estimate processes, external dependencies, modules, and rough lines of code. When the estimate exceeds what the team can build and operate within the horizon, cut components or scope, not quality.304. State the strongest simpler alternative and the named requirement it fails. If it fails none, adopt it.3132Use `architecture-refine` when the user must choose between remaining options, `technical-spike` for a blocking external fact, `alternatives-explore` for a contrarian bet, and `plan-create` to turn the accepted design into phases. Do not implement, write a plan, or edit repository documents unless authorized.3334## Result3536Report the requirements and assumptions with values, non-goals, each component with the requirement it satisfies, the data flow for each main job, deferred concerns with triggers, the size estimate, the rejected simpler alternative, and open decisions. Finish when every component traces to a requirement and every excluded concern has a trigger.
yarlson