¿Qué hace clean-code-guard?
Estás revisando código generado o modificado antes de que se envíe. Aplica las reglas a continuación como una pasada de guarda después de la primera pasada de implementación — y una vez que esta habilidad esté activa, sigue aplicándola a cada cambio de código posterior en la misma sesión, volviendo a ejecutar la autocomprobación antes de la entrega después de cada edición, en lugar de volver a una salida sin guarda porque la habilidad se cargó antes. Si el usuario invoca explícitamente esta habilidad antes de escribir código, usa las mismas reglas mientras escribes y aún así ejecuta la autocomprobación antes de la entrega.
Integración con el equipo de agentes
Las reglas del repositorio, los contratos aceptados, los permisos de roles y el alcance del usuario tienen prioridad sobre esta guía y sus referencias. DEV usa la pasada de guarda en sus propios cambios; CR usa el modo de revisión de solo lectura y no edita la implementación. Trata los límites numéricos, las prohibiciones de nombres, las formas de los argumentos y las reglas de abstracción como señales para investigar, no como ediciones o bloqueos automáticos. Un hallazgo debe explicar un costo concreto de corrección o mantenimiento en contexto; no dividas código cohesivo, rompas interfaces ni agregues comentarios de excepción solo para cumplir con un conteo. Revisa el código modificado y sus llamantes directamente afectados, no deuda no relacionada.
Toda la orientación y las listas de verificación utilizadas por este paquete son locales. Los nombres de publicaciones externas son solo atribución; usa la evidencia del repositorio y las referencias incluidas en lugar de navegar. Si esta tarea está fuera del alcance de la habilidad, sigue el proceso normal del repositorio; no se requiere ninguna habilidad hermana.
Compatibilidad
Esta es una habilidad de instrucción portátil. No requiere servidor MCP, acceso a red, clave API, comando de shell, ejecutable local ni script incluido. Se puede usar en cualquier runtime que admita SKILL.md más archivos de referencias/ vinculados directamente; agents/openai.yaml son metadatos de visualización ligeros.
Esta habilidad no reemplaza linters de proyecto, formateadores, verificadores de tipos o ejecutores de pruebas. Usa las herramientas propias del proyecto para la verificación mecánica; usa esta habilidad para la capa de juicio en torno a la calidad y revisión del código.
Cómo usar esta habilidad
Esta habilidad tiene tres modos: elige según la solicitud del usuario.
Modo guarda (recomendado): después de que el código haya sido generado, editado, refactorizado o corregido, verifica el diff o los archivos objetivo contra los Imperativos de aplicación permanente a continuación. Corrige las infracciones antes de presentar, confirmar o fusionar el trabajo.
Modo en vivo (explícito): cuando el usuario invoca esta habilidad antes de una edición de código arriesgada, aplica los mismos imperativos mientras escribes, luego ejecuta la lista de verificación Autocomprobación antes de la entrega. Si violas alguna regla, corrígela antes de mostrársela al usuario.
Modo de revisión (activado cuando el usuario te pide revisar, auditar, criticar o calificar código): recorre references/review-checklist.md con los archivos objetivo y produce un informe de hallazgos estructurado. No edites código en modo de revisión a menos que se te solicite.
En los tres modos, los cuerpos de las reglas se encuentran en references/. Lee el archivo de referencia relevante cuando:
- Encuentras una regla que no recuerdas completamente su razonamiento.
- El usuario se opone a una regla y necesitas la cita de la fuente.
- Estás en modo de revisión y necesitas la lista de verificación completa.
- El código bajo revisión toca un principio específico (por ejemplo, subclase → references/solid.md; deduplicación → references/dry-kiss-yagni.md).
Los archivos de referencia son:
- references/naming-and-functions.md — nombres, tamaño de funciones, parámetros, separación comando/consulta.
- references/comments-and-formatting.md — cuándo comentar, cuándo eliminar, coincidir con el estilo vecino.
- references/solid.md — SRP, OCP, LSP, ISP, DIP con las redacciones modernas y olores de detección.
- references/dry-kiss-yagni.md — duplicación de conocimiento vs texto, la regla de re-inline de Sandi Metz, complejidad de McCabe, categorías de costos de YAGNI de Fowler.
- references/ai-failure-modes.md — las 14 formas sistemáticas en que los LLMs producen mal código. Lee este primero si eres un agente de IA leyendo esta habilidad. Es el archivo de mayor apalancamiento en la habilidad.
- references/review-checklist.md — recorrido estructurado para el modo de revisión.
- references/sources.md — bibliografía central para URLs de fuentes. Léelo solo cuando necesites verificar o citar una fuente externa.
Ejemplos
- Un agente de codificación implementa un endpoint: usa el modo guarda en el diff antes de que el trabajo sea presentado o confirmado.
- El usuario pregunta "revisa este PR" o "¿debería fusionar esto?": usa el modo de revisión y reporta hallazgos desde references/review-checklist.md; no edites a menos que se te solicite.
- El usuario pregunta "implementa este endpoint usando clean-code-guard": usa el modo en vivo mientras escribes, luego ejecuta la autocomprobación antes de la entrega.
- El usuario pregunta "refactoriza esta función, mismo comportamiento": preserva el comportamiento observable exactamente y trata cualquier corrección de errores como un cambio separado.
Criterios de éxito
Esta habilidad funciona cuando las tareas de escritura de código evitan los modos de fallo enumerados, las tareas de revisión de código producen hallazgos priorizados con evidencia concreta, y las refactorizaciones preservan el comportamiento a menos que el usuario solicite explícitamente un cambio de comportamiento. Debe permanecer en silencio para tareas conceptuales, de CI, flujo de trabajo de git, prosa, análisis de datos y ejecución de pruebas cubiertas por las exclusiones del frontmatter.
Por qué existe esta habilidad
El código generado por LLM tiene modos de fallo sistemáticos y medibles que las instrucciones genéricas de "sigue el código limpio" no detectan. Ejemplos respaldados por investigación publicada:
- La duplicación de código creció 8 veces en bases de código rastreadas entre 2021 y 2024 (informe GitClear 2025).
- La tasa de alucinación de paquetes promedia el 19.6% en 16 modelos (Spracklen et al., USENIX Security '25).
- Los LLMs a menudo envuelven operaciones arriesgadas en manejadores de captura amplios que tragan errores (Karpathy).
- Los agentes de IA "declaran éxito a pesar de fallar pruebas" devolviendo valores de fixture codificados (Fowler, Patterns for Reducing Friction).
- El tamaño de las funciones creció de 142 a 267 LoC, la complejidad ciclomática de 4.2 a 8.1 en commits asistidos por IA (GitClear).
Los principios clásicos (Código Limpio, SOLID, DRY/KISS/YAGNI) siguen siendo la base — pero esta habilidad agrega la capa específica de IA que la mayoría de los paquetes de reglas pasan por alto.
Imperativos de aplicación permanente
Estas son las reglas a seguir en cada cambio de código. Son imperativas, no sugerencias.
Funciones y nombres
- Los nombres revelan la intención. Nunca uses
data,data2,result,result_final,item,temp,value,obj,info,helper,manager,utils, ohandle_*/process_*/do_*sin un calificador. Un nombre debe responder por qué existe y qué hace. (Clean Code Ch. 2) - Las funciones se mantienen pequeñas. Apunta a ≤20 líneas, un nivel de abstracción, una cosa. Si puedes extraer una función con un nombre que no reformula el cuerpo, el padre estaba haciendo más de una cosa. (Clean Code Ch. 3)
- Cuatro argumentos es el límite máximo. En cinco, detente e introduce un objeto de solicitud/configuración (record, struct, DTO o equivalente). Nunca uses banderas booleanas como argumentos — divide en dos funciones en su lugar.
- Sin argumentos de salida. Una función o devuelve un valor (consulta) o tiene un efecto secundario (comando). Nunca ambas. Los nombres de comandos usan verbos; los nombres de consultas usan sustantivos o nombres estilo getter. (CQS)
Comentarios y estructura
- Los comentarios explican por qué, nunca qué. Elimina cualquier comentario que parafrasee la línea debajo de él. Elimina comentarios de andamio de pasos numerados. Elimina código comentado — el control de versiones existe. (Clean Code Ch. 4)
- Coincide con el estilo existente del archivo. Lee el archivo que estás editando y al menos uno vecino antes de escribir. Refleja las mayúsculas, el orden de importaciones, el manejo de errores, el registro y las elecciones de cliente HTTP/BD. No introduzcas un segundo patrón.
SOLID
- Un actor por módulo. Una clase debe ser responsable ante un grupo de interesados (Contabilidad, Autenticación, Informes). Si dos subsistemas no relacionados acceden a la misma clase, divídela. (SRP, Uncle Bob 2014)
- Extensión mediante código nuevo, no ediciones. Si agregar una nueva variante requiere otra rama de etiqueta de tipo en una función existente, refactoriza primero a un registro, estrategia o envío polimórfico. (OCP)
- Ninguna subclase rechaza el contrato de su padre. Nunca sobrescribas un método para señalar "no implementado" o "operación no soportada". Nunca fortalezcas precondiciones o debilites postcondiciones en una sobrescritura. Si necesitas hacer eso, la herencia está mal. (LSP)
- Las abstracciones viven con el cliente, no con la implementación. Cuando introduzcas una interfaz, protocolo o contrato abstracto, colócalo en el paquete que lo consume, no junto a la clase concreta. (DIP)
DRY, KISS, YAGNI
- Elimina el conocimiento duplicado, no el texto duplicado. Dos funciones que se parecen pero codifican reglas diferentes no son una violación de DRY. Una regla expresada en código + docs + esquema sí lo es. (Programador Pragmático, "DRY")
- La abstracción incorrecta es peor que la duplicación. Si una abstracción ha acumulado ramas para cada caso especial del llamante, vuelve a inlinearla en los llamantes, luego elimina las ramas muertas antes de re-abstraer. (Sandi Metz, "The Wrong Abstraction")
- Techo de complejidad: ciclomática ≤10, profundidad de anidamiento ≤5. Refactoriza antes de exceder. (McCabe 1976)
- Sin nada especulativo. Sin parámetro opcional, bandera de configuración, variable de entorno, toggle de funcionalidad, interfaz, fábrica o clase base sin un llamante presente. Si te encuentras agregando
enable_*,use_*_v2, o*_mode, elimínalo y envía el comportamiento concreto. (Fowler, "Yagni")
Guardarraíles específicos de IA — la sección de mayor apalancamiento
- Nunca tragues errores con manejo genérico de captura. Captura solo el tipo de error específico del que puedas recuperarte. Si no puedes recuperarte, deja que el error se propague. Devolver null/none/éxito vacío desde un manejador de captura está prohibido a menos que el contrato de la función documente ese comportamiento. (Karpathy)
- Protege el límite; confía en el contrato. En un límite de confianza — entrada externa, payloads de solicitud/API, datos deserializados o entre procesos, cualquier cosa de una fuente no confiable — valida, incluso cuando la ruta feliz parezca bien. Dentro del límite, no agregues comprobaciones nulas o comprobaciones de tipo en tiempo de ejecución para valores cuyo tipo declarado o contrato del llamante ya excluye ese caso. La prueba para una guarda no es "¿podría esto ser teóricamente incorrecto" sino "¿pueden los datos no confiables llegar aquí?". (arXiv 2409.19182)
- Verifica cada importación y llamada externa. Antes de llamar a un método en una biblioteca, confirma que existe en la versión instalada (lee el paquete, verifica el archivo de bloqueo o importa e inspecciona). No generes código basado en cómo la API "debería" verse. (USENIX Security '25)
- Sin retornos de "éxito" codificados ni fixtures simulados en código de producción. Nunca devuelvas
{"status": "ok", ...}o datos enlatados de una función cuya especificación dice que hace trabajo real. Si no puedes implementar, falla explícitamente con el mecanismo de no implementado u operación no soportada del lenguaje y dilo. Nunca deshabilites, saltes o debilites una prueba para hacerla pasar. (Fowler, Claude Code issue #6984) - Re-deriva, no copies de similar. Cuando te sientas tentado a copiar una función y modificarla, detente. Re-deriva de la especificación. Los errores de off-by-one y semántica nula incorrecta casi siempre entran mediante copia-de-similar. (arXiv 2411.01414)
- Enumera los casos límite antes de escribirlos. Para cualquier rango, off-by-one, nulo/vacío/uno/muchos, par/impar, o límite unicode/byte, escribe la lista de casos en un comentario primero. Cubre cada caso en el código antes de seguir adelante.
- Elimina código muerto antes de la entrega. Ejecuta un linter o un pase de grep para importaciones no utilizadas, símbolos no utilizados, ramas inalcanzables y exportaciones "por si acaso". Elimínalos. Una función que nadie llama hoy no merece vivir para "algún día".
- Lee antes de escribir. Antes de escribir en un repositorio desconocido, lee el archivo que editarás, un vecino y cualquier archivo de reglas del proyecto (CLAUDE.md, AGENTS.md, sección de "convenciones" del README). Usa los helpers, tipos de error y registro existentes del proyecto.
- Sin nueva dependencia para lo que cubren unas pocas líneas. Antes de agregar un paquete, verifica la biblioteca estándar, las dependencias ya instaladas, y si unas pocas líneas de código local hacen el trabajo. Una nueva dependencia es mantenimiento permanente y superficie de cadena de suministro; agrega una solo cuando sea dueña de complejidad real que no deberías reimplementar (criptografía, análisis, zonas horarias — ilustrativo, no exhaustivo), nunca para ahorrar diez líneas. Ver references/dry-kiss-yagni.md.
El piso — nunca recortes estos por simplicidad
La regla 16 confía en el contrato dentro del límite; los elementos a continuación se mantienen incluso mientras recortas especulación (14), guardas defensivas (16) y código muerto (21). Eliminar uno de estos es un cambio de comportamiento, no una limpieza — mantenlo, o márcalo y pregunta.
- Validación y sanitización en cada límite de confianza — entrada externa, payloads de solicitud/API, datos deserializados o entre procesos.
- Manejo de errores que previene la pérdida de datos.
- Medidas de seguridad — autorización, escape de salida, consultas parametrizadas, manejo de secretos.
- Comportamiento que el usuario solicitó explícitamente. Mencionado casualmente ≠ solicitado, pero no elimines lo que se pidió.
Disciplina de refactorización
- Preserva el comportamiento observable al refactorizar. Cuando el usuario te pida limpiar, simplificar o refactorizar código existente, no cambies el contrato — mismas entradas producen mismas salidas, mismas excepciones lanzadas, mismos efectos secundarios, mismas garantías de orden. Si detectas un error mientras refactorizas, márcalo por separado y pregunta antes de cambiarlo. La refactorización se define como "un cambio realizado en la estructura interna del software para hacerlo más fácil de entender y más barato de modificar sin cambiar su comportamiento observable" (Fowler, Refactoring). Las correcciones de errores y las refactorizaciones son dos operaciones — nunca las combines en un solo cambio.
Autocomprobación antes de la entrega
Antes de mostrar el trabajo al usuario, confirma que:
- No hay nombres de propósito general sin calificar (regla 1).
- Ninguna función excede 20 líneas o un nivel de abstracción (regla 2).
- Ninguna función tiene más de 4 argumentos (regla 3).
- Ninguna función mezcla consulta y comando (regla 4).
- Ningún comentario parafrasea el código o está comentado sin usar (regla 5).
- El estilo coincide con el archivo existente (regla 6).
- Ninguna clase sirve a múltiples actores (regla 7).
- No se agregaron ramas de tipo-etiqueta para nuevas variantes sin refactorización (regla 8).
- Ninguna subclase rechaza el contrato del padre (regla 9).
- Las abstracciones están en el paquete del cliente (regla 10).
- No hay duplicación de conocimiento (regla 11) y ninguna abstracción incorrecta (regla 12).
- Complejidad ciclomática ≤10, profundidad de anidamiento ≤5 (regla 13).
- Sin especulación: sin parámetros opcionales, banderas, toggles, interfaces o fábricas sin uso presente (regla 14).
- Sin captura genérica de errores (regla 15).
- Validación solo en límites de confianza (regla 16).
- Todas las importaciones y llamadas externas verificadas (regla 17).
- Sin valores codificados de éxito o datos enlatados (regla 18).
- Sin copia-de-similar (regla 19).
- Los casos límite están enumerados y cubiertos (regla 20).
- El código muerto se ha eliminado (regla 21).
- Se ha leído el código existente antes de escribir (regla 22).
- Sin nuevas dependencias innecesarias (regla 23).
- Los elementos del piso se mantienen: validación en límites de confianza, prevención de pérdida de datos, medidas de seguridad, comportamiento solicitado.
- La refactorización preserva el comportamiento observable (regla 24).
Si falta algún elemento, corrígelo antes de presentar.