Dev vs tono de cliente para los mismos commits

¿Por qué separar los ajustes de tono?

Empecé este proyecto porque vi que los equipos desperdician tiempo reescribiendo la misma entrada de registro de cambios para dos lectores diferentes. Los ingenieros necesitan ver qué cambió en el código, qué archivos se modificaron y cualquier API interna de ruptura. Los gerentes de producto, el personal de soporte y los usuarios finales se preocupan por lo que el cambio significa para ellos: nuevas características, errores corregidos, rendimiento mejorado o límites eliminados. Un solo tono no puede servir bien a ambos grupos. Al crear dos ajustes preestablecidos distintos que operan en la misma lista de confirmaciones, mantenemos la fuente de verdad sin cambios mientras entregamos mensajes personalizados. Este enfoque también permite que la etiqueta SemVer siga siendo la única fuente de significado contractual, porque la etiqueta está asociada con el grupo de confirmaciones, no con la redacción.

Preconfiguración de tono de desarrollador: detalle primero

Nivel de detalle de confirmación

Cuando la preconfiguración de desarrollador está activa, la IA expande cada confirmación en una oración que incluye la ruta del archivo, la función o clase modificada y la naturaleza del cambio (adición, eliminación, refactorización). Por ejemplo, una confirmación que corrige un puntero nulo en src/api/user.go se convierte en: "Corregido el error de puntero nulo en GetUserByID cuando el ID de entrada es cero, se agregó una cláusula de guardia y una prueba unitaria."

Enlace a sistemas de seguimiento

Si el mensaje de confirmación contiene un ID de problema (por ejemplo, ABC-123), la preconfiguración lo envuelve en un enlace al sistema de seguimiento, asumiendo que el equipo ha configurado la URL base. Esto permite a los ingenieros saltar directamente a la discusión o al documento de diseño sin dejar el registro de cambios.

Inclusión de contexto técnico

La preconfiguración agrega cualquier advertencia de compilador relevante, cambios en la cobertura de pruebas o diferencias en las pruebas de rendimiento que aparecieron en la ejecución de CI asociada con la confirmación. Esto proporciona una verificación rápida de la salud del área modificada.

Comprobaciones de seguridad y cumplimiento para la salida de LLM

Dado que el texto es generado por un modelo de lenguaje, lo ejecuto a través de un filtro de seguridad ligero que comprueba el contenido no permitido. El filtro hace referencia a la lista de los 10 principales de OWASP para riesgos de inyección de prompts y al marco de gestión de riesgos de AI de NIST para la orientación sobre la gestión de alucinaciones y sesgos. Si un segmento activa una regla, se marca para revisión humana antes de publicar.

Ejemplo de lista para una versión típica

- Se agregó la interfaz RetryPolicy en src/retry/policy.go para permitir estrategias de retroceso personalizables. - Se eliminó la estructura LegacyCache obsoleta de src/cache/legacy.go; todos los llamadores migrados a LRUCache. - Se corrigió la condición de carrera en WorkerPool.Start donde un canal nulo podría cerrarse dos veces; se agregó una guardia de mutex. - Se actualizó el módulo de Go github.com/stretchr/testify de v1.7.0 a v1.8.2 para recoger el parche de seguridad para el paquete de aserciones. - Se agregaron benchmarks para JSONEncoder que muestran una reducción del 12% en el tamaño de asignación para cargas útiles inferiores a 10KB.

Preconfiguración de tono del cliente: beneficio primero

Lenguaje enfocado en resultados

Con la preconfiguración del cliente, el AI reescribe cada confirmación en una oración que describe lo que el usuario puede hacer ahora o qué problema se ha resuelto. El jargon técnico se reemplaza con términos sencillos. La misma corrección de puntero nulo se convierte en: "Los usuarios ya no verán un error al ingresar un ID de valor cero en el campo de búsqueda de usuarios."

Evitando identificadores internos

Los hashes de confirmación, los nombres de las ramas y los números de problemas internos se omiten a menos que sean parte de una característica pública o un punto final de API versionado que los clientes puedan referencia. El objetivo es mantener el ruido bajo.

Destacando el impacto en el usuario

Si una confirmación mejora el rendimiento, la preconfiguración traduce la ganancia de benchmark en una declaración visible para el usuario: "Los tiempos de carga de página ahora son hasta un 15% más rápidos en dispositivos móviles." Si una confirmación elimina un límite, se lee: "Ahora puede cargar archivos de hasta 100 MB en lugar del límite anterior de 25 MB."

Enlazando a la documentación pública

