Como escrever um blog técnico com IA: pesquisa, validação de código e revisão humana

Um artigo técnico contém três blocos de código, mas nenhum foi executado. Os leitores copiam os exemplos, recebem erros e descobrem que o problema não era a redação: fatos e código nunca passaram por um controle.

Um rascunho de IA pode parecer completo enquanto adivinha versões, argumentos e formatos de saída. Um projeto declara "type": "module" no package.json, mas o exemplo usa require diretamente. Outro texto afirma que o GitHub Actions oferece “2.000 minutos por mês” sem explicar que esse número é a franquia de um plano específico para repositórios privados.

Escrever um blog técnico não significa entregar um tema ao modelo e polir a resposta. Primeiro, reúnem-se fontes e evidências executáveis; depois, a IA organiza a explicação; por fim, uma pessoa revisa fatos, código e estilo. O fluxo abaixo atribui um controle e um responsável a cada etapa para manter afirmações corretas, exemplos executáveis e conclusões reproduzíveis.

Pesquise antes de pedir um rascunho à IA

O que precisa ser pesquisado e o que a IA pode redigir?

A primeira decisão separa os fatos que devem vir de fontes externas das partes que o modelo pode organizar.

Há três cenários de pesquisa.

Versões, alterações em campos de API, limites documentados, preços ou cotas e configurações de segurança precisam ser pesquisados antes. Um erro pode quebrar o projeto do leitor ou gerar custos inesperados. A documentação atual do Next.js usa, por exemplo, a chave turbopack, enquanto as versões 13.0.0 a 15.2.x usavam experimental.turbo. Escrever apenas “configure o Turbopack”, sem indicar a versão, pode levar alguém a copiar uma configuração incompatível.

A IA pode redigir conceitos gerais, uso de frameworks, boas práticas e erros comuns, mas uma pessoa precisa verificá-los. Uma explicação sobre React hooks pode soar correta; a quantidade de regras, as convenções de nome e as diferenças entre versões devem ser comparadas com a documentação oficial.

Organização estrutural, edição de estilo e formatação podem ficar com a IA. Reformular uma explicação ou reunir parágrafos relacionados normalmente não exige pesquisa adicional.

Comparação:

Tipo de pesquisa	Conteúdo típico	Rigor do controle	Etapa
Pesquisar primeiro	Versões, campos de API, preços ou cotas, segurança	Alto: extrair da documentação oficial e marcar [VERIFY]	Preparar no planejamento e revisar no dia da redação
Rascunho de IA + revisão	Conceitos gerais, frameworks, boas práticas	Médio: comparar o rascunho com a documentação oficial	Redigir e verificar durante a revisão
Redação pela IA	Estrutura, edição de estilo, formatação	Baixo: nenhuma pesquisa adicional	Concluir durante a redação

Árvore de decisão:

Encontrou um conteúdo do tipo X
  ↓
Envolve versão, API, preço ou segurança?
  ├─ Sim → Extrair da documentação oficial, marcar [VERIFY] e revisar no dia da redação
  └─ Não → Envolve regra técnica ou boa prática?
      ├─ Sim → A IA redige; a revisão compara com a documentação oficial
      └─ Não → A IA organiza a explicação

Como levar o resultado da pesquisa para a entrada do outline?

Depois da pesquisa, os resultados entram no outline input para que a etapa de redação consiga citá-los diretamente.

Extraia de research.md as fontes de alta confiança marcadas como high, como as orientações de helpful content do Google Search Central, o exemplo oficial de CI com Node.js no GitHub Actions e a documentação de Content Collections do Astro.

Marque fatos voláteis com [VERIFY]: “A franquia do GitHub Actions para repositórios privados depende do plano da conta [VERIFY]” ou “A versão alvo do Node ainda tem suporte [VERIFY]”.

Registre cartões de fonte, saídas de comando e resultados da revisão nos campos source_cards e risk_notes do outline input:

{
  "source_cards": [
    {
      "url": "https://developers.google.com/search/docs/fundamentals/creating-helpful-content",
      "type": "official/docs",
      "confidence": "high",
      "usable_info": "O conteúdo deve oferecer informações originais e uma explicação completa, sem depender principalmente de automação em massa"
    }
  ],
  "risk_notes": [
    {
      "fact": "Franquia gratuita do GitHub Actions",
      "status": "[VERIFY]",
      "check_date": "2026-06-24",
      "source": "https://docs.github.com/en/billing/managing-billing-for-github-actions"
    }
  ]
}

