code-quality-guidelines

Code Quality Guidelines

Purpose

Keep every implementation change understandable, reviewable, and safe to extend. This is the general engineering baseline for all code changes, regardless of language or framework.

When to use it

• Before implementing any non-trivial code change.
• When touching shared utilities, public APIs, core flows, or files that already feel tangled.
• During /fix when a quick patch could create hidden coupling.
• During /review to identify maintainability issues that are likely to become defects, not as a style nit checklist.

Instructions

1. Start from the existing repository style and architecture. Prefer consistency over personal taste unless the existing pattern is actively unsafe.
2. Keep the change cohesive: one reason to change per function/module/component. Split only when it reduces coupling or clarifies ownership.
3. Make data flow explicit. Avoid hidden global state, temporal coupling, action-at-a-distance side effects, and "magic" behavior.
4. Prefer clear names and small interfaces over comments explaining confusing code. Comments should explain why, constraints, or non-obvious tradeoffs.
5. Isolate edge-case handling near the boundary where the edge case enters: parsing, validation, I/O, user input, external services, or persistence.
6. Preserve type safety and invariants. Do not widen types, use unchecked casts, or make optional/null states more ambiguous to get a patch through.
7. Keep dependencies boring. Do not add a dependency, framework, abstraction, or global helper unless the spec or repeated local need justifies it.
8. Make failure behavior deliberate: errors should be actionable, logged or surfaced at the right layer, and not swallowed silently.
9. Add or update tests around changed behavior, including at least one regression test for a bug fix and one edge case for new logic when applicable.
10. Run the smallest meaningful validation first, then the configured gates.