agentleFS
Carlososuna11Carlososuna11/claude-skills/skills/no-premature-abstraction/SKILL.md

no-premature-abstraction

Skill0 starsChanged 5 months agoMITView on GitHub

Usar antes de proponer una nueva tabla, clase, helper, capa, decorator, estado global, URL param, o cualquier abstracción que vaya más allá del scope del problema concreto. También cuando el impulso es "ya que estoy acá, refactorizo esto otro" o "agrego este flag por si en el futuro".

The file

Files
SKILL.md

No Premature Abstraction

Overview

Agregar features, refactors o abstracciones más allá de lo que el problema concreto pide es la causa principal de PRs sobre-scopeados, deuda escondida, y código que nadie usa.

Principio: YAGNI. Tres líneas similares es mejor que una abstracción prematura. Diseñar para hoy, no para el "por si acaso" hipotético.

Anunciar al inicio: "Aplicando no-premature-abstraction — evaluando si esta abstracción es necesaria ahora."

Qué cuenta como abstracción prematura

  • Crear una clase/función genérica cuando hay un solo caller.
  • Agregar un parámetro opcional "por si lo necesitamos después".
  • Crear una nueva tabla cuando el campo cabe en una existente.
  • Crear un módulo nuevo para tres líneas que viven bien en el actual.
  • Generalizar un helper antes de tener el segundo caso de uso.
  • Agregar un feature flag para algo que el usuario no pidió.
  • Refactorizar código ajeno al fix actual "ya que estoy acá".
  • Crear capas de indirección (service → repository → mapper → DTO) cuando el problema cabe en una.

Step 1: ¿El problema concreto pide esto?

Antes de proponer la abstracción, escribir el problema concreto en una oración:

"El bug es: cuando un usuario X hace Y, el sistema Z falla con W."

Luego escribir la solución mínima:

"Mínimo: cambiar línea N para que Z no falle cuando Y."

Si tu propuesta agrega más cosas que esa solución mínima, detenerse y justificar cada extra. "Lo agregué de paso" no es justificación.

Step 2: ¿Realmente hay un segundo caso de uso?

Regla de tres: no abstraer hasta el tercer caso real.

Cantidad de casosAcción correcta
1 casoHardcoded, sin abstracción
2 casosDuplicar; revisar si vale la pena abstraer en el tercero
3+ casosConsiderar abstraer, evaluando si los casos comparten forma además de nombre

Casos que parecen iguales pero divergen rápido producen abstracciones peores que la duplicación. Ejemplo típico: "estos dos forms son iguales" → al mes son diferentes y la abstracción común te traba.

Step 3: ¿Quién es el dueño del dato / lógica?

Si el problema toca datos que tiene otro módulo, no copiar el dato para resolverlo localmente — usar el módulo dueño.

Ejemplo de antipatrón: agregar userTier en la tabla transactions para "evitar el join" cuando users.tier ya existe. Eso duplica estado y crea problemas de sincronización.

Reglas:

  • Si el dato vive en X, X es la fuente de verdad. No copiar a Y.
  • Si la lógica vive en X, invocarla desde Y. No reimplementar.
  • Si el patrón existente cubre el caso (con ajuste menor), usarlo (ver skill reuse-existing-patterns).

Step 4: Distinguir cleanup oportuno vs scope creep

A veces tocar código relacionado sí es válido — pero hay una distinción clara:

Sí: cleanup oportunoNo: scope creep
Renombrar un símbolo que tu cambio rompeRenombrar todo el módulo "ya que estoy"
Borrar un import que tu cambio dejó inútilReformatear el archivo entero
Agregar un test para el bug que arreglasAgregar tests para todo lo que esté cerca
Actualizar un comentario que ahora es incorrectoReescribir comentarios viejos del archivo
Corregir un typo que ves en una línea que tocasHacer typo-sweep al repo

Regla: si lo que vas a tocar no tiene relación causal con el problema concreto, no lo toques en este PR. Abre un PR aparte.

Step 5: Half-finished implementations son peores que no hacerlas

Si el problema requiere una abstracción completa y no tienes tiempo para hacerla bien, mejor no empezarla. Una abstracción a medias:

  • Implica que existe, pero no la cubre.
  • Otros devs la encuentran y la usan creyendo que está completa.
  • Genera bugs cuando se descubre que el caso N no estaba cubierto.

Opciones cuando no hay tiempo:

  • Hardcoded ahora, abstraer cuando exista el tercer caso real.
  • Abrir issue documentando el diseño pendiente para no perder el contexto.
  • No abstraer, no abrir issue, no dejar nada a medias.

Quick Reference

SituaciónAcción
Mi propuesta agrega cosas al scope originalStep 1: justificar cada extra
Es el primer caso de usoNo abstraer; hardcoded está bien
Es el segundo casoDuplicar; evaluar abstraer en el tercero
Los dos casos "parecen iguales"Verificar si comparten forma o solo nombre
Voy a copiar un dato de otro móduloStep 3: usar el módulo dueño en su lugar
Estoy renombrando porque mi cambio rompeCleanup oportuno: OK
Voy a reformatear todo el archivoScope creep: separar PR
No tengo tiempo para hacer la abstracción bienStep 5: hardcoded ahora o no empezar

Common Mistakes

  • "Lo agregué de paso." Cualquier extra fuera del scope necesita justificación explícita.
  • Abstraer al segundo caso. Esperar al tercero — los dos primeros suelen divergir.
  • Duplicar un dato del módulo dueño "para evitar el join". Crea problemas de sincronización peores que el join.
  • Refactorizar código ajeno "ya que estoy". Eso es un PR aparte.
  • Half-finished implementations. Mejor no empezar que dejar a medias.
  • Feature flag para algo que el usuario no pidió. YAGNI.

Red Flags

Nunca:

  • Agregar features, refactors o helpers que no estén en el scope del problema concreto.
  • Abstraer al segundo caso de uso sin verificar que comparten forma.
  • Duplicar datos que ya tiene otro módulo en su tabla.
  • Dejar implementaciones a medias creyendo "el siguiente las completa".
  • Agregar parámetros opcionales "por si los necesitamos".
  • Hacer cleanup masivo en un PR que tiene scope acotado.

Siempre:

  • Escribir el problema concreto en una oración antes de proponer la solución.
  • Justificar cada extra fuera de la solución mínima.
  • Usar el módulo dueño cuando necesites su dato/lógica.
  • Separar cleanups en PRs aparte si no son causalmente parte del fix.
  • Preferir tres líneas similares a una abstracción prematura.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.