Buenas prácticas
Cómo escribir pautas de revisión
Las instrucciones de revisión y AGENTS.md funcionan mejor como reglas breves y específicas que un compañero nuevo podría seguir. Para elegir entre ellos, consulta Dónde va cada regla.
Empieza por revisiones reales
Deja que HeyDeer revise algunos pull requests antes de escribir nada. Añade una regla cuando se repita un fallo o un comentario no deseado, unas pocas reglas cada vez, y lee las siguientes revisiones para ver el efecto.
Escribe reglas breves y específicas
- Agrupa las reglas en unos pocos encabezados, como Prioridades, Dejar tal cual y Convenciones.
- Escribe una regla por viñeta y nombra las rutas, funciones y bibliotecas a las que se refiere.
- Añade el motivo cuando no sea obvio.
- Mantén las exclusiones concretas: “No comentes los archivos de scripts/one-off/”, no “No comentes los scripts”, que también oculta problemas reales.
- Muestra unas pocas líneas de código incorrecto y correcto de tu código base.
- Mantente muy por debajo del límite de 12.000 caracteres. Cuando las instrucciones crezcan, mueve las convenciones a AGENTS.md y los requisitos estrictos a comprobaciones del repositorio.
Qué no incluir
| No incluyas | Por qué | En su lugar |
|---|---|---|
| Reglas de formato, como la sangría o el orden de los imports | Un formateador o un linter las aplica con exactitud. | Ejecuta esas herramientas en la CI. |
| “Sé más exhaustivo”, “No se te escape nada” | No le dan a HeyDeer nada concreto sobre lo que actuar. | Nombra los riesgos que importan, o usa la profundidad Profundo o un Alcance de los comentarios más amplio. |
| Asignar un personaje, como “Eres un ingeniero de seguridad sénior” | Un rol no dice qué buscar. | Escribe las reglas que aplicaría esa persona. |
| “Bloquea el merge si…”, “Aprueba los PR pequeños” | Las instrucciones dan forma a la revisión, no a lo que HeyDeer hace en GitHub. | Usa “Marcar la comprobación como fallida si se detectan problemas” con una regla de rama, y Aprobación automática. |
| “Ejecuta los tests”, “Compila primero el proyecto” | HeyDeer lee código. Nunca ejecuta código, tests ni builds. | Pide lo que HeyDeer puede verificar leyendo. |
| Enlaces, como “Sigue los estándares de nuestra wiki” | HeyDeer no puede abrir enlaces web. | Copia las reglas que importan, guarda el documento en el repositorio o conecta un servidor MCP. |
| “Escribe tus hallazgos en japonés” | El idioma es un ajuste que también cubre los resúmenes y los encabezados. | Configura el Idioma de la revisión. |
Antes y después
Antes:
You are a world-class senior engineer. Be extremely thorough and
never miss a bug. Follow our standards at
https://wiki.example.com/engineering/standards. Use 2-space
indentation. Write all comments in Japanese. Run the tests before
you review, and block the PR if anything is wrong.Después:
## Priorities
- Code under src/payments/ is high risk. Every call to chargeCard()
passes an idempotency key derived from the order ID, so a retried
request cannot charge twice.
- Retries use retry() from src/lib/retry.ts, which adds backoff.
Replace hand-written retry loops with it.
## Leave alone
- Files under scripts/one-off/. They run once by hand and are deleted.
- Formatting. The formatter enforces it in CI.
## Conventions
- Return client errors through AppError with a stable code.
Incorrect:
```ts
return Response.json({ error: err.message }, { status: 500 });
```
Correct:
```ts
throw new AppError('INVOICE_NOT_FOUND', 404);
```La nueva versión convierte el personaje y el enlace a la wiki en reglas específicas. Todo lo demás se traslada a los lugares de la tabla anterior.