yonathan-boop/Claude

antislop-code

Anti Slop: Reglas para Agentes de Codificación IA. Skill de Comentarios de Código

Parte del sistema antislop. Debe leerse junto con antislop.md (el núcleo). Este skill filtra comentarios que suenan genéricamente a IA (decorativos, que repiten lo obvio, rígidos, ruidosos) mientras preserva los comentarios que transmiten información real. Hace referencia a las reglas del núcleo por número y nunca las duplica ni las renombra. Cárgalo cuando la tarea escriba o edite comentarios de código.

Cómo usar este skill

• Cargar junto con antislop.md siempre que la tarea toque comentarios de código. El núcleo contiene el mecanismo (la prueba de propósito, los tres niveles, la Puerta de Entrega); este skill contiene la profundidad específica de comentarios.
• Cada entrada tiene la misma estructura: Qué (el patrón), Por qué (por qué se lee como slop), Solución (qué hacer en su lugar), con la regla del núcleo citada como R-XX.
• Guardarraíl de alcance: este skill solo modifica comentarios. Nunca modifiques código ejecutable, identificadores, importaciones, formato, indentación, espacios en blanco, flujo de control o lógica. En caso de duda, deja el código intacto.
• La Puerta de Entrega del núcleo sigue siendo la puerta. El "Checklist de Comentarios de Código" al final de este archivo es el suplemento específico para comentarios que debe ejecutarse junto con ella.

Comentarios que No Aportan Nada

Separadores Decorativos

• Qué: comentarios tipo banner construidos con caracteres repetidos, etiquetas en MAYÚSCULAS o recuadros alrededor de un nombre de sección: // ======================= alrededor de Autenticación, // -------- FLUJO DE TRABAJO --------, o un encabezado /* ---- RUTAS ---- */.
• Por qué: la decoración es el mensaje. Una etiqueta envuelta en = o - señala "Esto lo hizo la IA" sin añadir información, y las MAYÚSCULAS suenan a gritos.
• Solución: reemplázalo con una sola línea simple, o elimínalo por completo si la etiqueta no aporta nada (R-31).

Repetir lo Obvio

• Qué: un comentario que repite lo que la siguiente línea o declaración ya muestra, como // Inicializa la variable encima de let count = 0, // Clase Usuario encima de class Usuario {}, // Valida usuario encima de function validaUsuario(), o const edadUsuario = 25; // La edad del usuario es 25.
• Por qué: duplica la carga de lectura sin añadir nada. El código ya lo dice; el comentario solo lo repite.
• Solución: elimínalo y deja la línea de código intacta.

Narración del Flujo de Trabajo

• Qué: comentarios que narran el flujo paso a paso, como // Paso 1: Validar entrada, // Paso 2: Procesar solicitud, // Paso 3: Devolver respuesta, o // Primero..., // Luego..., // Finalmente....
• Por qué: el flujo de control es visible en el código mismo. Numerarlo parece una lista de verificación, no una explicación.
• Solución: elimínalo. Si el flujo es genuinamente difícil de seguir, es un problema de estructura, no de falta de comentarios.

Etiquetas Vacías

• Qué: etiquetas genéricas sin información detrás: // Lógica principal, // Lógica central, // Lógica de negocio, // Función auxiliar, // Punto de entrada, // Manejo de errores, o // Nota: Esto es importante / // Importante: Por favor lee.
• Por qué: la etiqueta nombra una categoría, no un hecho. "Lógica principal" no le dice al lector nada que no pueda inferir del código.
• Solución: elimínalo a menos que la etiqueta lleve información específica. "Nota: los reintentos ocurren solo en 5xx" merece su lugar; "Nota: esto es importante" no.

Marcadores de Posición Vagas

• Qué: comentarios que prometen trabajo futuro sin decir qué: // TODO: Mejorar esto, // Mejoras futuras, // Se puede añadir optimización adicional aquí, // Añadir más validación.
• Por qué: un TODO vago es ruido. Nombra un sentimiento (esto podría ser mejor) en lugar de una tarea (qué, y por qué).
• Solución: elimínalo. Conserva un TODO solo cuando nombre una tarea específica con suficiente contexto para actuar.

Eco de Firma

• Qué: documentación que solo repite la firma, como un bloque JSDoc que repite @param precio El precio. y @returns Precio total. para una función cuyo nombre y parámetros ya lo dicen todo.
• Por qué: la documentación que repite la firma añade longitud, no comprensión. El lector no aprende nada nuevo.
• Solución: simplifica o elimina el eco. Conserva documentación que explique reglas de negocio, casos límite, suposiciones, algoritmos, limitaciones, efectos secundarios, comportamiento de API o implicaciones de seguridad. Nunca elimines documentación real.

Emoji Decorativo

