hypergadam/agent-skills

Revisión de código Go

Objetivo: el cambio debe hacer que el código base sea más saludable. No tiene que ser perfecto. No bloquees un cambio por gusto personal.

Paso 1: Obtener el cambio

• Si el usuario dio un diff, PR o archivos, usa eso.
• En un repositorio git: git diff --stat main...HEAD, luego git diff main...HEAD (prueba con master o origin/main si main no existe). Para trabajo sin confirmar: git diff y git diff --staged.
• Si el propósito del cambio no está claro, pregunta en una línea corta.

Paso 2: Leer el contexto

• Abre el archivo completo alrededor de cada función modificada, no solo las líneas del diff.
• Encuentra los llamadores de las funciones exportadas modificadas: grep -rn "FuncName(" --include=*.go
• Revisa la versión de Go en go.mod. Algunos consejos dependen de ella (las variables de bucle son por iteración desde Go 1.22).

Paso 3: Ejecutar las herramientas (si puedes ejecutar comandos)

go build ./...
go vet ./...
go test -race ./...              # solo los paquetes cambiados si el repositorio es lento
golangci-lint run ./...          # solo si está instalado o el repositorio tiene una configuración

Informa fallos reales. Para el formato, di "ejecuta gofmt" una vez; no enumeres cada línea. Si no puedes ejecutar comandos, dilo en una línea.

Paso 4: Revisar en este orden

Primero lo grande. Si el diseño está mal, dilo primero y omite los detalles menores.

1. Diseño – ¿Pertenece este cambio aquí (este paquete, este servicio)? ¿Encaja con el resto del sistema? ¿Es el momento adecuado?
2. Funcionalidad – ¿Hace lo que el autor quería? ¿Es eso bueno para las personas que lo usan (usuarios finales y futuros desarrolladores)? Piensa en casos extremos y concurrencia.
3. Complejidad – ¿Puede un lector entenderlo rápidamente? Cuidado con la sobreingeniería: código construido para un futuro imaginado en lugar del problema actual.
4. Pruebas – ¿Hay pruebas en el mismo cambio? ¿Fallarían si el código se rompiera? ¿Son simples?
5. Nombres – Claros, no demasiado largos, estilo Go.
6. Comentarios – Explica por qué, no qué. Comentarios obsoletos y TODOs terminados eliminados.
7. Estilo – gofmt, guía de estilo. Preferencia personal = solo Nit.
8. Consistencia – La guía de estilo gana sobre el código circundante. Si la guía no dice nada, sigue el código circundante.
9. Documentación – README, godoc, variables de entorno/config, migraciones actualizados si el comportamiento cambió.
10. Cada línea – Lee todo el código escrito por humanos. El código generado (*.pb.go, mocks, salida de sqlc) se puede revisar por encima.
11. Salud del código – ¿El sistema completo mejora o empeora con este cambio?
12. Cosas buenas – Menciona cosas buenas reales que veas.

Para verificaciones específicas de Go en cada área, lee references/go-checklist.md. Revisa siempre sus secciones de Errores, Concurrencia y Recursos; la mayoría de los bugs de Go están allí.

Etiquetas de severidad

• Bloqueante – error, condición de carrera, fuga de goroutine, problema de seguridad, prueba rota, diseño incorrecto. Debe arreglarse antes de fusionar.
• Debe arreglarse – problema real, no urgente. El autor puede argumentar.
• Nit – mejora opcional pequeña. Siempre comienza el comentario con "Nit:".
• Pregunta – algo que no entiendes. Si no puedes entenderlo, otros tampoco; pide código más claro.

No inventes problemas. Un buen cambio recibe una revisión corta. Si no estás seguro de que algo sea un error, usa Pregunta, no Bloqueante. Si te piden revisar solo algunos archivos o aspectos, di qué partes revisaste.

Formato de salida

## Resumen
1–2 oraciones: qué hace el cambio. Veredicto: Aprobar / Aprobar con comentarios / Necesita cambios.

## Bloqueantes
- `ruta/archivo.go:42` – qué está mal y por qué es importante.
```go
  // arreglo sugerido
```

## Debe arreglarse
## Nits
## Preguntas
## Cosas buenas

## Lo que revisé
Herramientas ejecutadas y resultados, archivos revisados, cualquier cosa omitida.

Omite las secciones vacías. Cada comentario: problema, por qué, arreglo. Sé breve.