Predefinições de tom para desenvolvedores e clientes para os mesmos commits

Por que pré-definições de tom separadas?

Comecei este projeto porque vi equipes desperdiçarem tempo reescrevendo a mesma entrada de changelog para dois leitores diferentes. Engenheiros precisam ver o que mudou no código, quais arquivos foram alterados e quais APIs internas de quebra foram alteradas. Gestores de produto, pessoal de suporte e utilizadores finais se importam com o que a alteração significa para eles: novos recursos, bugs corrigidos, desempenho melhorado ou limites removidos. Um único tom não pode servir bem a ambos os grupos. Ao criar duas pré-definições distintas que operam na mesma lista de compromissos, mantemos a fonte de verdade inalterada enquanto entregamos mensagens personalizadas. Esta abordagem também permite que o rótulo SemVer permaneça a única fonte de significado contratual, porque o rótulo está anexado ao grupo de compromissos, não à redação.

Predefinição de tom do desenvolvedor: detalhe-primeiro

Detalhe de nível de compromisso

Quando a predefinição de desenvolvedor está ativa, a IA expande cada compromisso em uma frase que inclui o caminho do arquivo, a função ou classe modificada e a natureza da alteração (adição, exclusão, refatoração). Por exemplo, um compromisso que corrige um ponteiro nulo em src/api/user.go se torna: "Corrigido dereferenciamento de ponteiro nulo em GetUserByID quando o ID de entrada é zero, adicionado cláusula de guarda e teste unitário."

Linkando para sistemas de rastreamento

Se a mensagem de compromisso contém um ID de problema (por exemplo, ABC-123), a predefinição o envolve em um link para o rastreador, supondo que a equipe tenha configurado a URL base. Isso permite que os engenheiros acessem diretamente a discussão ou o documento de design sem sair do registro de alterações.

Incluindo contexto técnico

A predefinição adiciona quaisquer avisos relevantes do compilador, alterações na cobertura de testes ou deltas de benchmark de desempenho que apareceram na execução do CI associada ao compromisso. Isso fornece uma verificação rápida de saúde para a área modificada.

Verificações de segurança e conformidade para saída de LLM

Como o texto é gerado por um modelo de linguagem, eu o executo em um filtro de segurança leve que verifica o conteúdo proibido. O filtro referencia a OWASP LLM Top 10 para riscos de injeção de prompt e o NIST AI Risk Management Framework para orientação sobre como gerenciar alucinações e viés. Se um segmento dispara uma regra, ele é marcado para revisão humana antes de ser publicado.

Lista de exemplos para uma versão típica

- Adicionada interface RetryPolicy em src/retry/policy.go para permitir estratégias de retrocesso plugáveis. - Removida estrutura LegacyCache depreciada de src/cache/legacy.go; todos os chamadores migrados para LRUCache. - Corrigida condição de corrida em WorkerPool.Start onde um canal nulo poderia ser fechado duas vezes; adicionado guarda de mutex. - Atualizado módulo Go github.com/stretchr/testify de v1.7.0 para v1.8.2 para pegar patch de segurança para pacote assert. - Adicionados benchmarks para JSONEncoder mostrando redução de 12% no tamanho de alocação para payloads abaixo de 10KB.

Predefinição de tom do cliente: benefício-em-primeiro

Linguagem focada no resultado

Com a predefinição do cliente, a IA reescreve cada confirmação em uma frase que descreve o que o usuário pode fazer agora ou qual problema foi resolvido. Jargão técnico é substituído por termos simples. A mesma correção de ponteiro nulo se torna: "Os usuários não verão mais um erro ao inserir um ID de valor zero no campo de pesquisa de usuário."

Evitando identificadores internos

Hashes de confirmação, nomes de branch e números de problemas internos são omitidos, a menos que sejam parte de uma flag de recurso pública ou de um endpoint de API versionado que os clientes possam referenciar. O objetivo é manter o ruído baixo.

Destacando o impacto no usuário

Se uma confirmação melhora o desempenho, a predefinição traduz o ganho de benchmark em uma declaração visível para o usuário: "Os tempos de carregamento de página agora são até 15% mais rápidos em dispositivos móveis." Se uma confirmação remove um limite, ela é lida: "Agora você pode carregar arquivos de até 100 MB em vez do limite anterior de 25 MB."

Linkando para documentação pública

