Clean Code Law

Small files, no repetition, no speculation. Any developer must be able to edit the codebase without going mad in thousand-line files.

The 250-word rule

• Budget: ≤250 words per source file (whitespace-separated tokens, code and comments). Hard cap: 350 when splitting would genuinely harm cohesion.
• Enforced by the file-size-gate hook — an oversized write comes back to you with instructions; split before continuing.
• Exempt: docs (*.md), lockfiles, generated files, migrations, JSON/YAML data, vendored code. Config lives in rules (domain code) and can be tuned.
• Why: small files are readable, reviewable, independently testable, cheap for agents to load, and force real module boundaries.

How to split (in preference order)

1. Extract pure helpers into a sibling module the file imports.
2. Split by responsibility (parsing vs validation vs IO), never by line count.
3. Component files: one component per file; hooks into hooks/; variants into a variants.ts.
4. If a file resists splitting, the design is wrong — fix the design.

DRY (never repeat yourself)

Before writing anything, check it doesn't already exist: code-review-graph (semantic_search_nodes) or repo search. If it exists, import it. If it almost exists, extend it where it lives. A bug fix goes in the shared function all callers route through — never patched per-caller.

Ponytail alignment (the ladder is law here too)

Does it need to exist? → reuse in-repo → stdlib → native platform → installed dep → one line → only then minimal new code. No interfaces with one implementation, no config for constants, no scaffolding "for later".

Classes & modules (one job each)

• Single responsibility: a class/service does one thing — a UserService fetches/mutates users, it doesn't also send emails or format API responses. If a class needs "and" to describe it, split it.
• Dependency injection over globals: pass a db session/client into a constructor or function param — never import a singleton connection deep in business logic. Makes testing and swapping impls trivial.
• No god objects: a class that grows a new method for every feature is a design smell — extract collaborators instead of adding methods.
• Prefer plain functions over a class with one method; reach for a class only when you need to hold state across calls (a service with a shared client, a stateful parser) — ponytail applies to OOP too.

Comments

Premium and sparse: only constraints the code cannot show (invariants, gotchas, external contracts, ponytail: ceiling notes). Never narrate what the next line does. No dead code, no commented-out blocks.

Every non-trivial file leaves one check

A branch/loop/parser/money/security path ships with the smallest runnable check that fails if the logic breaks (an assert self-check or one tiny test). No frameworks unless the project already has one.