| 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)