Quando uma alteração toca um endpoint de API pública ou uma opção de configuração, a predefinição adiciona um link para a seção relevante de documentação, supondo que o site de documentação siga um padrão de URL previsível (por exemplo, https://docs.example.com/api/v2/users).

Lista de exemplos para o mesmo lançamento

- A lógica de retry agora se adapta a problemas temporários de rede, reduzindo uploads com falha em conexões instáveis. - A implementação antiga de cache foi removida; o novo cache usa menos memória e limpa entradas obsoletas automaticamente. - Corrigimos um crash raro que poderia ocorrer quando muitos trabalhadores começavam ao mesmo tempo. - Biblioteca de terceiros atualizada para abordar um aviso de segurança; nenhuma ação é necessária de sua parte. - Respostas JSON agora são mais leves, o que reduz o uso de dados em conexões medidos.

De diff de commit para duas narrativas

Análise e agrupamento

O pipeline começa a executar git log --pretty=format:%H %s %b --since="1 semana atrás" para coletar commits desde a última tag. Cada commit é analisado para o seu tipo de commit convencional (feat, fix, perf, refactor, etc.) e escopo. Commits com o mesmo tipo e implicações de SemVer são agrupados juntos porque compartilharão o mesmo aumento de versão.

Aplicação de prompts específicos de tom

Para cada grupo, eu crio duas prompts: uma ajustada para o preset de desenvolvedor, outra para o preset de cliente. A prompt do desenvolvedor pede uma "descrição detalhada e técnica que inclui nomes de arquivos, símbolos e quaisquer alterações relevantes de teste ou benchmark." A prompt do cliente pede uma "explicação concisa e orientada para benefícios que evita jargão interno e se concentra no que o usuário experimenta." A mesma lista de commits alimenta ambas as prompts, garantindo que os fatos subjacentes permaneçam idênticos.

Revisão com intervenção humana

A saída da IA é enviada para um editor de rascunho onde um mantenedor pode aceitar, editar ou rejeitar cada frase. Eu descobri que a maioria das edições são ajustes menores de redação em vez de alterações factuais, o que mostra que o modelo é bom em permanecer fiel à diff de origem. Após a revisão, o rascunho é renderizado em Markdown e, em seguida, em HTML para publicação.

Tabela: mapeamento de tipos de commit convencionais para frases de tom

Tipo de commit | Exemplo de frase para desenvolvedor | Exemplo de frase para cliente feat | Adicionado método ExportCSV ao ReportService que transmite linhas para reduzir o uso de memória. | Agora você pode baixar relatórios como arquivos CSV diretamente do botão de exportação. fix | Resolvido deadlock em JobQueue.Push quando um trabalho nulo foi enfileirado sob alta carga. | Os trabalhos não mais ficarão presos quando o sistema estiver ocupado. perf | Substituído lookup O(n²) em TagIndex.Find por um mapa de hash, reduzindo a latência de 12 ms para 0,8 ms para 10 k tags. | As buscas de tags agora são consideravelmente mais rápidas, especialmente com bibliotecas grandes. refactor | Extraído interface PasswordValidator de AuthHandler para permitir regras de força plugáveis. | Os requisitos de senha agora podem ser ajustados sem alterar o código de login principal. docs | Atualizado API.md com nova descrição do endpoint PATCH /users/:id e carga útil de exemplo. | O centro de ajuda agora mostra como atualizar parcialmente um perfil de usuário.

Preservar o significado do SemVer em diferentes tons

As regras de incremento de versão permanecem ancoradas nos commits

A etiqueta SemVer é determinada exclusivamente pelos tipos de commits convencionais no grupo: um feat dispara um incremento menor, um fix um patch, e uma alteração de quebra um incremento maior. Como os presets de tom não alteram as mensagens de commit ou seus tipos, o número de versão resultante é idêntico seja qual for a versão do desenvolvedor ou do cliente que se lê.

Consistência de contrato

Trato a etiqueta SemVer como o contrato entre o produtor e o consumidor do software. O registro de alterações é apenas uma expressão legível por humanos desse contrato. Ao manter o contrato intacto, as equipes podem confiar em ferramentas automatizadas (como bots de lançamento ou verificadores de dependências) para interpretar a versão corretamente, enquanto o registro de alterações de dois tons serve aos dois públicos sem criar ambiguidade.

Exemplo de um lançamento principal

Suponha que um commit adiciona BREAKING CHANGE: remove a API legada v1. O preset de desenvolvedor notará as eliminações de arquivos exatas e os passos de migração necessários. O preset de cliente explicará que o ponto de extremidade da API antiga não está mais disponível e apontará os usuários para a documentação do v2. Em ambos os casos, a versão passa de 2.4.1 para 3.0.0, preservando o significado contratual.

O que isto não é

Quero ser claro sobre os limites desta abordagem para que possa ter expectativas realistas.

- Não garante que cada frase gerada seja perfeita em termos de tom; ocasionalmente, frases técnicas podem aparecer no rascunho do cliente ou linguagem vaga de benefícios pode aparecer no rascunho do desenvolvedor. A revisão humana ainda é necessária. - Não é um substituto de 100 % para um escritor técnico dedicado ou um marketer de produtos. A IA acelera a primeira versão, mas a nuances, a voz da marca e as menções legais ainda precisam do toque de uma pessoa. - Não elimina a necessidade de higiene de compromisso claro. Se as mensagens de compromisso forem vagas ou carecerem de estrutura de compromisso convencional, os grupos serão menos precisos e a saída será menos útil. - Não é uma ferramenta mágica que irá satisfazer automaticamente todos os reguladores ou diretrizes de acessibilidade. Os controles de segurança que adicionei são básicos; ainda deve realizar a sua própria revisão de conformidade. - Não promete que o registro de alterações nunca perderá uma alteração. Se um compromisso for omitido do intervalo de log do git (por exemplo, devido a um clone raso ou a um filtro errado), ele não aparecerá em nenhum dos tons.

Referências

- OWASP LLM Top 10 - Quadro de Gestão de Riscos de IA do NIST

Leituras relacionadas

- Registos de alterações agrupados a partir de commits (não git log bruto) — Changelog AI - A matriz de tópicos de micro-SaaS de LX AI