.agent/workflows/adicionar-ajuda.global.md

type	name	description	scope	updatedAt
workflow	adicionar-ajuda	Adicionar ou atualizar botão de ajuda e documentação em telas (Frontend)	global	2026-06-01

Workflow: Adicionar Ajuda em Telas

Este workflow automatiza a inserção do botão de ajuda e a criação do arquivo de documentação correspondente sempre que uma tela é criada ou modificada de forma significativa.

O objetivo da ajuda é auxiliar o usuário final a compreender e utilizar corretamente a aplicação, explicando o funcionamento da tela de forma clara e objetiva.

Pré-requisitos

• O arquivo alvo deve ser um componente de interface (.tsx para React ou .vue para Vue).
• O projeto deve possuir um componente de ajuda (ex: BotaoAjuda, HelpButton ou equivalente) disponível para uso na interface.
• Caso não exista, criar um componente reutilizável que exiba o conteúdo do .ajuda.md em modal ou drawer.

Passos

1. Identificar o Componente Alvo

Determine qual arquivo representa a tela principal ou modal que está sendo criado ou editado.

• React → .tsx
• Vue → .vue

2. Verificar Existência de Ajuda

Procure por um arquivo de ajuda com o mesmo nome do componente e sufixo indicativo de ajuda (ex.: .ajuda.md) localizado na mesma pasta.

Exemplo:

TelaCadastroUsuario.tsx
TelaCadastroUsuario.ajuda.md

ou

TelaCadastroUsuario.vue
TelaCadastroUsuario.ajuda.md

3. Criar ou Atualizar o Arquivo Markdown

Se o arquivo .ajuda.md não existir, crie-o utilizando o template básico abaixo.

O conteúdo deve ser escrito pensando no usuário final, explicando de forma simples como utilizar a tela.

A documentação deve incluir, quando aplicável:

• Objetivo da tela
• Descrição dos botões
• Descrição dos campos de formulário
• Regras de preenchimento e validações
• Fluxo esperado de uso
• Contexto técnico ou legal, quando relevante para o entendimento da funcionalidade

Template inicial:

# Ajuda: [Nome da Tela]

## Objetivo da Tela

Explique de forma simples para que serve esta tela dentro do sistema.

## Botões

- **Salvar**: grava as informações preenchidas.
- **Cancelar**: descarta as alterações realizadas.
- **Excluir**: remove o registro atual do sistema.

## Campos do Formulário

- **Nome**: informe o nome completo do responsável.
- **Data de Vistoria**: data em que a vistoria foi realizada.
- **Observações**: campo livre para registrar informações adicionais.

## Fluxo de Uso

1. Preencha os campos obrigatórios.
2. Revise as informações inseridas.
3. Clique em **Salvar** para registrar os dados no sistema.

## Informações Técnicas ou Legais (quando aplicável)

Explique regras técnicas, normas ou exigências legais relacionadas à funcionalidade da tela.

4. Posicionamento do Botão de Ajuda

O botão deve ser inserido de forma consistente e não pode interferir na interface da aplicação.

Telas / Páginas

• O botão deve ficar na parte inferior esquerda da página.
• Deve respeitar espaçamento suficiente das bordas da interface.
• Não pode sobrepor nenhum componente da tela.
• Não pode ficar oculto ou sobreposto pela barra de módulos da aplicação.
• Ajustar margin, padding ou z-index quando necessário para garantir visibilidade adequada.

Modais e Diálogos

• O botão deve ficar na parte inferior esquerda do modal.
• Preferencialmente no rodapé do modal ou em um container equivalente.
• Não pode sobrepor botões ou ações do modal.
• Garantir espaçamento adequado para não interferir na usabilidade.