Open Code Review: revisão de diffs com regras e comentários por linha

ANÁLISE EDITORIAL

Revisar código com um agente não deveria começar por uma pergunta vaga como “há algum problema aqui?”. Primeiro é preciso decidir qual diff entra, quais arquivos ficam fora, que regra se aplica a cada caminho e como cada comentário volta para uma linha verificável. Open Code Review transforma essa preparação em um fluxo operado pelo CLI ocr, combinando seleção determinística de mudanças Git com análise apoiada por modelo.

Esta Skill não substitui revisão humana, testes, análise de segurança ou aprovação de merge. Ela ensina o agente a reunir contexto de negócio, escolher o alvo, executar a revisão em modo próprio para agentes e organizar achados por severidade e categoria. O resultado esperado é uma lista de comentários que a equipe consegue conferir no código, não uma declaração automática de qualidade.

Imagem: Ilustração editorial exclusiva do Bastidores da IA sobre alterações de código passando por trilhos de regras e uma lente analítica. Não é captura de tela, interface real, logotipo oficial, benchmark nem prova de revisão executada.

O que esta Skill faz de verdade

O SKILL.md fixado no commit auditado orienta quatro etapas. Primeiro, o agente resume o contexto do trabalho. Depois, chama ocr review com esse contexto no parâmetro --background. Em seguida, interpreta a saída estruturada. Por fim, só entra em correção quando o pedido do usuário autorizou essa segunda ação.

O CLI pode revisar o workspace, um commit específico ou um intervalo entre referências Git. No modo padrão de workspace, a documentação informa que entram mudanças staged, unstaged e arquivos não rastreados. Para um commit, usa --commit. Para comparar branches ou outras referências, usa --from e --to. O modo --preview permite conferir o alvo antes de chamar o modelo.

A saída inclui caminho, conteúdo do comentário, linha inicial e final, categoria, severidade e, quando disponível, sugestão de código. A Skill manda agrupar achados críticos, altos e médios e filtrar itens baixos com aparência de ruído. Isso é uma regra de apresentação da Skill, não prova de que os níveis foram calibrados para todo projeto.

Para quem serve

Serve para desenvolvedores, mantenedores e equipes que já trabalham com Git e precisam transformar uma revisão assistida por IA em um processo repetível. É mais útil quando o alvo é claro, o repositório tem regras próprias e a equipe quer comentários localizados, em vez de uma opinião geral sobre a arquitetura.

Também pode apoiar uma triagem antes da revisão humana de pull request. O agente identifica o contexto, o CLI seleciona arquivos e aplica regras, e a pessoa revisora decide quais achados merecem correção. A ferramenta não deve ser usada para aprovar merge sozinha, avaliar desempenho de pessoas ou enviar código confidencial a um provedor sem autorização.

Ela não duplica a Code Review and Quality já catalogada. A entrada anterior é uma metodologia geral de revisão por correção, arquitetura, segurança e legibilidade. Open Code Review é específica para operar o CLI ocr, seus modos de diff, regras por caminho, formato de comentários e tratamento de falhas.

Compatibilidade e pré-requisitos

O repositório oficial lista Windows, macOS e Linux e apresenta integrações para Codex, Claude Code, Cursor e outros clientes. O arquivo da Skill é um Agent Skill portátil, mas o uso real depende do CLI externo. No commit auditado, o package.json exige Node.js 14 ou mais recente para o pacote npm. O README oficial pede Git 2.41 ou mais recente.

Antes de revisar, o projeto precisa estar acessível como repositório Git e o comando ocr precisa responder. O fluxo descrito na Skill requer um provedor Anthropic ou compatível com OpenAI configurado. A documentação mais ampla do produto também descreve um modo de delegação, mas essa alternativa não substitui a necessidade de entender qual agente lerá os arquivos e qual política de dados se aplica.

