El skill que revisa mi código antes que yo: optimizar-codigo + un loop MAA

Contexto

Tengo un repo grande con ~30 endpoints en app/api/cms/deals/[id]/** y mecánica de Mongo repetida en cada uno. Cada vez que toco un endpoint para arreglar un bug, el mismo bug suele estar en otros tres archivos que no abrí. Es el costo de no haber separado orquestación (auth, RLS, transición de estado) de mecánica reusable (abrir la colección, hacer el update, parsear la respuesta) desde el principio.

El síntoma clásico: arreglo el bug en un endpoint, lo doy por cerrado, dos semanas después aparece en otro path porque ese endpoint también tenía la copia local del mismo código mal escrito.

Qué hicimos

Construí skills/optimizar-codigo/SKILL.md. No es un linter, no es un formateador. Es una disciplina de estructura que se activa cada vez que toco un archivo en app/api/**/route.ts o lib/**/*.ts:

1. Lee el archivo completo (no excerpts).
2. Clasifica cada bloque: ¿es regla de dominio (action) o mecánica reusable (service)?
3. Hace Grep en el resto del repo para ver si esa mecánica ya existe en otro caller.
4. Si hay 2+ callers que repiten la misma mecánica, propone extraer a lib/<dominio>/<nombre>.ts con API explícita y return estructurado.
5. Si hay 1 solo caller, no extrae — eso es sobre-abstracción.
6. Si detecta dos patrones contradictorios (en mi caso, lib/integraciones/ y lib/integrations/ conviviendo), los nombra como conflicto y exige auditoría aparte. No los mezcla.

La regla más importante del skill: un cambio a la vez. Si encuentra 3 mecánicas duplicadas, extrae una, verifica, y después sigue. Nada de refactor masivo en un commit.

Dónde entra MAA

Esto es lo que cambia el juego. Un skill aislado dura una semana — lo invoco, mejora un archivo, y se olvida. Sin ciclo de retroalimentación, la disciplina se diluye.

Por eso lo conecté al método Medir – Analizar – Actuar que aplica a todo lo que hago (regla global del CLAUDE.md, inspirada en la charla de Jared Friedman sobre empresas-ciclo):

• Medir: cuántas veces el mismo bug aparece en más de un caller. Cuántas funciones nuevas en lib/ se reusan en 2+ lugares vs las que mueren con 1 solo caller. Cuántos endpoints del CRM siguen abriendo la colección de Mongo inline. Si no puedo contarlo, no puedo mejorarlo.
• Analizar: comparar contra la base de hace dos semanas. ¿Está bajando la duplicación? ¿Está subiendo la reusabilidad de los services? ¿O estoy extrayendo abstracciones que nadie usa?
• Actuar: ajustar el skill. Si la métrica dice que estoy sobre-extrayendo, endurezco la regla del segundo caller. Si dice que sigo dejando duplicación, reviso por qué el hook automático no está disparando.

El skill aplica la disciplina en cada commit. El loop MAA verifica cada semana que la disciplina está moviendo la métrica correcta. Sin el loop, el skill se convierte en otra regla que nadie aplica.

Resultado

Lo que se ve hoy en el repo:

• skills/optimizar-codigo/SKILL.md listo y conectado al hook automático en .claude/settings.json.
• Conflicto activo nombrado y pendiente: lib/integraciones/ vs lib/integrations/. No lo resolvió inline. Lo dejó marcado para auditoría aparte, que es exactamente el comportamiento que quería.
• 14 archivos en app/api/cms/deals/[id]/** con cambios sin commitear — los voy a procesar uno por uno, no en batch, justo como manda la regla 1 del skill.

Lo que NO está hecho todavía:

• El sensor de medición. Hoy no estoy contando duplicación automáticamente; tengo que armar un script que grepee patrones repetidos en app/api/**/route.ts y dé un número semanal. Sin ese número, el bloque "Medir" del MAA es opinión, no dato. Eso entra al backlog del fin de semana.

Lo que opino

Tres cosas que aprendí construyendo esto:

Primero: un skill sin loop es una opinión bien escrita. Llevo seis meses construyendo skills (cotización, propuesta, cierre de sesión, infografico, voz-gnb). Los que sobreviven son los que tienen métrica detrás. Los que se mueren son los que armé "porque sonaba bien". Este skill no sobrevive sin el sensor de duplicación. Tengo que construirlo o aceptar que va a decaer.

Segundo: la disciplina de "un cambio a la vez" es lo más difícil de respetar. Mi instinto natural es "ya que estoy abriendo este archivo, arreglo los otros tres". El skill prohíbe eso explícitamente, y por algo: el refactor masivo es donde se cuelan los bugs que tardan meses en aparecer. El skill me obliga a parar después de cada extracción y verificar — incluso cuando "todo se ve igual".

Tercero: nombrar conflictos en vez de promediarlos cambia cómo se piensa el código. El conflicto entre lib/integraciones/ y lib/integrations/ lleva meses ahí. Mi tentación siempre fue "lo arreglo cuando tenga tiempo". El skill lo marca como deuda nombrada con dueño, no como TODO flotante. Esa distinción importa: una cosa es saber que algo está mal, otra es tener el conflicto registrado en una regla que se activa en cada commit hasta que se resuelva.

Aprendizaje clave

El código no mejora por buenas intenciones, mejora por loops cerrados. Skill + métrica + revisión semanal = mejora compuesta. Skill solo = nota en Notion.