Prompts de guía de estilo de Claude Code para revisiones de código consistentes

Por qué las violaciones a la guía de estilo se extienden tan rápido

Las violaciones a la guía de estilo rara vez aparecen como un único gran error. Empiezan como pequeñas decisiones de “casi igual” que parecen inofensivas en un pull request y luego se acumulan hasta que la base de código resulta desigual y más difícil de leer.

La deriva de estilo suele verse así: un archivo usa userID, otro usa userId, un tercero usa uid. Un handler devuelve { error: "..." }, otro lanza, otro registra y devuelve null. Cada cambio es pequeño, pero juntos crean un repositorio donde los patrones dejan de ser predecibles.

La iteración rápida y múltiples colaboradores empeoran la situación. La gente copia lo que ve, sobre todo bajo presión de tiempo. Si el código más reciente en el repo usó un atajo, ese atajo se convierte en la plantilla para el siguiente cambio. Tras unas semanas, el “estilo por defecto” no es tu guía escrita: es lo último que se hizo.

Por eso la meta tiene que ser convenciones consistentes, no preferencias personales. La pregunta no es “¿Me gusta este nombre?” sino “¿Coincide esto con las reglas que acordamos para que la próxima persona pueda seguirlo sin pensar?”

Detectar violaciones temprano significa detener malos patrones antes de que se conviertan en combustible para copiar-pegar. Enfócate en el código nuevo y modificado, corrige la primera aparición de una inconsistencia nueva y bloquea merges que introduzcan deriva. Cuando señales un problema, añade un breve ejemplo preferido que la gente pueda imitar la próxima vez.

Un ejemplo realista: un desarrollador añade un nuevo endpoint de API y registra los cuerpos de las peticiones “solo para depurar”. Si eso llega a main, el siguiente endpoint lo copia y pronto datos sensibles aparecen en los logs. Detectarlo en el primer PR es barato. Detectarlo una vez que se ha propagado es doloroso y arriesgado.

Convierte tu guía de estilo en reglas claras y comprobables

Una guía de estilo funciona en las revisiones si se lee como una lista de verificación, no como un conjunto de preferencias. Reescribe cada pauta como una regla que se pueda comprobar sobre un diff.

Organiza las reglas en cuatro bloques para que sean difíciles de ignorar: nombres, capas, manejo de errores y logging. Para cada bloque, escribe dos cosas: qué debe ser verdadero y qué está prohibido.

Decide la fuerza de cada regla desde el principio:

• Obligatoria: incumplirla bloquea el cambio.
• Recomendada: arréglalo salvo que haya una razón clara para no hacerlo.
• Opcional: agradable de tener, nunca bloqueante.

Fija el alcance para que las revisiones no se conviertan en refactors interminables. Una regla simple funciona bien: “el código nuevo y modificado debe cumplir; el código existente sin tocar no se reescribe salvo que bloquee la corrección”. Si quieres limpieza, asígnale un tiempo limitado como tarea separada.

También define el resultado que quieres de una revisión para que sea fácil actuar: un veredicto pasar/fallar, una lista de violaciones con archivo y referencias de línea, correcciones sugeridas escritas como ediciones concretas y una breve nota de riesgo cuando algo pueda causar bugs o filtraciones.

Ejemplo: si un PR registra tokens de usuario en texto plano, la revisión debería fallar bajo “logging: nunca registrar secretos” y sugerir registrar un request ID en su lugar.

Estructura de prompt que hace cumplir reglas en vez de opiniones

Los prompts de estilo fallan cuando suenan a preferencias. Un buen prompt de revisión se lee como un contrato: no negociables claros, excepciones claramente nombradas y una salida predecible.

Empieza con dos bloques cortos: lo que debe ser cierto y lo que se puede flexibilizar. Luego añade una regla de decisión: “Si no está claro, marcar como Needs Clarification. No adivinar.”

Exige evidencia. Cuando la herramienta marque una violación, requiere que cite el identificador exacto y la ruta del archivo, no una descripción vaga. Esa sola restricción elimina mucha ida y vuelta.

Mantén el alcance estrecho: comenta solo las líneas modificadas y los caminos de código directamente afectados. Si permites refactors no relacionados, la aplicación de estilo se convierte en “reescribir el archivo” y la gente deja de confiar en el feedback.

Aquí tienes una estructura que puedes reutilizar:

Role: strict style guide reviewer.
Input: diff (or files changed) + style guide rules.
Non-negotiables: [list].
Allowed exceptions: [list].
Scope: ONLY comment on changed lines and directly impacted code paths. No unrelated refactors.
Evidence: Every finding MUST include (a) file path, (b) exact identifier(s), (c) short quote.
Output: structured compliance report with pass/fail per category + minimal fixes.