Com os marcadores prontos, a redação não precisa refazer toda a pesquisa; ela apenas confere os fatos voláteis indicados.

Valide os exemplos de código: parecer correto não basta

Quatro cenários de validação de código

Exemplos em artigos técnicos frequentemente parecem corretos e falham na prática. Quando o leitor copia e recebe um erro, a confiança no artigo desaparece.

Há quatro cenários de validação.

Execução local cobre comandos de instalação, exemplos de configuração e scripts simples, como npm install, git clone e alterações em arquivos de configuração. Esses comandos devem ser executados localmente, com a saída registrada.

Testes de CI cobrem build, testes e dependências de ambiente, como npm ci, npm run build e npm test no GitHub Actions. O CI é adequado porque mantém o ambiente consistente.

Gerenciamento de versões inclui versões do Node, dependências e APIs, como .nvmrc, package.json e alterações de endpoint. O texto deve indicar a versão e explicar diferenças relevantes. Consistência de ambiente inclui divergências entre desenvolvimento, produção e CI, como variáveis de ambiente, imagens Docker e sistemas operacionais. O ambiente de execução deve aparecer para evitar erros em condições diferentes.

Comparação:

Cenário de validação	Conteúdo típico	Método	Evidência obrigatória
Execução local	Instalação, arquivos de configuração	Executar localmente	Texto da saída ou captura
Teste de CI	Build e testes	GitHub Actions ou outro CI	Log do CI ou captura do resultado
Gerenciamento de versão	Node e dependências	Comando de versão	Saída de node --version + versão declarada
Consistência de ambiente	Variáveis e Docker	Teste em vários ambientes ou declaração explícita	Ambiente + condições

Como registrar evidências de execução?

Todo exemplo de código precisa de evidência de execução; escrever apenas “funcionou” não basta. Os comandos e resultados abaixo mostram o formato de um registro de evidência, não uma comprovação real reutilizável. Em outro artigo, substitua-os pelas versões e pelos logs reais do projeto alvo.

Exemplo de comandos para CI com Node.js:

# Ambiente local: macOS + Node 18.20.0 LTS
$ node --version
v18.20.0

# Ambiente de CI: GitHub Actions
$ npm ci
added 245 packages in 12s

$ npm run build
✓ Built in 1.23s

$ npm test
✓ 12 tests passed

Comparação:

✅ Correto: incluir captura ou texto da saída, versão e pontos relevantes.

❌ Incorreto: escrever “execução concluída” sem apresentar evidência.

Em blocos de código, use fenced code blocks com identificador de linguagem, como bash ou typescript. Para saídas longas, use uma seção recolhível ou mostre apenas os trechos importantes. Em comandos com várias etapas, identifique o ambiente, como local, CI ou Docker. Em verificações de versão, inclua a saída de node --version ou npm --version.

Exemplo:

# Ambiente de execução: macOS + Node 18.20.0
$ npm install
added 124 packages in 8s

$ node --version
v18.20.0

Se a saída for longa, mostre somente a parte relevante:

$ npm run build
✓ Built in 1.23s
  ├─ dist/index.html
  ├─ dist/assets/index.js
  └─ dist/assets/index.css

A documentação do GitHub recomenda fenced code blocks com destaque de sintaxe em Creating and highlighting code blocks. Um blog técnico deve manter esse padrão, não disfarçar código como texto corrido.

Revisão humana não é só polimento: verifique fatos, código e estrutura

Revisão factual: versões, parâmetros e preços precisam de origem

A revisão humana cobre três camadas: fatos, código e estrutura. Tratar a revisão como uma simples troca de palavras deixa passar versões erradas, parâmetros inválidos e conclusões incompatíveis com o código.

O núcleo da revisão factual é a rastreabilidade. Toda versão, campo de API, argumento de comando, configuração, preço, cota e data de lançamento deve ser comparado com documentação oficial ou execução real.

Checklist:

Item	Como revisar	Sinal de falha	Exemplo correto
Versão	Comparar com release ou documentação oficial	Versão inexistente ou recurso descrito incorretamente	Link oficial + saída de node --version
Argumento de comando	Comparar com a documentação da CLI	Argumento inexistente ou formato errado	Link oficial + saída real
Campo de API	Comparar com a documentação da API	Campo inexistente ou tipo errado	Link oficial + requisição real
Preço ou cota	Comparar com a página oficial de preços	Preço errado ou condição público/privado ausente	Link oficial + condição de uso
Data de lançamento	Comparar com anúncio ou blog oficial	Data errada ou evento inexistente	Link para o anúncio oficial

