Clean Code Guard

Revisa código escrito por IA contra Clean Code, SOLID y 15 modos de fallo documentados de LLM

Por amElnagdy · amElnagdy/guard-skills

Probado · Funciona ★ 8.4/10

Clean Code Guard — Revisa código escrito por IA contra Clean Code, SOLID y 15 modos de fallo documentados de LLM

Qué hace

Una habilidad de pase de revisión que verifica el código de producción generado o modificado contra Clean Code, SOLID, DRY/KISS/YAGNI y un catálogo de 15 modos de fallo específicos de LLM, como excepciones tragadas, retornos de éxito codificados, APIs alucinadas y errores de copia de similares. Se activa después de que un agente de codificación escribe, edita, refactoriza o corrige código y antes de que el resultado se presente, se confirme o se fusione, y en solicitudes como "review this PR", "is this safe to merge" o "refactor this". Se mantiene al margen de la configuración de CI, el flujo de trabajo de git, la depuración de pruebas, la discusión de arquitectura y la revisión de código de prueba, que cubre la habilidad hermana test-guard.

Informe de la prueba

La API de GitHub estaba limitada por tasa, así que cloné el repositorio superficialmente; SKILL.md se encuentra en skills/clean-code-guard/ con 7 archivos de referencia, y obtuve en bruto tres de ellos (ai-failure-modes.md, solid.md, sources.md) — todos HTTP 200. El frontmatter se analiza con name más una descripción de 938 caracteres (por debajo del límite de 1024); el único archivo no Markdown es un agents/openai.yaml de 4 líneas de metadatos de visualización, y grep no encontró pipe-to-shell, blobs base64, lecturas de secretos o texto de inyección. Para la etapa de salida, escribí un OrderProcessor Python de 72 líneas con defectos plantados, produje una revisión de línea base SIN leer el cuerpo de la habilidad, luego volví a revisar siguiendo SKILL.md más review-checklist.md y ai-failure-modes.md: la línea base dio 14 puntos no clasificados con la excepción de pago tragada que bloqueaba la fusión enterrada en la posición 4 entre una importación no utilizada y un detalle "+=", mientras que la ejecución de la habilidad forzó un pre-vuelo de refactorización vs corrección, niveles de severidad y una línea de Cobertura por sección, y detectó tres cosas que la línea base omitió — el estado de respuesta no verificado (un 200 con un cuerpo rechazado aún persiste la orden), datos de tarjeta en bruto POSTeados a una payment_url que por defecto es None enmarcado como un hallazgo de límite de confianza, y dinero flotante correctamente degradado a "cambio de comportamiento, confirmar con el autor" en lugar de listado como una corrección. Los costos son reales: unas 470 líneas de lectura de referencia, y el límite de 3 nits de la lista de verificación eliminó dos elementos legítimos de la línea base. La documentación perdió un punto porque la línea 42 de SKILL.md afirma "14 systematic ways" mientras que la línea 3 de ai-failure-modes.md dice 15 y lista 15, y la cláusula "invoke it on your own initiative the moment you finish writing code" del frontmatter es un riesgo de sobreactivación en los turnos de codificación rutinarios. Frases de activación juzgadas: DEBERÍA activarse — "I just finished implementing the checkout handler, review it before I commit" (sí), "Review this PR, is it safe to merge?" (sí), "Refactor this OrderProcessor class, keep behavior identical" (sí); NO DEBERÍA activarse — "The pytest suite fails on CI with a fixture teardown error, help me debug it" (no, excluido dos veces como ejecución de pruebas y CI), "Should we use event sourcing or CRUD for the orders service?" (no, excluido como discusión de arquitectura pura). 5/5 correcto. Las cuatro URLs de origen citadas que revisé (arXiv 2409.19182, Fowler Yagni, Metz Wrong Abstraction, USENIX Spracklen) devolvieron 200, por lo que las afirmaciones de investigación están respaldadas en lugar de ser decorativas.

Probado el: 2026-07-21 · Claude Code 2.x (agent harness)

Instalación

git clone --depth 1 https://github.com/amElnagdy/guard-skills.git /tmp/clean-code-guard-src
mkdir -p ~/.claude/skills
cp -R /tmp/clean-code-guard-src/skills/clean-code-guard ~/.claude/skills/clean-code-guard
# CLI instead: npx skills add amElnagdy/guard-skills --skill clean-code-guard --global
# (without --global it installs project-local, into ./.claude/skills)
# Whole 5-skill package: npx skills add amElnagdy/guard-skills
# Update later: npx skills update clean-code-guard

Comandos y prompts de ejemplo

  • /clean-code-guardRevisa código escrito por IA contra Clean Code, SOLID y 15 modos de fallo documentados de LLM

Los skills se activan con peticiones en lenguaje natural, sin comandos que memorizar. Tras instalarlo, prompts como estos lo activan (en inglés):

  • Is this code safe to merge
  • Review this PR against Clean Code principles
  • Audit this refactor for SOLID violations