engineering-principles

Engineering Principles

The non-negotiable rules every coding skill in this pack must follow. AI agents tend to emit code as if there is no tomorrow: duplicate components, monolithic files, fresh abstractions instead of reuse, no types, no structure. This document exists to stop that.

Every architecture, review, and interface skill inherits these rules. Specific roles add detail on top, but never relax them.

When to use

Always, whenever you write or modify production code. This is a cross-cutting concern.

1. DRY — reuse before creating

Delegated to the dedicated meta skill: meta/reuse-before-create.

That skill is the single source of truth for the reuse-vs-create decision: the strict ordering (reuse → extend → compose → extract → create new), the mandatory one-line justification when creating, the per-artifact-type search strategies, and the "don't trust names alone" rule.

Do not duplicate that logic in this skill or any other. Inherit it, follow it.

2. File and function size

Code is read more than written. Optimise for the next reader.

Unit	Soft limit	Hard limit
Function	40 lines	80 lines
React component	150 lines	250 lines
File	250 lines	400 lines
Class	200 lines	350 lines

When you approach the soft limit, split. Hitting the hard limit without splitting is a code smell to flag in review.

Splitting strategies:

• Extract sub-components for distinct UI regions
• Pull pure helpers into the same folder, import locally
• Move types to a types.ts next to the file
• Group related functions into a class or module if they share state

3. Single responsibility

A function, component, hook, or module does one thing. If you can't describe what it does in a single sentence without "and", split it.

Common violations:

• A component that fetches data, renders UI, and handles navigation — split into hook + UI
• A util that validates AND transforms — make two functions
• A "manager" class with 12 methods — likely 3 modules pretending to be one