> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acrity.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Policy Engine

> Configure a política padrão de revisão do workspace na Acrity.

O `Policy Engine` define a política padrão de revisão para o workspace. Ele controla quais tipos de revisão ficam ativos, quais instruções adicionais devem orientar a análise e quais autores devem ser incluídos ou bloqueados.

Use `Console > Policy Engine` para configurar o padrão do workspace. Use a configuração do repositório apenas para exceções.

## Quem pode acessar

O `Policy Engine` requer um admin de workspace. Os papéis são conjuntos fixos de capacidades definidos pela Acrity, portanto esse acesso não é configurável por organização.

## Quando usar

Use esta tela para:

* ativar ou desativar tiers de revisão no workspace;
* adicionar instruções gerais de revisão;
* definir bots que podem ser revisados;
* bloquear autores que não devem gerar revisão;
* consultar ou rotacionar configuração de webhook quando a tela exibir essa opção;
* alinhar a política padrão antes de conectar muitos repositórios.

## Tiers de revisão

| Tier   | Uso típico                                                             |
| ------ | ---------------------------------------------------------------------- |
| `Fast` | Revisão mais direta para mudanças comuns, com foco em retorno rápido.  |
| `Deep` | Revisão mais completa para mudanças que exigem análise mais cuidadosa. |

O workspace deve manter pelo menos um tier ativo. Se ambos estiverem ativos, a Acrity pode aplicar a política configurada conforme o contexto do review e as opções disponíveis no produto.

<Note>
  Não use tiers como substituto para regras de branch. Branch rules devem ficar em `Console > Repositórios`.
</Note>

## Instruções adicionais

As instruções adicionais permitem adaptar a revisão ao padrão da organização.

Use para registrar diretrizes como:

* padrões de arquitetura esperados;
* critérios de qualidade relevantes para a organização;
* cuidados com testes, segurança ou compatibilidade;
* linguagem esperada nos comentários;
* decisões de produto que devem ser consideradas.

Evite incluir:

* segredos;
* tokens;
* informações confidenciais de clientes;
* regras internas que não deveriam aparecer em saídas de revisão;
* instruções específicas demais para um único repositório.

Para regras específicas de um repositório, use `Console > Repositórios > Detalhe > Review`.

## Substituições de prompt de revisor

Cada papel de revisor tem seu próprio campo de substituição de prompt, permitindo ajustar com precisão como um revisor específico analisa mudanças em todo o workspace.

| Revisor        | Orienta                                                                |
| -------------- | ---------------------------------------------------------------------- |
| Architect      | Estrutura, design e como uma mudança se encaixa no sistema mais amplo. |
| Spec Validator | Alinhamento entre a mudança e os requisitos declarados.                |
| QA Engineer    | Cobertura de testes, casos extremos e qualidade geral.                 |

Cada campo:

* aceita até 2.000 caracteres;
* indica se o texto atual é uma **substituição do workspace** ou o **padrão global**;
* oferece uma ação **Revert to global** que descarta a substituição do workspace e restaura o padrão global.

Quando um campo exibe o padrão global, esse revisor usa a orientação nativa da Acrity. Quando você salva um texto em um campo, ele se torna uma substituição do workspace que se aplica às revisões em todo o workspace, substituindo o padrão global para esse revisor.

```mermaid theme={null}
flowchart LR
  A[Padrão global] -->|Salvar texto do workspace| B[Substituição do workspace]
  B -->|Revert to global| A
```

<Warning>
  Use as substituições de prompt de revisor com cautela. Elas alteram o comportamento do revisor em todo o workspace, e é fácil esquecer que uma substituição está ativa. Para orientações duradouras e de longo prazo, prefira commitar um arquivo `ARCHITECTURE.md` no repositório, para que a orientação fique junto ao código e seja versionada com ele.
</Warning>

## Política de autores

A política de autores ajuda a controlar quais mudanças devem ser revisadas.

| Campo              | Para que serve                                                     |
| ------------------ | ------------------------------------------------------------------ |
| Bots permitidos    | Identifica contas automatizadas cujos PRs/MRs podem ser revisados. |
| Autores bloqueados | Impede revisões para autores específicos.                          |

Use bots permitidos quando automações criam mudanças que devem receber revisão, como atualização de dependências. Use autores bloqueados para evitar ruído operacional ou excluir contas que não devem gerar análise.

## Chave ou URL de webhook

Alguns workspaces podem exibir configuração de webhook vinculada ao fluxo de revisão.

Quando a tela exibir essa opção:

* copie a URL apenas para o provedor correto;
* trate a chave como segredo;
* rotacione a chave se houver suspeita de exposição;
* atualize o provedor depois de rotacionar;
* valide o webhook pelo Console ou pelo provedor.

<Warning>
  Não compartilhe chaves de webhook em chats, tickets públicos, comentários de PR/MR ou documentação interna ampla.
</Warning>

## Configurar política padrão

<Steps>
  <Step title="Abrir Policy Engine">
    Acesse `Console > Policy Engine`.
  </Step>

  <Step title="Revisar tiers">
    Ative `Fast`, `Deep` ou ambos, conforme a política do workspace.
  </Step>

  <Step title="Adicionar instruções">
    Preencha instruções adicionais gerais que se aplicam à maioria dos repositórios.
  </Step>

  <Step title="Ajustar prompts de revisor (opcional)">
    Defina uma substituição do workspace para o revisor Architect, Spec Validator ou QA Engineer apenas quando necessário e reverta ao padrão global quando não for mais preciso.
  </Step>

  <Step title="Configurar autores">
    Adicione bots permitidos e autores bloqueados quando necessário.
  </Step>

  <Step title="Salvar">
    Salve e confirme mensagens de validação.
  </Step>

  <Step title="Testar em repositório">
    Escolha um repositório representativo e acompanhe a próxima revisão no dashboard Ops para validar o comportamento esperado.
  </Step>
</Steps>

## Relação com configuração do repositório

| Nível       | Melhor uso                                         |
| ----------- | -------------------------------------------------- |
| Workspace   | Política padrão para a maioria dos repositórios.   |
| Repositório | Exceções para projetos com necessidade específica. |

Mantenha a política do workspace simples e estável. Isso reduz divergência entre times e facilita auditoria.

## Boas práticas

* Escreva instruções curtas, claras e verificáveis.
* Evite duplicar documentação longa dentro do campo de instruções.
* Não inclua segredos ou dados confidenciais.
* Revise a política após mudanças grandes de processo.
* Use exceções por repositório com moderação.
* Reverta as substituições de prompt de revisor ao padrão global assim que não forem mais necessárias e mantenha orientações duradouras no `ARCHITECTURE.md` do repositório.
* Combine política de autores com branch rules para reduzir ruído.

## Problemas comuns

| Sintoma                                                  | O que verificar                                                                                                              |
| -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| Não consigo salvar                                       | Confirme se pelo menos um tier está ativo e se os campos respeitam as validações da tela.                                    |
| Um repositório não segue o padrão                        | Verifique se ele possui configuração própria na aba Review.                                                                  |
| Reviews estão ruidosas                                   | Revise instruções adicionais, política de autores e branch rules dos repositórios.                                           |
| Um revisor se comporta de forma inesperada em todo lugar | Verifique se há uma substituição de prompt do workspace definida para esse revisor e use **Revert to global** se necessário. |
| Bot esperado não foi revisado                            | Confirme se a conta está em bots permitidos e se o evento atende às regras do repositório.                                   |
| Autor continua gerando review                            | Verifique grafia, identificador usado pelo provedor e configuração do repositório.                                           |