maintainable-code-guidelines

name	maintainable-code-guidelines
description	The reviewer's maintainability lens on changed code, on top of the project's development, structure, and component rules. Covers naming and file organization, route-local vs shared abstraction boundaries, complexity/readability limits, magic-number and dead-code discipline, scope control, and SOLID/DRY/KISS/YAGNI judgment across the project's modules.
when_to_use	Use when reviewing maintainability or design of changed code — "readable", "too long", "refactor", "abstraction", or "should this live elsewhere".
user-invocable	false

Maintainable Code Guidelines

Apply these rules when reviewing the maintainability and design of any changed code. This is the reviewer's lens — flag violations and link to the developer-facing rule rather than restating it.

Naming and Organization

See naming-and-organization.md for:

• File names match the project's established file-naming convention (e.g., kebab-case) and any required co-located sibling files (such as a style-module pairing)
• Components, helpers, and data-access modules live in the correct directory tier (route-local before group-shared before global)
• New routes follow the project's own routing skill, if defined, and co-locate their required sibling files (props/types, not-found, social-image files)
• Identifier names match in/around the changed file's existing conventions

Abstraction Boundaries

See abstraction-boundaries.md for:

• New shared logic lives at the lowest tier that has more than one caller (route-local before group-shared before global)
• The server / client component boundary is split per the project's own component skill, if defined
• Domain-specific pipelines (such as a content-rendering pipeline) stay behind a single owning module, per the project's own domain skill, if defined

Complexity and Readability

See complexity-and-readability.md for:

• The project's configured Biome complexity/length thresholds are not silently bypassed
• Magic numbers and strings have a named constant or design token, with Biome's inline suppression directive (and a justifying comment) only when justified
• Dead code (unused imports, unreachable branches, commented-out blocks) is removed
• Missing doc-comments on changed public types/functions, restating comments, and comment-voice violations (rules owned by development-guidelines › code-quality)
• Inline TypeScript types are extracted into named aliases when reused

Scope Discipline

See scope-discipline.md for:

• The diff matches the stated user goal — no drive-by refactors per the project's development guidelines (change-management rules)
• Pre-existing problems are flagged separately, not bundled into this change
• New abstractions are justified by ≥ 2 concrete call sites (YAGNI)
• Repeated logic across the diff is consolidated only when the duplication is truly the same concern (DRY without coupling unrelated callers)