code-quality

Files (1)

• SKILL.md

SKILL.md (first lines)

# Skill: code-quality

## Purpose

Keep code cohesive, explicit, maintainable, testable, and appropriately small.

This skill encodes SOLID, KISS, DRY, YAGNI, cohesion, coupling, and size discipline as practical rules rather than motivational office posters.

## Single Responsibility at Every Level

### Function

A function should do one coherent thing.

A function is suspicious when it:

- validates input;
- performs I/O;
- applies domain rules;
- mutates persistence;
- formats output;
- logs business events;
- handles retries;

all in one place.

Split by responsibility, not by arbitrary line count.

### Class / Type

A class/type should represent one role:

- domain state;
- lifecycle;
- policy;
- adapter;
- interface implementation;
- dependency grouping;
- stateful workflow.

Avoid god objects, vague managers, and classes that are just bags of unrelated methods.

### File / Module

A file/module should have one cohesive theme.

A file is suspicious when it contains:

- unrelated domain concepts;
- mixed layers;
- many independent public entry points;
- repeated section headers needed to understand it;
- several classes that change for unrelated reasons.

Do not create a `utils`, `helpers`, `common`, or `misc` dumping ground unless the repository already has that convention and the new code still has a cohesive purpose.

### Package / Component

A package/component should expose a clear public boundary.

It should not be a directory-shaped junk drawer.

Prefer package boundaries around:

- domain subareas;
- application use cases;
- infrastructure adapters;
- integration clients;
- UI/presentation areas;
- hardware responsibilities.

### Layer

A layer should have one architectural responsibility.

Do not mix transport, domain, persistence, configuration, and presentation concerns.

### Bounded Context

A bounded context should own one domain language and one model of reality.

Do not leak terms and invariants across contexts accidentally.

## Size Limits

Human-authored 10k-line files are forbidden.

Default thresholds for human-authored source:

- function over 60 logical lines: suspicious;
- function over 100 logical lines: split or justify;
- class/type over 300 logical lines: suspicious;
- class/type over 500 logical lines: split or justify;
- file/module over 800 logical lines: split or justify;
- file/module over 1,500 logical lines: strong refactor candidate;
- file/module over 10,000 logical lines: unacceptable except generated/vendor/lock content.

Generated, vendored, lock, and machine-produced migration files may be exceptions.

If a large file is unavoidable, document why and isolate growth behind clear sections or generated boundaries. Better yet, do not make it unavoidable. Humanity has suffered enough.

## KISS

Prefer simple, direct solutions.

Avoid:

- abstraction before evidence;
- clever generic code for one caller;
- framework-shaped code without a framework-sized problem;
- dynamic behavior that hides control flow;
- configuration-driven everything.

A 100-line TODO app should still be clean, typed, and testable. It does not need a fake enterprise architecture ceremony.

## DRY

Avoid duplication of knowledge, not merely duplicated text.

From Mesteriis/Engineering-Bible-AI, MIT.

More from Mesteriis/Engineering-Bible-AI