La verdad cruda sobre los documentos escritos a mano: son exactos el día que los escribes y erróneos algún día después, y nadie puede decirte qué día.
La mayoría de los equipos lo resuelve programando revisiones de documentación. Eso no funciona: la revisión ocurre según un calendario y el código cambia según una tubería de despliegue, y los dos calendarios nunca cuadran. El arreglo no es disciplina. Es hacer de la documentación algo que regeneras en lugar de algo que te acuerdas de actualizar.
# artisan
$ php artisan boost:update
AGENTS.md no es prosa mantenida a mano: lo produce Laravel Boost a partir de los paquetes y capacidades realmente instalados. Cuando cambia una dependencia, vuelves a ejecutar el comando en lugar de buscar un párrafo que arreglar. No puede desviarse como se desvía una página de wiki, porque no está describiendo la base de código de memoria: la está leyendo.
ArchTest.php hace el mismo trabajo de otra forma. Un comentario que dice «los jobs deben llevar el sufijo Job» se queda rancio en cuanto alguien deja de leer comentarios. Una aserción arch() que dice lo mismo hace fallar la construcción en cuanto alguien lo incumple. La prueba es la documentación.
Errores que te dicen que hacer despues
Una opinión polémica: un mensaje de error que sólo enuncia el problema ha hecho la mitad de su trabajo. La otra mitad es decirle a quien lo lee qué pasa a continuación.
// api-infrastructure/src/Exceptions/ApiExceptionRenderer.php
if ($exception instanceof ThrottleRequestsException) {
$status = HttpResponse::HTTP_TOO_MANY_REQUESTS;
$message = 'Too many requests. Please try again later.';
} elseif ($exception instanceof ModelNotFoundException) {
$status = HttpResponse::HTTP_NOT_FOUND;
$message = 'The requested resource was not found.';
} elseif ($exception instanceof ValidationException) {
$status = HttpResponse::HTTP_UNPROCESSABLE_ENTITY;
$message = json_encode($exception->errors()) ?: '{}';
}
Cada rama responde a dos preguntas a la vez: qué salió mal y qué le dice el código de estado a quien llama que haga. Un 429 dice «frena y reintenta». Un 404 dice «deja de preguntar, eso no está». Un 422 devuelve los campos exactos que fallaron, así que quien llama no tiene que adivinar cuál era el problema.
// bootstrap/app.php
$exceptions->render(function (ConnectionException $exception) {
return response()->json(
data: ['errors' => [$exception->getMessage()]],
status: HttpResponse::HTTP_GATEWAY_TIMEOUT,
);
});
Un 504 en lugar de un 500 genérico le dice a quien llama algo concreto: esto no fue culpa tuya, el servicio externo iba lento, reintentar es razonable. Un 500 Internal Server Error pelado no le dice nada salvo que abra un ticket. Una respuesta cierra la conversación. La otra deja actuar.