Exemplos incorretos:

O projeto declara "type": "module" no package.json, mas o código usa diretamente o require do CommonJS sem trocar para .cjs nem explicar o limite entre módulos.

O artigo diz que “o GitHub Actions tem apenas 2.000 minutos por mês”, sem explicar que os runners padrão hospedados pelo GitHub são gratuitos em repositórios públicos e que os minutos incluídos em repositórios privados dependem do plano.

Exemplos corretos:

“O Node 18 oferece ES modules e CommonJS; .mjs, .cjs e o campo type do package.json determinam como um arquivo é interpretado. O registro foi obtido com Node 18.20.0 e inclui a saída de node --version (fonte: documentação oficial do Node.js).”

“Em 26 de julho de 2026, runners padrão hospedados pelo GitHub são gratuitos em repositórios públicos. Repositórios privados recebem minutos conforme o plano, como 2.000 no GitHub Free e 3.000 no GitHub Pro (fonte: GitHub Actions billing).”

Revisão de código: execução, saída e ambiente

A revisão de código verifica três pontos: o comando executa, a saída corresponde ao texto e o ambiente está declarado.

Checklist:

Item	Como revisar	Sinal de falha	Exemplo correto
Execução do comando	Executar localmente ou no CI	Erro ou dependência ausente	Log ou captura
Correspondência da saída	Comparar com o texto	Saída diferente da descrição	Texto e saída consistentes
Ambiente	Conferir a declaração	Versão do Node ou sistema ausente	Node 18.20.0 + macOS
Versão da dependência	Conferir package.json	Versão diferente da descrita	package.json ou saída do comando de versão

Exemplos incorretos:

O texto diz que “o build gerou três arquivos”, mas a saída real de npm run build mostra cinco.

O texto diz que “funcionou localmente”, mas o exemplo depende de Docker e não menciona essa diferença.

Exemplos corretos:

“npm run build gerou três arquivos: index.html, index.js e index.css”, exatamente como mostra a saída.

“O exemplo foi testado no macOS com Node 18.20.0. Linux, Windows ou outra versão podem exigir ajustes de caminho.”

Revisão de estrutura e estilo: H2/H3, links internos e resíduos de IA

Essa camada verifica se os H2/H3 correspondem ao outline, se os links internos ocupam os locais planejados e se frases vagas típicas de IA foram removidas.

Checklist:

Item	Como revisar	Sinal de falha	Exemplo correto
Consistência de H2/H3	Comparar com outline.md	Título removido ou adicionado	Registrar o motivo da alteração
Links internos	Comparar com o plano de links	Link ausente ou âncora errada	Posicionar conforme o plano
Resíduos de IA	Comparar com anti-ai-words.json	Clichê temporal ou promessa vaga	Substituir por um fato concreto ou remover

O arquivo anti-ai-words.json do projeto define duas categorias de expressão a evitar. Durante a revisão, substitua ou remova generalizações, atribuições vagas e promessas exageradas.

Exemplos incorretos:

Abrir o texto com um clichê sobre a era atual.

Prometer “uma análise completa” sem dizer o que será verificado.

Exemplos corretos:

Remova o clichê e vá direto ao problema: “Ao escrever um blog técnico com IA, a primeira pergunta é quais fatos precisam vir de fora.”

Troque a promessa vaga por um critério concreto: “Este artigo apresenta um fluxo executável de redação, validação e revisão.”

Feche o processo com um QA antes da publicação

Checklist de QA antes da publicação

Terminar o texto não significa que ele está pronto. O QA final verifica marcadores de pesquisa, validação de código, rastreabilidade, estrutura, links internos, resíduos de IA e imagens.

Item	Como verificar	Condição de aprovação	Tratamento da falha
Marcadores de pesquisa	Procurar [VERIFY]	Nenhum marcador pendente	Voltar à pesquisa
Exemplos de código	Comparar com os logs	Todos têm evidência de execução	Voltar à validação
Fatos rastreáveis	Conferir cartões de fonte	Todo fato tem fonte ou limite declarado	Adicionar fonte ou remover afirmação
Estrutura	Comparar com outline.md	H2/H3 consistentes ou alteração explicada	Atualizar outline ou registrar motivo
Links internos	Comparar com o plano	Todos posicionados com âncora correta	Adicionar link ou ajustar plano
Resíduos de IA	Conferir anti-ai-words.json	Nenhuma expressão proibida	Substituir ou reescrever
Imagens	Conferir inventário e caminhos Markdown	Todos os caminhos válidos e processados	Enviar imagem ou ajustar o caminho