Tenha uma branch de base correta, um alvo identificável e comandos de teste conhecidos. Se o repositório usa monorepo, código gerado ou arquivos vendorizados, defina exclusões e regras antes da primeira revisão. Sem esse preparo, uma execução pode gastar contexto em arquivos irrelevantes ou emitir comentários sobre artefatos que a equipe não edita.

Instalação recomendada

A forma documentada pelo projeto é instalar o pacote npm global. Para reproduzir a versão consultada nesta curadoria, fixe o release:

npm install -g @alibaba-group/open-code-review@1.9.9
ocr --version

O pacote instala o CLI e obtém os componentes previstos para a plataforma. Consulte a documentação oficial de instalação e o registro npm da versão 1.9.9 antes de executar. Em ambiente corporativo, use o registro aprovado, confira a origem e evite instalar globalmente em uma estação compartilhada sem revisão.

O ZIP local do Bastidores não instala o ocr. Ele contém somente o SKILL.md original, a licença Apache-2.0 e o registro ORIGEM.md. Não há binário, instalador npm, código do aplicativo, dependência, token ou credencial. O download próprio serve para auditoria documental e comparação com o commit fixado.

Configuração antes do primeiro uso

Inicie pelo comando interativo de configuração do provedor:

ocr config provider
ocr config model
ocr llm test

Não cole chave em arquivo versionado, argumento de terminal compartilhado, captura ou conversa. Use o mecanismo de configuração previsto pelo produto e um segredo com escopo adequado. Confirme se a política do provedor permite enviar o código daquele repositório. Uma chave válida não é autorização para processar propriedade intelectual de cliente.

Depois, defina as regras. Segundo a Skill, a precedência é: caminho passado em --rule, arquivo .opencodereview/rule.json no repositório, regra no diretório pessoal e padrões internos. A primeira regra correspondente substitui a regra do sistema por padrão; merge_system_rule precisa ser explícito quando as duas devem ser usadas.

Revise cada padrão de caminho e escreva regras verificáveis. “Código deve ser bom” não orienta uma decisão. “Métodos novos deste diretório validam parâmetros obrigatórios antes do acesso” permite localizar a condição e testar a correção. A documentação oficial de regras detalha o formato e a resolução.

Primeiro uso seguro

Comece sem chamar o modelo. Em uma cópia ou branch controlada, execute:

ocr review --preview

Confira se arquivos staged, unstaged e não rastreados pertencem ao escopo. Remova segredos e dados de teste reais, ou restrinja o alvo. Para revisar um commit, prefira ocr review --preview --commit <sha>. Para uma branch, confirme a base antes de usar --from e --to. O objetivo é saber exatamente qual diferença será enviada.

Quando o preview estiver correto, reúna uma frase de contexto de negócio sem dados sensíveis e execute o modo para agente:

ocr review --audience agent --background "contexto funcional e limite da mudança" --commit <sha>

A Skill recomenda redirecionar saídas grandes para arquivo temporário e ler o conteúdo completo, em vez de usar head ou tail. Registre exit code, stderr e arquivos que falharam. Se a conexão com o provedor falhar, investigue a configuração; não repita cegamente uma chamada que pode consumir orçamento ou duplicar envio de contexto.

Resultado esperado

O resultado esperado é uma revisão estruturada com número de arquivos e achados agrupados por severidade. Cada item deve trazer caminho, linha quando localizada, categoria, descrição e recomendação. Categorias previstas incluem bug, segurança, desempenho, manutenibilidade, teste, estilo e documentação.

Quando linha inicial e final aparecem como zero, a própria Skill considera que o posicionamento falhou. Nesse caso, o agente deve ler o comentário, abrir o arquivo indicado e localizar o trecho por contexto antes de sugerir alteração. Um comentário sem posição não deve ser anexado ao primeiro bloco parecido por conveniência.

Se não houver achados críticos, altos ou médios após a filtragem, o relatório pode dizer isso com o total de arquivos revisados. A frase não significa “código seguro”. Ela significa apenas que aquela execução, com aquele alvo, regras, provedor e limite, não manteve achados nesses níveis.

