35 lines
1.8 KiB
Markdown
35 lines
1.8 KiB
Markdown
|
---
|
||
|
|
alwaysApply: true
|
||
|
|
---
|
||
|
|
|
||
|
|
# Quality Guardrails
|
||
|
|
|
||
|
|
Use these while building. Do not turn every task into a full review; apply as lightweight pressure before adding or changing structure.
|
||
|
|
|
||
|
|
## Module Shape
|
||
|
|
|
||
|
|
- Filenames should match the primary export exactly, including casing.
|
||
|
|
- Exports and higher level functions should appear before private functions in a file.
|
||
|
|
- Prefer a primary type plus matching namespace for behavior tied to that type.
|
||
|
|
- Functions that operate on a domain type should live in that type's namespace.
|
||
|
|
- Avoid scattered single-name function exports for domain-specific behavior.
|
||
|
|
- Truly generic helpers may stay standalone when they do not naturally belong to a domain type.
|
||
|
|
|
||
|
|
## Design Pressure
|
||
|
|
|
||
|
|
- DRY: centralize rules and policy, not incidental similarity.
|
||
|
|
- KISS: prefer the smallest clear structure that solves the actual problem.
|
||
|
|
- YAGNI: do not add speculative extension points, options, compatibility layers, or abstractions.
|
||
|
|
- SOC: keep parsing, validation, IO, orchestration, and policy separate when mixing them creates change pressure.
|
||
|
|
- Cohesion: each module/type/function should have one clear job and one clear reason to change.
|
||
|
|
- Coupling: avoid making callers know protocol internals, nested implementation details, or unrelated runtime policy.
|
||
|
|
- Locality: one behavior should not require excessive jumping across unrelated files or helpers.
|
||
|
|
- Naming/API Clarity: names should expose behavior and domain meaning; avoid vague wrappers, false promises, and boolean-blind APIs.
|
||
|
|
|
||
|
|
## Refactor Bias
|
||
|
|
|
||
|
|
- Prefer moving behavior to the domain owner over creating utility bags.
|
||
|
|
- Prefer local private helpers over exported helpers until another real caller exists.
|
||
|
|
- Prefer deleting compatibility code when there are no shipped consumers, persisted data, or explicit requirements.
|
||
|
|
- Prefer small reshapes that preserve behavior over broad rewrites.
|