Estados:

✅ Aprovado: pode publicar

⚠️ Pendente: precisa de nova revisão ou fonte

❌ Falha: exige reescrita ou retorno à pesquisa/validação

Valide um item por vez. Ao encontrar um problema, marque o estado imediatamente. Somente quando tudo passar o status da tarefa deve mudar para “pronto para publicação”.

Como retornar quando o QA encontra um problema?

O problema deve voltar à etapa responsável; não deve ser ignorado.

Um erro factual volta à pesquisa: adicione documentação oficial, remova afirmações não rastreáveis e confira fatos voláteis.

Um erro de código volta à validação: execute novamente, registre a saída, atualize o exemplo e declare o ambiente.

Uma divergência estrutural exige atualizar o outline ou registrar a justificativa, indicando quais H2/H3 foram removidos ou adicionados.

Um link ausente volta ao mapa do cluster e ao inventário do site, usando uma âncora descritiva em vez de “clique aqui”.

Resíduos de IA voltam à edição com anti-ai-words.json; se não houver substituição concreta, reescreva o parágrafo.

Exemplo:

O QA detecta que a cota do GitHub Actions não informa a condição público/privado
  ↓
Marcar como falha
  ↓
Voltar à pesquisa
  ↓
Adicionar a fonte oficial de cobrança e as condições
  ↓
Executar o QA novamente

Esse retorno torna a responsabilidade visível. A pessoa que revisa no fim não deve receber uma mudança sem explicação.

Sete sinais de que o artigo se afastou dos fatos

Os sete sinais

O desvio factual se acumula. Estes sinais ajudam a encontrá-lo antes da publicação.

Sinal 1: afirmação sem fonte. O texto diz “versão mais recente”, “recomendação oficial” ou “boa prática” sem link. Por exemplo, afirma que uma chave do Turbopack funciona em todas as versões do Next.js sem citar documentação.

Sinal 2: código não executado. Não existe saída nem log; há apenas “funciona”.

Sinal 3: versão ou parâmetro classificado incorretamente. A versão pode existir, mas sua linha ou suporte está errado; parâmetros e endpoints também mudam. O Node 20.1.0 era Current, não LTS.

Sinal 4: ambiente incoerente. A evidência informa um ambiente, mas o comportamento foi validado em outro.

Sinal 5: conclusão não reproduzível. O texto afirma uma melhoria sem método, dados ou etapas.

Sinal 6: link interno quebrado. O artigo aponta para /posts/ai/ai-xxx, mas a rota não existe.

Sinal 7: uma frase vaga esconde a falta de evidência. “Análise completa” substitui uma fonte ou resultado.

Exemplos:

Sinal	Exemplo incorreto	Problema
Sem fonte	“Esta chave do Turbopack funciona em todas as versões do Next.js”	Sem documentação oficial
Código não executado	“Execute npm install; funciona”	Sem evidência
Versão incorreta	“Node 20.1.0 LTS”	20.1.0 era Current
Ambiente incoerente	O registro indica um ambiente antigo e a validação ocorre em outro	Versão e ambiente não correspondem
Conclusão não reproduzível	“O desempenho melhorou muito”	Sem método nem dados
Link quebrado	Link para /posts/ai/ai-xxx	Rota inexistente
Resíduo de IA	“Análise completa de redação com IA”	Promessa vaga

Ao encontrar um sinal, marque [VERIFY] e devolva-o à etapa responsável.

Uma afirmação sem fonte volta à pesquisa, código não executado à validação e versão errada ao release oficial. Um ambiente incoerente exige as condições corretas ou a remoção da afirmação. Uma conclusão irreproduzível precisa de método, dados e etapas, ou deve ser apagada. Um link quebrado deve usar uma rota real. Uma frase vaga precisa ser concretizada ou removida.

O retorno deve ser imediato. Caso contrário, pequenas incertezas se acumulam e formam um artigo impossível de rastrear.

Escreva com honestidade sem um ambiente completo

