👤 Para responsáveis por processos e administradores de pipes
🔐 Boas práticas aplicáveis a todos os planos; recursos citados dependem das permissões e da contratação da empresa
🎯 Para quem quer preparar um processo para mudanças e passagem de responsabilidade
Uma pessoa precisa mudar o critério de aprovação de compras, mas a explicação está dividida entre mensagens antigas e a memória de quem montou o fluxo. Antes de avaliar a mudança, o time precisa descobrir quais informações sustentam a decisão e quem deve participar da revisão.
Ao terminar esta leitura, você vai saber o que registrar sobre um processo, onde manter essas informações e como usar o registro para planejar a próxima manutenção. O objetivo é permitir que outra pessoa entenda o funcionamento do pipe e encontre as dependências que precisa conferir antes de alterar algo.
📖 O que você vai entender aqui:
O que uma documentação útil precisa explicar
Uma documentação útil responde a duas perguntas: como o processo funciona e por que ele foi organizado dessa forma. Uma lista de fases mostra o caminho, mas quem assume a manutenção também precisa entender o que determina as decisões ao longo dele.
Comece pelo objetivo, pelo ponto de entrada e pelo resultado que encerra o trabalho. Identifique o papel responsável pelo processo e as decisões que exigem sua participação. Se o fluxo continua em outro pipe, registre onde termina a responsabilidade de cada time.
Em um exemplo hipotético de compras, o escopo pode começar no recebimento da solicitação e terminar na aprovação ou no cancelamento. A execução do pagamento pode pertencer a outro processo. Deixar essa fronteira explícita ajuda a avaliar uma mudança sem incluir responsabilidades que pertencem a outro time.
O histórico de uma solicitação e a documentação do processo cumprem papéis diferentes. O primeiro ajuda a entender um caso; a segunda explica a lógica que deve orientar os casos do mesmo processo.
Onde manter as informações do processo
Mantenha a documentação final do processo identificável na descrição do Pipe. Esse é o ponto de referência para quem precisa entender o propósito do fluxo e saber quem responde por ele.
Na descrição, registre o objetivo, um resumo do que acontece nas etapas e o papel responsável pelo processo. Use as descrições de fase para as orientações específicas de cada etapa. Quando as regras e dependências exigirem mais detalhe, organize um documento complementar e indique na descrição onde encontrar esse material.
Escolha uma referência principal para o detalhamento e confira se quem fará a manutenção consegue acessar o conteúdo. Inclua a data da última revisão para que o time saiba quando aquela versão foi conferida.
Para comparar o registro com a configuração atual, administradores podem usar a visualização Fluxo. Ela reúne fases, campos e automações do pipe. A justificativa das decisões de negócio e as dependências externas continuam precisando de registro próprio.
- Saiba mais: veja como consultar a estrutura do processo no Fluxo.
Como descrever o trabalho de cada fase
Na descrição de cada fase, combine prazo acordado, papel responsável e uma orientação breve sobre o trabalho esperado. Acrescente o critério que permite seguir adiante e o caminho para situações que exigem ajuste.
No exemplo de compras, a descrição da fase Aguardando aprovação poderia orientar: “Responsável: gestor da área solicitante. Prazo acordado: dois dias úteis. Conferir a justificativa e o valor solicitado. Registrar a decisão antes de seguir. Se faltar informação, encaminhar para Ajuste pendente pelo caminho previsto no processo”. O prazo e os papéis são ilustrativos e devem refletir o acordo da empresa.
Escrever um prazo na descrição não configura um alerta de SLA. Da mesma forma, citar um papel responsável não atribui automaticamente os cards. O texto e a configuração precisam refletir o mesmo acordo.
Para tornar as etapas reconhecíveis, use os mesmos nomes na documentação e no pipe. Se as cores indicam responsabilidade no seu processo, explique também essa convenção. Aprofunde esses critérios em boas práticas para organizar e nomear fases.
Como relacionar regras e campos às dependências
Antes de registrar uma regra, escreva a decisão de negócio que ela representa. Depois, relacione o cenário que a aciona, as condições avaliadas, a ação esperada e os campos ou destinos envolvidos.
Na aprovação de compras, registre de onde vem o valor analisado, qual critério vigente determina a aprovação e quem pode autorizar uma mudança nesse critério. Indique onde localizar a configuração correspondente. Assim, a próxima revisão parte da intenção da regra e chega aos elementos que precisam ser conferidos.
Use nomes consistentes. Para identificar uma automação, o padrão combina fase de gatilho, cenário, condição quando necessária e ação. Para condicionais, o nome deve ajudar a reconhecer se a regra exibe ou esconde um campo e em qual situação. Uma condicional controla a exibição; uma automação executa uma ação a partir de um evento. Registre separadamente o papel de cada uma.
Para campos que sustentam regras, anote finalidade, origem da informação e dependências. Inclua o identificador técnico quando ele for necessário à pessoa que mantém a integração. Isso é especialmente útil para campos ocultos ou auxiliares, cuja função pode não aparecer na rotina de preenchimento.
Ao usar os prefixos [Auxiliar], [Integração] ou [Inativo], explique na descrição do campo por que ele existe e o que depende dele. Mantenha a orientação “Não deletar” quando houver necessidade de preservação. Essa anotação comunica um cuidado; ela não bloqueia tecnicamente a exclusão.
Registre também os retornos de ajuste: quem recebe o card, quais informações precisam ser preservadas antes de uma limpeza e como o trabalho volta ao caminho principal. Para aprovações e outras transições críticas, documente qual mecanismo controla a movimentação e quais condições precisam estar completas antes do acionamento.
O que registrar sobre conexões e outros participantes
Quando o processo se conecta a outros pipes, databases ou sistemas, registre a origem e o destino dos dados, a finalidade da troca e quem mantém cada parte. Inclua onde consultar a configuração da conexão e qual time deve participar de uma alteração.
Se houver uma integração autenticada por conta de serviço, identifique a conta por referência e seu responsável. Planeje a revisão de conexões antigas quando houver mudança de responsabilidade ou de sistema. Senhas e tokens devem permanecer no local seguro definido pela empresa, fora da documentação do processo.
Quando houver Agentes de IA, documente seu contexto, os dados de entrada, a ação e a saída esperada. Registre a divisão de responsabilidades entre agentes e pessoas, incluindo quem avalia exceções conforme o processo da empresa.
Complete o registro com os canais de participação: quem trabalha no pipe, quem responde por formulário ou Interface e quem pode fazer manutenção. Se houver comunicações por email, identifique os templates envolvidos e sua finalidade. Para regras de prazo, registre a referência de fuso horário adotada.
Você não precisa acrescentar recursos ao processo para preencher a documentação. Registre as dependências que existem e explique o que a empresa precisa preservar quando algo mudar.
Como atualizar a documentação após uma mudança
Combine quem revisa o registro e quais mudanças exigem atualização. Alterações em fases, campos, critérios de aprovação, conexões, responsáveis, canais de acesso e prazos são bons momentos para conferir se a documentação continua representando o processo.
Mantenha um registro curto com data, alteração, motivo, dependências conferidas, pessoa responsável pela revisão e teste realizado. No exemplo de compras, mudar o critério de aprovação exige revisar a explicação da regra e os elementos que usam esse critério, além da configuração correspondente.
Inclua no teste um cenário que segue adiante e outro que precisa retornar para ajuste, quando esses caminhos existirem. Atualize também capturas de tela ou diagramas afetados. Para conferir a clareza, peça a outra pessoa que use o material para localizar a regra e explicar o impacto da mudança.
Para aprofundar a relação entre mapeamento, responsabilidades e implementação, avance para a Certificação de Implementação de Processos da Pipefy Academy. O acesso às aulas requer login ou cadastro.
Por onde começar no seu processo
Escolha um pipe que já está em operação e uma mudança que o time espera fazer. Use estas perguntas para organizar a primeira versão do registro:
- Qual é o objetivo do processo, onde ele começa e quando termina?
- Quem responde pelo processo e quem realiza sua manutenção?
- O que cada fase espera receber e entregar, com qual responsável e prazo?
- Quais regras, campos e conexões sustentam a decisão que será alterada?
- O que acontece nos ajustes e nas exceções?
- Quando o registro foi revisado e como o funcionamento foi conferido?
Comece pela descrição do Pipe, complete uma fase e detalhe uma regra relevante. Depois, amplie o registro conforme as próximas manutenções. O critério de qualidade é conseguir encontrar a informação necessária para decidir a mudança com contexto.
Antes de avançar, confirme que você entende:
☐ A descrição do Pipe apresenta o propósito e o responsável pelo processo e orienta onde encontrar os detalhes.
☐ As descrições de fase explicam o trabalho, enquanto configurações próprias definem atribuições e alertas.
☐ Uma mudança exige conferir as regras e dependências relacionadas e atualizar o registro.
☐ Outra pessoa consegue localizar uma regra e explicar o que precisa ser revisado antes de fazer uma alteração.
Pronto para preparar a próxima mudança? → Confira a estrutura atual do processo no Fluxo e compare com o que você documentou.
