feat: 1995

.agents/rules/quality.md

@@ -0,0 +1,34 @@
+---
+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.