Cuando un cambio afecta un punto final de API público o una opción de configuración, la preconfiguración agrega un enlace a la sección de documentación relevante, asumiendo que el sitio de documentación sigue un patrón de URL predecible (por ejemplo, https://docs.example.com/api/v2/usuarios).

Lista de ejemplos para el mismo lanzamiento

- La lógica de reintento ahora se adapta a los glitches de red temporales, reduciendo las cargas fallidas en conexiones inestables. - Se eliminó la implementación de caché antigua; la nueva caché utiliza menos memoria y limpia las entradas obsoletas automáticamente. - Se corrigió un bloqueo raro que podría ocurrir cuando muchos trabajadores comenzaban al mismo tiempo. - Se actualizó la biblioteca de terceros para abordar un aviso de seguridad; no se requiere acción por su parte. - Las respuestas JSON ahora son más ligeras, lo que reduce el uso de datos en conexiones medidas.

Desde el diff de commit a dos narrativas

Análisis y agrupación

La tubería comienza ejecutando git log --pretty=format:%H %s %b --since="1 semana atrás" para recopilar commits desde la última etiqueta. Cada commit se analiza para determinar su tipo de commit convencional (feat, fix, perf, refactor, etc.) y alcance. Los commits con el mismo tipo y implicación de SemVer se agrupan juntos porque compartirán el mismo incremento de versión.

Aplicación de prompts específicos de tono

Para cada grupo, creo dos prompts: uno ajustado para el preset de desarrollador y otro para el preset de cliente. El prompt de desarrollador solicita "una descripción detallada y técnica que incluya nombres de archivos, símbolos y cualquier cambio de prueba o benchmark relevante". El prompt de cliente solicita "una explicación concisa y orientada a beneficios que evite el jargon interno y se centre en lo que el usuario experimenta". La misma lista de commits alimenta ambos prompts, asegurando que los hechos subyacentes sigan siendo idénticos.

Revisión con intervención humana

La salida de la IA aterriza en un editor de borrador donde un mantenedor puede aceptar, editar o rechazar cada oración. He encontrado que la mayoría de las ediciones son ajustes menores de redacción en lugar de cambios de hechos, lo que muestra que el modelo es bueno para mantenerse fiel al diff de origen. Después de la revisión, el borrador se renderiza en Markdown y luego en HTML para su publicación.

Tabla: mapeo de tipos de commit convencionales a frases de tono

Tipo de commit | Ejemplo de frases para desarrolladores | Ejemplo de frases para clientes feat | Se agregó el método ExportCSV a ReportService que transmite filas para reducir el uso de memoria. | Ahora puede descargar informes como archivos CSV directamente desde el botón de exportación. fix | Se resolvió el deadlock en JobQueue.Push cuando un trabajo nulo se agregó bajo alta carga. | Los trabajos ya no se bloquearán cuando el sistema esté ocupado. perf | Se reemplazó la búsqueda O(n²) en TagIndex.Find con un mapa hash, reduciendo la latencia de 12 ms a 0,8 ms para 10 k etiquetas. | Las búsquedas de etiquetas ahora son notablemente más rápidas, especialmente con bibliotecas grandes. refactor | Se extrajo la interfaz PasswordValidator de AuthHandler para permitir reglas de fuerza ajustables. | Los requisitos de contraseña ahora se pueden ajustar sin cambiar el código de inicio de sesión principal. docs | Se actualizó API.md con la nueva descripción del punto final PATCH /users/:id y la carga útil de ejemplo. | El centro de ayuda ahora muestra cómo actualizar parcialmente un perfil de usuario.

Preservando el significado de SemVer en diferentes tonos

Las reglas de incremento de versión permanecen ancladas a los commits

La etiqueta SemVer se determina únicamente por los tipos de commits convencionales en el grupo: un feat desencadena un incremento menor, un fix un parche y un cambio de ruptura un incremento mayor. Como los ajustes de tono no alteran los mensajes de commit ni sus tipos, el número de versión resultante es idéntico ya sea que se lea la versión del desarrollador o la del cliente.

Consistencia del contrato

Trato la etiqueta SemVer como el contrato entre el productor y el consumidor del software. El registro de cambios es simplemente una expresión legible por humanos de ese contrato. Al mantener el contrato intacto, los equipos pueden confiar en herramientas automatizadas (como bots de lanzamiento o verificadores de dependencias) para interpretar la versión correctamente, mientras que el registro de cambios de doble tono sirve a las dos audiencias sin crear ambigüedad.

Ejemplo de un lanzamiento principal

Supongamos que un commit agrega BREAKING CHANGE: eliminar API legacy v1. El ajuste de desarrollador anotará las eliminaciones de archivos exactas y los pasos de migración requeridos. El ajuste de cliente explicará que el punto final de API antiguo ya no está disponible y dirigirá a los usuarios a la documentación de v2. En ambos casos, la versión pasa de 2.4.1 a 3.0.0, preservando el significado contractual.

Qué no es esto

Quiero dejar claro los límites de este enfoque para que puedas establecer expectativas realistas.

- No garantiza que cada oración generada sea perfecta en cuanto al tono; ocasionalmente, puede aparecer una fraseación demasiado técnica en el borrador del cliente o un lenguaje de beneficios vago en el borrador del desarrollador. Todavía se requiere una revisión humana. - No es un reemplazo del 100 % para un escritor técnico dedicado o un especialista en marketing de productos. La IA acelera el primer borrador, pero la nuance, la voz de la marca y los avisos legales aún necesitan el toque de una persona. - No elimina la necesidad de una higiene de compromiso clara. Si los mensajes de compromiso son vagos o carecen de estructura de compromiso convencional, los grupos serán menos precisos y la salida será menos útil. - No es una herramienta mágica que satisfaga automáticamente todas las regulaciones o directrices de accesibilidad. Las comprobaciones de seguridad que agregué son básicas; aún debes realizar tu propia revisión de cumplimiento. - No promete que el registro de cambios nunca omitirá un cambio. Si se omite un compromiso del registro git (por ejemplo, debido a un clon superficial o a un filtro erróneo), no aparecerá en ningún tono.

Referencias

- OWASP LLM Top 10 - Marco de gestión de riesgos de inteligencia artificial de NIST

Lecturas relacionadas

- Registros de cambios agrupados desde los commits (no registros de git sin procesar) — Changelog AI - La matriz de temas de LX AI Micro-SaaS