Requiere que el informe mantenga las mismas secciones cada vez, aunque algunas digan “No issues found”: Naming, Layering, Error handling, Logging.

Si dice “service layer leaking DB details”, debe citar algo como internal/orders/service/order_service.go y la llamada exacta (por ejemplo db.QueryContext) para que puedas arreglar la filtración sin debatir lo que quiso decir.

Paso a paso: construye un flujo de trabajo con prompts para verificación de estilo

Una guía de estilo se afianza cuando el proceso es repetible. La meta es hacer que el modelo verifique reglas, no que discuta gustos, y hacerlo de la misma manera cada vez.

Usa un flujo de trabajo simple de dos pasadas:

1. Pega tus estándares como una lista compacta y numerada (10–25 líneas). Mantén cada regla comprobable.
2. Añade contexto para el cambio: el diff, los archivos tocados y una frase sobre la intención.
3. Pide primero un informe de violaciones. Requiere archivo y referencias de línea, una razón corta y el número exacto de la regla.
4. Solo después del informe, pide el parche mínimo posible para alcanzar el cumplimiento.
5. Vuelve a ejecutar el mismo prompt en el código actualizado para confirmar que no queda nada.

Ejemplo: un PR añade un endpoint nuevo. La pasada 1 marca que el handler habla directamente con PostgreSQL (layering), usa nombres mixtos en structs de petición (naming) y registra emails completos (logging). La pasada 2 hace cambios mínimos: mover la llamada a la DB a un service o repository, renombrar el struct y enmascarar el email en los logs. No cambia nada más.

Convenciones de nombres: prompts que detectan las cosas pequeñas

Los problemas de nombres parecen menores, pero generan costo real: la gente malinterpreta intención, la búsqueda se complica y los nombres “casi iguales” se multiplican.

Indica las reglas de nombres que el revisor debe aplicar en todo el cambio: nombres de archivos, tipos exportados, funciones, variables, constantes y tests. Sé explícito sobre el estilo de mayúsculas (camelCase, PascalCase, snake_case) y elige una regla para acrónimos (por ejemplo APIClient vs ApiClient). Luego exígelo en todas partes.

También estandariza el vocabulario compartido: tipos de error, campos de logs y claves de configuración. Si los logs usan request_id, no permitas reqId en un archivo y requestId en otro.

Una instrucción práctica para el revisor:

Check every new or renamed identifier. Enforce casing + acronym rules.
Flag vague names (data, info, handler), near-duplicates (userId vs userID), and names that contradict behavior.
Prefer domain language: business terms over generic tech words.

Pide un informe corto: los tres nombres más confusos, cualquier casi-duplicado y cuál conservar, más cualquier nombre de log/config/error que no coincida con el estándar.

Reglas de capas: mantener responsabilidades separadas

Las reglas de capas funcionan mejor en lenguaje llano: los handlers hablan HTTP, los services contienen reglas de negocio y los repositories hablan con la base de datos.

Fija la dirección de dependencias. Los handlers pueden llamar a services. Los services pueden llamar a repositories. Los repositories no deberían llamar a services ni handlers. Los handlers no deben importar código de base de datos, helpers SQL o modelos del ORM. Si usas paquetes compartidos (config, time, IDs), mantenlos libres de lógica de aplicación.

Asigna trabajo transversal a una casa clara. La validación suele pertenecer al límite para la forma de la petición y al service para reglas de negocio. La autorización a menudo comienza en el handler (identidad, scopes), pero el service debe aplicar la decisión final. El mapeo pertenece a los bordes de las capas: el handler mapea HTTP a tipos de dominio, el repository mapea filas de BD a tipos de dominio.

Incluye esto en un prompt para mantener las revisiones concretas:

Check layering: handler -> service -> repository only.
Report any leaks:
- DB types/queries in handlers or services
- HTTP request/response types inside services or repositories
- repository returning DB models instead of domain objects
- auth/validation mixed into repository
For each leak, propose the smallest fix: move function, add interface, or rename package.

Haz el informe explícito: nombra el archivo, la capa a la que pertenece, la importación o llamada que rompe la regla y el cambio mínimo que evita que el patrón se propague.

Convenciones de manejo de errores: consistencia bajo presión

La mayoría de los debates sobre estilo se calientan cuando algo falla en producción. Una política clara de manejo de errores mantiene las correcciones en calma porque todo el mundo sabe qué significa “bueno”.

Anota la filosofía y hazla cumplir. Por ejemplo: “Envuelve errores para añadir contexto; crea un error nuevo solo cuando cambias el significado o mapeas a un mensaje de usuario. Devuelve errores crudos solo en el boundary del sistema.” Esa frase evita patrones aleatorios que se propaguen.

