Codificação por Voz em VS Code: Dite Comentários e Documentação

O Problema

Desenvolvedores escrevem mais texto que a maioria das pessoas percebe. Além do código em si, há um fluxo constante de escrita não-código que acontece dentro de VS Code: comentários inline, docstrings de função, seções de README, rascunhos de mensagens de commit, descrições de ticket, anotações todo, e notas de decisão arquitetônica.

Esta escrita é frequentemente tratada como secundária — algo a fazer rapidamente ou adiar até mais tarde. O resultado é bases de código com documentação escassa, funções sem explicação do por que existem e decisões arquitetônicas que existem apenas na memória de alguém.

O atrito é real. Depois de gastar energia mental em um algoritmo complexo, a última coisa que a maioria dos desenvolvedores quer fazer é escrever um parágrafo explicando. Digitar se sente como trabalho adicional no topo do trabalho real. Mas documentação escrita imediatamente após implementação — enquanto o contexto está fresco — é dramaticamente mais valiosa que documentação escrita uma semana depois ou nunca.

Como Telvr Funciona com VS Code

Telvr se integra com VS Code e qualquer outro editor de texto através de injeção de posição de cursor no nível do sistema. Nenhuma extensão do VS Code é necessária. Nenhuma chave de API em seu editor. Nenhuma configuração dentro do VS Code em si.

O fluxo de trabalho para documentação de desenvolvimento:

1. Abra VS Code e posicione seu cursor onde você quer que a documentação apareça — acima de uma função, em um bloco de comentário, em um arquivo README ou em um novo documento markdown.
2. Pressione sua tecla de ativação do Telvr.
3. Fale sua documentação, explicação ou descrição de tarefa.
4. Solte a tecla de ativação. A saída formatada aparece no seu cursor em menos de dois segundos.
5. Continue codificando.

Telvr funciona em todos os contextos do VS Code: o editor em si, o terminal integrado (para ideias de comando faladas) e arquivos de visualização prévia markdown. Também funciona em JSON de configurações do VS Code e outros arquivos de configuração onde você possa querer adicionar comentários.

Melhor Modo de Enriquecimento para VS Code: Dev Task

O modo Dev Task é projetado especificamente para documentação de fluxo de trabalho de desenvolvimento. Quando você o ativa e fala sobre um pedaço de código ou uma tarefa, a IA estrutura sua saída em um formato pronto para desenvolvimento com quatro seções:

Contexto: Informações de fundo explicando o que este código faz, por que existe ou qual problema resolve.

Requisitos: O que a implementação precisa satisfazer — restrições, dependências, casos extremos ou regras de negócio.

Notas de Implementação: Detalhes técnicos, abordagem adotada, trade-offs considerados ou ressalvas importantes.

Critérios de Aceita: Como verificar se a implementação está correta — que testes devem passar, que comportamento esperar ou que condições definem sucesso.

Esta estrutura é imediatamente útil para:

• Blocos de documentação em nível de função explicando lógica complexa
• Comentários de cabeçalho em nível de arquivo para módulos não óbvios
• Descrições de tarefas ao planejar trabalho diretamente em arquivos de código
• Registros de decisão arquitetônica (ADRs) rascunhados em markdown

Para comentários inline mais simples — uma explicação rápida de uma regex, uma anotação sobre uma limitação conhecida — o modo Limpo e Corrigido oferece prosa limpa e legível sem a estrutura formal.

Exemplo Antes e Depois

Entrada de fala bruta (modo Dev Task):

"então esta função cuida da limitação de taxa para a API uh ela precisa rastrear pedidos por usuário por minuto e deve usar uma janela deslizante não uma janela fixa porque janelas fixas podem permitir tráfego em rajada no limite um dependendo de Redis para armazenamento de contador e deve retornar 429 com cabeçalho retry-after quando o limite é excedido também devemos garantir que as chaves de limite expirem automaticamente para não enchermos Redis ao longo do tempo"

Após modo Dev Task:

Contexto Cuida de limitação de taxa de API por usuário usando um algoritmo de janela deslizante. Usa Redis para armazenamento de contador distribuído para suportar implantações multi-instância.

Requisitos

• Rastrear pedidos por usuário por minuto usando janela deslizante (não janela fixa)
• Retornar HTTP 429 com cabeçalho Retry-After quando o limite é excedido
• Chaves do Redis devem expirar automaticamente para prevenir crescimento de armazenamento ilimitado

Notas de Implementação

• Janela deslizante escolhida sobre janela fixa para prevenir tráfego em rajada em limites de janela
• Dependência do Redis necessária para estado de limite de taxa distribuído

Critérios de Aceitação

• Limite de taxa é imposto corretamente sob padrões de tráfego sustentado e rajada
• Chaves do Redis expiram conforme esperado (verificar com comandos TTL)
• Respostas 429 incluem um cabeçalho Retry-After válido
• Nenhuma acumulação de chave Redis após períodos de teste estendidos

A versão falada é uma explicação ramificante. A saída Dev Task é uma especificação estruturada que você pode colar diretamente acima da função como um bloco de documentação.

Economias de Tempo

Documentação é cronicamente subpriorizada porque é lenta de escrever relativa ao seu valor percebido no momento. Desenvolvedores que mudam para documentação por voz relatam duas mudanças: eles documentam mais e documentam melhor.

Escrever um bloco de documentação de função completo leva cinco a oito minutos de digitação focada. Falar o mesmo conteúdo leva sessenta a noventa segundos, e o modo Dev Task cuida da formatação. O investimento de tempo reduzido torna documentação viável em vez de onerosa.

Para documentos mais longos — READMEs, registros de decisão de arquitetura, guias de integração — as economias de tempo escalam proporcionalmente. Um README de mil palavras que levaria quarenta e cinco minutos para escrever pode ser ditado em dez a doze minutos e então editado a partir daí.

Há também um argumento de qualidade. Quando documentação é rascunhada imediatamente após escrever o código, enquanto os detalhes de implementação estão frescos, a documentação resultante é mais precisa e mais útil. A velocidade do Telvr torna prático documentar enquanto codifica em vez de como uma tarefa adiada.

Ao longo de uma semana de desenvolvimento típica com trabalho de documentação regular, Telvr pode recuperar duas a três horas — e produzir uma base de código melhor documentada como um efeito colateral.

Começando

1. Baixe Telvr para macOS em telvr.ai.
2. Complete a configuração e configure seu microfone preferido.
3. Defina uma tecla de ativação que funcione em seu fluxo de trabalho VS Code — algo que você possa pressionar sem mover suas mãos longe da fileira de início.
4. Abra VS Code, posicione seu cursor acima de uma função ou em um bloco de documentação e teste sua primeira ditação.
5. Defina Dev Task como seu modo padrão para trabalho de documentação de desenvolvimento.

Um bom primeiro exercício: encontre as três funções mais complexas em seu projeto atual — as que mais se beneficiariam de documentação clara — e dite um bloco Dev Task para cada. O exercício inteiro deve levar menos de dez minutos e produzir documentação que levaria uma hora para escrever.

Telvr inclui uma versão de avaliação gratuita de 14 dias com acesso completo a todos os modos de enriquecimento. Após o teste, o preço é EUR 3 por mês mais a partir de EUR 0,003 por minuto de transcrição.