• Qué: emojis usados como decoración en comentarios, como // ✅ Validación o // 🚀 Rendimiento.
• Por qué: los emojis son ruido visual en el código, y el conjunto específico (✅, 🚀, 🔒) es el vocabulario predeterminado de la IA.
• Solución: reemplázalos con inglés simple, o elimínalos si la etiqueta no aporta nada.

Marcadores de Fin

• Qué: comentarios que solo marcan el final de un bloque, como } // fin si, # Fin de la función, o // Fin de procesarPedido.
• Por qué: la llave de cierre ya termina el bloque. El marcador existe por costumbre, no por necesidad.
• Solución: elimínalo. En el raro caso de que un marcador de fin ayude genuinamente en un archivo largo, consérvalo solo donde evite confusión, no por costumbre.

Cómo Debería Leerse

El Comentario Sobreexplicado

• Qué: un comentario que se extiende por varias líneas, acumulando razones, contexto e historia alrededor de un hecho que cabe en una línea: un bloque de cuatro líneas que explica que un stub está en PATH, qué versión introdujo la solución alternativa, y qué se rompió antes. Cada frase es cierta. La longitud es la señal.
• Por qué: una persona deja una nota, un generador escribe un caso. Rellenar un hecho de una línea en un párrafo, construir una cadena "porque X, entonces Y, y por lo tanto Z", o citar el número de incidencia y la versión que lo solucionó son el mismo adorno que cualquier otro patrón de IA, y entierran la línea que importa bajo las que no.
• Solución: recórtalo solo a la restricción: una línea, dos como máximo, nunca tres. Conserva la trampa de plataforma, el fallo silencioso, la regla de protocolo, el coste de rendimiento. Elimina el número de incidencia, el historial de versiones y la cadena de razonamiento.

Narración Línea por Línea

• Qué: un comentario en cada declaración trivial, narrando cada línea a medida que se escribe: // Inicializa contador, luego // Recorre elementos, luego // Obtiene elemento, luego // Incrementa, luego // Devuelve resultado.
• Por qué: cuando cada línea está comentada, ninguno de los comentarios importa. El lector tiene que revisar cada uno para encontrar el que tiene significado.
• Solución: escribe un comentario conciso por bloque lógico en lugar de uno por línea. Si el bloque no necesita comentario, no escribas ninguno.

Redacción Rígida o Ruidosa

• Qué: comentarios que suenan formales, largos o a gritos: "Esta función es responsable de validar si las credenciales suministradas son válidas antes de continuar con el proceso de autenticación", o // LÓGICA PRINCIPAL en mayúsculas.
• Por qué: la redacción formal y ruidosa suena generada, no como un ingeniero dejando una nota para la siguiente persona.
• Solución: escribe líneas cortas en minúsculas con voz natural de desarrollador: // Valida credenciales antes de emitir un token. Los buenos comentarios explican por qué, no qué, y se mantienen cortos.

No es una Prohibición (conserva estos)

Nunca elimines comentarios que expliquen:

• lógica de negocio e intención
• decisiones arquitectónicas
• consideraciones de seguridad
• compensaciones de rendimiento
• comportamiento de concurrencia
• detalles de protocolo
• contratos de API
• soluciones alternativas
• casos límite y suposiciones
• licencias y avisos legales

Ejemplo que debe permanecer:

// Stripe puede reintentar entregas de webhook hasta por tres días.
// Ignora eventos duplicados usando el ID del evento.

Un comentario gana su lugar cuando explica algo que el código no muestra: la razón, la restricción, el comportamiento no obvio.

Ganar un lugar dice qué puede quedarse, nunca cuánto tiempo puede ocupar. Una nota de solución alternativa ocupa una línea sobre la solución alternativa, no un párrafo. El ejemplo anterior tiene dos líneas porque dos hechos son reales, no porque dos líneas sean un objetivo. Esta lista es la razón más común por la que un comentario sobrevive a una revisión que no debería: el contenido es legítimamente valioso, por lo que la longitud no se examina. El valor no es longitud.

Checklist de Comentarios de Código

Ejecuta estos junto con la Puerta de Entrega del núcleo cuando la tarea toque comentarios. Todas las respuestas deben ser sí:

• ¿Cada comentario añade información que el código no muestra? (R-31)
• ¿Los comentarios evitan separadores decorativos, banners en MAYÚSCULAS y encabezados con recuadros?
• ¿Los comentarios evitan repetir lo obvio de la línea, declaración o firma?
• ¿Los comentarios evitan la narración paso a paso del flujo de trabajo?
• ¿Los comentarios evitan etiquetas vacías y TODOs vagos que no nombren ninguna tarea?
• ¿Los comentarios evitan emojis decorativos y marcadores de fin?
• ¿La densidad de comentarios es de uno por bloque lógico, no uno por línea?
• ¿Cada comentario tiene una línea, o dos solo cuando la segunda aporta un hecho nuevo?
• ¿Los comentarios restantes se leen cortos, naturales y en minúsculas?
• ¿Se mantiene el guardarraíl de alcance: solo se modificaron comentarios, el código intacto?