Permissões e riscos

O risco principal é de exposição. Uma revisão pode ler código proprietário, configuração, testes, caminhos internos e arquivos não rastreados. Dependendo do provedor, esse conteúdo sai da máquina. Restrinja o diff, use conta aprovada, confira retenção e não envie segredos. O guia do Bastidores sobre permissões de agentes ajuda a separar leitura, rede, escrita e publicação.

O segundo risco é alteração indevida. A Skill permite entrar na etapa de correção quando o usuário pediu “revisar e corrigir”. Mesmo assim, isso não autoriza commit, push ou merge. Aplique mudanças em branch isolada, leia o diff produzido, execute testes e mantenha revisão humana. Se o pedido foi apenas revisar, pergunte antes de editar.

Há ainda risco de falsa segurança e custo. Regras mal escritas, diff parcial, arquivos truncados, limites de token e um provedor indisponível alteram o resultado. A Skill menciona concorrência e timeout ajustáveis, mas números padrão não são promessa de desempenho. Não use estrelas, release ou formato estruturado como substituto de teste independente.

Erros comuns

• Rodar no diretório errado: confirme a raiz Git ou informe o repositório de forma explícita.
• Esquecer arquivos não rastreados: o modo workspace os inclui; revise o preview.
• Comparar a branch com a base errada: confirme referências e merge base antes da análise.
• Enviar segredo ao provedor: remova credenciais e restrinja o diff antes da rede.
• Usar regra vaga: transforme preferência em condição observável por caminho.
• Aplicar sugestão automaticamente: confira contexto, diff, testes e aprovação.
• Ignorar comentário sem linha: localize o trecho manualmente antes de agir.
• Tratar saída vazia como certificação: registre escopo, regras, modelo e limitações.
• Tratar o ZIP como runtime: o pacote local é documental e não contém o CLI.

Versão auditada e download local

A curadoria fixou o commit 66120291271b2e605e420e9f11fbd6448f06163f. O SKILL.md declara versão 1.0.0. O release do CLI consultado foi v1.9.9, publicado pelo repositório oficial, e o registro npm também apontava 1.9.9 como versão mais recente na consulta.

Em 22/08/2026, o repositório alibaba/open-code-review tinha 21.125 estrelas e não estava arquivado. Estrelas indicam adoção observável, não auditoria de segurança, precisão ou resultado garantido.

A licença Apache-2.0 permite redistribuição sob suas condições. O ZIP local tem 9.260 bytes, contém somente SKILL.md, LICENSE e ORIGEM.md, e possui SHA-256 740f7ee2826bda1cc830f88cee516fbb4447962f50f911330c14129dfcc679a8. O SKILL.md e a licença preservam os hashes dos arquivos oficiais auditados.

Resultado esperado e limite final

Open Code Review faz sentido quando a equipe quer uma revisão de diff com alvo explícito, regras por arquivo e comentários que possam voltar ao código. A parte determinística ajuda a organizar seleção e posicionamento. O modelo ainda interpreta contexto e pode errar, omitir ou exagerar.

Considere a execução útil quando o preview foi conferido, o contexto não contém dado indevido, cada achado pode ser localizado e a equipe sabe o que não foi validado. Considere a correção concluída somente após revisar o diff, rodar testes proporcionais ao risco e obter a aprovação exigida pelo projeto.

O download local preserva a instrução. O botão do repositório oficial leva ao projeto que fornece o CLI, releases e documentação. Mantenha essas duas ações separadas: ler uma Skill não instala um programa, e instalar um programa não autoriza enviar qualquer repositório para análise.

Fontes primárias

• Repositório oficial alibaba/open-code-review
• Diretório da Skill no commit auditado
• SKILL.md oficial fixado
• README oficial com requisitos e modos de revisão
• Quickstart oficial do Open Code Review
• Configuração oficial de provedor e modelo
• Referência oficial do CLI
• Release v1.9.9 consultado
• Licença Apache-2.0 preservada no pacote