This codebase follows a rule-driven, semantic-first design model. The goal is to reduce ambiguity, minimize cognitive load, and keep the system easy to reason about as it grows.
Do not introduce new structure without a clear, deliberate reason.
When writing or changing code, follow these principles strictly.
- Always choose clear, absolute rules instead of flexible conventions.
- Avoid patterns that require interpretation or context to understand.
- If two options exist, pick one and make it the rule.
- Each module, section, or namespace should represent one clear concept.
- Do not group unrelated behavior together.
- If something does not fit cleanly, the design is wrong.
- Names must describe what something is, not how it works.
- Avoid names based on temporary implementation choices.
- Prefer stable concepts over technical mechanisms.
- Keep different dimensions separate:
- Domain (auth, user, billing)
- Runtime (server, client, worker)
- Responsibility (routing, rendering, persistence)
- Never mix these in the same abstraction.
- Prefer small, closed systems with limited states.
- Avoid designs that allow many variations or loose combinations.
- The structure should guide the developer to the correct choice.
- The shape of the code should make the architecture obvious.
- Do not hide structure behind abstractions.
- If something is hard to place, the design is wrong.
- One unit (function, class, module) = one clear responsibility.
- No "do everything" helpers.
- If a unit grows, split by responsibility, not by convenience.
- Avoid magic, dynamic behavior, and implicit contracts.
- Prefer explicit code, even if it is more verbose.
- Readability and predictability are more important than brevity.
- Assume this code will be read in 10+ years.
- Optimize for clarity, not speed of writing.
- Fewer options is better than more options.
- If something can be removed, remove it.