Separa el texto visible para el usuario del detalle interno. Los mensajes de usuario deben ser cortos y seguros. Los errores internos pueden incluir el nombre de la operación y identificadores clave, pero no secretos.

En las revisiones, revisa algunos fallos recurrentes: errores tragados (registrados pero no devueltos), retornos ambiguos (valor nil con error nil tras una falla) y mensajes al usuario que filtran trazas de pila, texto de consultas, tokens o datos personales. Si soportas reintentos o timeouts, exige que sean explícitos.

Ejemplo: una llamada de checkout se agota. El usuario ve “El servicio de pago está tardando demasiado”. Internamente, envuelve el timeout e incluye op=checkout.charge y el ID del pedido para que sea buscable y accionable.

Convenciones de logging: legible, searchable y seguro

Los logs solo ayudan cuando todos los escriben igual. Si cada desarrollador escoge su propio wording, nivel y campos, buscar se convierte en adivinar.

Haz los niveles de log no negociables: debug para detalle de desarrollo, info para hitos normales, warn para situaciones inesperadas pero manejadas y error cuando la acción visible por el usuario falla o necesita atención. Mantén “fatal” o “panic” raros y ligados a una política clara de crash.

Los logs estructurados importan más que frases perfectas. Exige nombres de claves estables para que dashboards y alertas no se rompan. Decide un pequeño conjunto central (por ejemplo event, component, action, status, duration_ms) y manténlo consistente.

Trata los datos sensibles como un alto total. Sé explícito sobre lo que NUNCA debe registrarse: contraseñas, tokens de autenticación, tarjetas completas, secretos y datos personales en bruto. Señala cosas que parecen inocuas pero no lo son, como enlaces de restablecimiento de contraseña, IDs de sesión y cuerpos completos de petición.

Los IDs de correlación hacen posible la depuración a través de capas. Exige un request_id en cada línea de log dentro de una petición. Si registras user_id, define cuándo está permitido y cómo representar usuarios faltantes o anónimos.

Un bloque de prompt reutilizable:

Review the changes for logging conventions:
- Check level usage (debug/info/warn/error). Flag any level that does not match impact.
- Verify structured fields: require stable keys and avoid free-form context in the message.
- Confirm correlation identifiers: request_id on all request-bound logs; user_id only when allowed.
- Flag any sensitive data risk (tokens, secrets, personal data, request/response bodies).
- Identify noisy logs (in loops, per-item logs, repeated success messages) and missing context.
Return: (1) violations with file/line, (2) suggested rewrite examples, (3) what to add or remove.

Antes de mergear, haz un “safety pass” rápido: cualquier log nuevo sin request_id para trabajo por petición, cualquier clave nueva que cambie nombres existentes (userId vs user_id), cualquier error log sin indicar qué falló (operación, recurso, estado), logs de alto volumen que se disparen en cada petición y cualquier posibilidad de que secretos o datos personales aparezcan en campos o mensajes.

Cómo atrapar violaciones antes de que se propaguen

Trata la deriva de estilo como una ruptura de build, no como una sugerencia. Añade una puerta estricta que se ejecute antes del merge y devuelva un claro pasar o fallar. Si una regla obligatoria se incumple (nombres, límites de capa, seguridad de logging, manejo de errores), falla y apunta a archivos y líneas exactas.

Mantén la puerta corta. Un truco práctico es exigir un checklist SÍ/NO por regla y negar la aprobación si algún ítem es NO.

Una lista de verificación del tamaño de un PR que captura la mayoría de problemas:

• Naming: coincide con el patrón aprobado para archivos, tipos y funciones
• Layering: no hay llamadas directas que salten capas (por ejemplo handlers llamando a la DB)
• Errors: se retornan con contexto, nada ignorado silenciosamente
• Logging: campos consistentes, sin secretos y nivel acorde al impacto
• Tests/docs: actualizados cuando cambia comportamiento o APIs públicas

Cuando la herramienta sugiere arreglos, exige un pequeño snippet compatible para cada regla que toque. Eso evita feedback vago como “renombra para mayor claridad”.

Errores comunes al usar prompts para hacer cumplir estilo

La forma más rápida de que una guía de estilo fracase es dejar margen para interpretación. Si dos revisores leen la misma regla y llegan a conclusiones distintas, la herramienta acabará imponiendo gustos en lugar de estándares.

Naming es un ejemplo común. “Usa nombres claros” no es comprobable. Afínalo a algo verificable: “las funciones son verbos (por ejemplo, createInvoice), los booleanos empiezan con is/has/can, los tipos exportados son PascalCase”.