Três maneiras honestas

Às vezes falta um serviço pago, um cluster complexo, um sistema operacional ou hardware específico. Não invente evidências. Há três alternativas.

Primeira: declare condições e limites. Informe a versão testada e possíveis diferenças, ou que apenas o plano gratuito foi coberto. Exemplo: “O exemplo foi validado somente com Node 18.20.0; outras versões podem variar.”

Segunda: ofereça uma validação alternativa. Pode ser uma reprodução mínima, dados Mock ou um issue oficial. Exemplo: “Não havia um cluster Kubernetes disponível; há apenas uma reprodução mínima que ainda precisa ser testada em um cluster real.”

Terceira: admita o que não foi verificado. Escreva “Esta conclusão de desempenho não foi reproduzida no ambiente atual” ou remova a afirmação.

Comparação:

Situação	Redação enganosa	Redação honesta
Diferença de versão	“Todas as versões oferecem suporte”	“Validado com Node 18.20.0; outras versões podem variar”
Diferença de ambiente	“Funcionou localmente”	“Testado no macOS com Node 18.20.0; Linux, Windows ou outra versão podem exigir ajustes”
Serviço pago	“É gratuito”	“Somente o plano gratuito foi testado; recursos pagos podem variar”
Afirmação não verificada	“O desempenho melhorou muito”	“O ambiente atual não reproduziu esta conclusão de desempenho”

Exemplos válidos:

“O teste usou o plano gratuito do Cloudflare Workers, que atualmente inclui 100.000 solicitações por dia. As condições pagas podem variar; consulte a página oficial de preços.”

“Não havia um cluster Kubernetes disponível. A reprodução mínima ainda precisa ser testada em um cluster real, considerando limites de Pod e configuração de rede.”

“Não há medição de um projeto grande, portanto não se afirma nada sobre o desempenho de build do Turbopack. Registre uma linha de base e uma comparação no seu projeto.”

Exemplos inválidos:

“Cloudflare Workers é gratuito.” A cota está ausente.

“Funciona em qualquer ambiente.” O ambiente está ausente.

“O desempenho melhorou muito.” Método e dados estão ausentes.

O Google Search Central recomenda informações originais, explicações completas e análises úteis em Creating helpful, reliable, people-first content. Explicar uma limitação não reduz o padrão: separa o que foi verificado do que ainda precisa de teste.

Quando publicar e quando revisar o rascunho

Árvore de decisão de publicação

A decisão não depende da quantidade de palavras nem de uma aparência finalizada. Pesquisa, validação, revisão e QA precisam passar.

Pesquisa: se todas as fontes confiáveis estão disponíveis e os dados voláteis estão marcados, avance para a validação. Se uma fonte central estiver ausente, pesquise.

Validação: se todos os exemplos funcionam, avance para a revisão. Corrija ou remova exemplos que falharam. Exemplos que não podem ser verificados precisam declarar os limites ou sair.

Revisão humana: se os fatos são rastreáveis, avance para o QA. Documente ou remova afirmações sem fonte. Uma alteração estrutural explicada pode avançar; uma divergência sem explicação volta ao planejamento.

QA antes da publicação: se tudo passar, o artigo avança. Um item pendente exige revisão e uma falha volta à etapa responsável.

Um artigo avança quando pesquisa e atualização estão completas, o código tem evidências, a revisão confirma fatos e estrutura, resíduos de IA foram removidos e o QA passou.

Se faltar fonte, registro, link interno ou limpeza de estilo, ainda há trabalho.

Uma versão, parâmetro, preço ou outro fato central incorreto, uma conclusão principal irreproduzível ou uma estrutura fora do objetivo sem explicação exigem revisão.

Cada etapa tem um controle. A falha volta à causa e não chega à publicação.

Prioridade:

Primeiro, corrija ou remova erros factuais. Depois, erros de código que um leitor poderia copiar. Estrutura e links têm prioridade menor, mas devem ser resolvidos antes da publicação.

Leituras relacionadas

Para fornecer o contexto do projeto à IA, leia como usar CLAUDE.md para evitar código incorreto. Para empacotar redação e revisão como etapas reutilizáveis, consulte fluxos com Claude Code Skills.

Há também um fluxo de redação com IA para conteúdo geral. Esse texto prioriza velocidade; este prioriza fatos técnicos, evidências de execução e controles de publicação. Os dois podem ser combinados.