Otra trampa es pedirlo todo a la vez. Cuando un prompt intenta cubrir nombres, capas, errores, logging, tests y rendimiento, el feedback se vuelve superficial. Divide las revisiones en pasadas enfocadas cuando necesites profundidad o limita la puerta a reglas obligatorias.

Los problemas que más causan deriva en la aplicación:

• Reglas vagas: reemplaza “limpio” y “consistente” con lenguaje medible.
• Mezclar arreglos de estilo con rediseños: no permitas que un prompt de estilo proponga una nueva arquitectura.
• Falta de evidencia citada: exige que cada comentario cite el identificador o fragmento exacto.
• Excepciones silenciosas: si permites una excepción, exige una nota corta explicando por qué y cuándo se debe eliminar.

Si tratas los prompts como tests, obtienes aplicación predecible. Si los tratas como consejo, las violaciones se cuelan y se multiplican.

Lista rápida para ejecutar en cada cambio

Haz una pasada rápida sobre el diff (no todo el repo) y confirma:

• Naming: los identificadores nuevos siguen tu patrón (case, prefijos, sufijos). Un concepto se nombra igual en todos los archivos.
• Layering: las dependencias solo van en la dirección permitida. Capas inferiores nunca importan capas superiores.
• Errors: las fallas se retornan con contexto. Nada queda ignorado en silencio.
• Logging: nivel correcto, campos estables y sin secretos ni datos personales.
• Pass final: el revisor declara exactamente: “no mandatory violations found”, o lista las violaciones que deben corregirse antes del merge.

Mantén un prompt pequeñísimo y pégalo con cada cambio:

Review ONLY the changed code against our rules for naming, layering, errors, and logging.
List mandatory violations first (with file + line if available). Then list optional suggestions.
End with either: “no mandatory violations found” or “mandatory violations found”.

Ejemplo: una nueva función procUsr() en un handler que escribe directamente en PostgreSQL debería fallar por naming y layering aunque la feature funcione. Detectarlo aquí evita que la copia y pega propague el error.

Ejemplo: una revisión realista que arregla problemas temprano

Un compañero añade el endpoint POST /v1/invoices/{id}/send. Toca un handler, un service y almacenamiento.

En la primera pasada quieres un informe, no una reescritura:

Pass 1 (report only)
You are a strict style checker. Read the patch.
Rules: naming must match our guide, handlers call services only, services call storage only, no SQL in handlers,
errors must be wrapped with context, logs must be structured and not leak PII.
Output: a numbered list of violations with file:line, rule name, and one-sentence impact. Do not propose fixes.
If a rule might be intentionally broken, ask one clarification question.

Hallazgos típicos: SendInvoiceNow() vs SendInvoice mismatched naming, el handler llamando db.QueryRow directamente, retornar err crudo sin contexto y logs ruidosos como log.Printf("sending invoice %v", invoice) que vuelcan objetos completos.

La segunda pasada pide cambios mínimos y seguros:

Pass 2 (minimal fix suggestions)
Using the violations list, propose the smallest code edits to comply.
Constraints: keep behavior the same, no refactors beyond what is needed, show suggested function names and where code should move.
For each fix, include 1-2 lines of example code.

Si romper una regla está permitido, dilo desde el principio: “Exceptions are permitted only if you add a short comment explaining why, and you add a follow-up task to remove the exception.”

Tras la corrección, el handler pasa a ser un adaptador delgado, el service se encarga del flujo, storage ejecuta la consulta, los errores pasan a fmt.Errorf("send invoice: %w", err) y los logs quedan en una línea limpia con campos seguros (ID de factura, no la factura completa).

Siguientes pasos: hacerlo rutinario sin ralentizar

Elige un prompt aprobado por el equipo y trátalo como una herramienta compartida. Empieza por lo que más te duele en las revisiones (deriva de nombres, mezcla de capas, errores inconsistentes, logs inseguros). Actualiza el prompt solo cuando veas una violación real en código real.

Mantén un bloque pequeño de reglas al principio del prompt y pégalo en cada revisión sin cambiarlo. Si todos editan las reglas cada vez, no tendrás un estándar. Tendrás un debate.

Una cadencia simple ayuda: una persona recoge las principales faltas de estilo de la semana y añades exactamente una regla más clara o un ejemplo mejor.

Si trabajas en un flujo de construcción guiado por chat como Koder.ai (koder.ai), vale la pena ejecutar las mismas comprobaciones de puerta durante los cambios, no solo al final. Funciones como planificación, snapshots y rollback pueden ayudarte a mantener las correcciones de estilo pequeñas y reversibles antes de exportar el código fuente.