Como Escrever Arquivos de Prompt

Estrutura Geral do Arquivo

Um arquivo de prompt começa com um bloco de front matter YAML (delimitado por ---) que contém os metadados do prompt. O uuid é o único campo obrigatório. Em seguida, as seções de conteúdo são delimitadas por títulos de nível 1 (# NOME DA SEÇÃO).

---
<metadados em formato YAML>
---

# SYSTEM PROMPT
<instruções de sistema para o modelo de IA>

# PROMPT
<o texto do prompt que será enviado ao modelo>

# JSON SCHEMA
<esquema JSON da resposta esperada (opcional)>

# FORMAT
<instruções adicionais de formato (opcional)>

Front Matter

Contém os metadados do prompt em formato YAML, delimitado por --- no início e no fim. Controla visibilidade, filtros, ordenação e integração com outros prompts.

Exemplo completo

---
uuid: 8c8bac70-1aaa-46fc-90fc-328b19906307
name: Voto
sort: 3
share: publico
target: processo
piece_strategy: mais-relevantes-segunda-instancia
profile: eficiente
instance: [segundo-grau]
matter: [civel]
scope: [justica-federal]
author: Nome do Autor
group:
  slug: minutas-segunda-instancia
  title: Minutas de Segunda Instância
context:
  action: minuta-editar
  instance: segundo-grau
predecessors:
  - path: pedidos-fundamentacoes-e-dispositivos
successors:
  - path: chat
---

Referência de Campos

uuid (obrigatório)

Identificador único e permanente do prompt. Nunca altere este valor após o arquivo ser publicado — ele é usado para rastrear o histórico de versões e manter as referências de workflow.

• Gere um UUID v4 em qualquer gerador online (ex: uuidgenerator.net) ou com o comando uuidgen no terminal.
• Formato: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
• Arquivos sem uuid são ignorados pela sincronização (útil para arquivos auxiliares/snippets).

name (opcional)

Nome de exibição do prompt na interface. Se omitido, o sistema usa o nome do arquivo (sem extensão e com formatação automática).

name: Minuta de Sentença

sort (opcional)

Número inteiro que controla a ordem de exibição na lista. Números menores aparecem primeiro. Prompts sem sort definido aparecem no final, em ordem alfabética.

sort: 3

author (opcional)

Texto livre com o nome do autor ou equipe responsável pelo prompt. Sugerimos incluir a sigla do órgão, conforme exemplo abaixo.

author: Caroline Tauk/JFRJ

share (opcional)

Controla a visibilidade do prompt para outros usuários. Valor padrão: padrao.

share: publico

oculto é gerenciado automaticamente pelo sistema e não deve ser usado em prompts criados por usuários. Ele aparece no formulário de edição como informação somente-leitura quando já está definido.

target (opcional)

Define o tipo de entrada sobre o qual o prompt opera. Valor padrão: processo.

target: processo

piece_strategy (opcional)

Define qual estratégia de seleção de peças do processo será usada. Relevante apenas quando target: processo.

piece_strategy: mais-relevantes-segunda-instancia

profile(opcional)

Define o perfil de modelo a ser usado por este prompt. O front matter aceita apenas os perfis abstratos abaixo, nunca nomes concretos de modelos como gemini-2.5-pro ou gpt-4.1. Use o perfil premium só em último caso, pois normalmente é muito mais caro que os demais. Utilize o perfil eficiente quando não há necessidade de raciocínio profundo, mas se quer velocidade e baixo custo. O perfil versatil representa modelos com boa capacidade de raciocínio e custo razoável. O perfil padrao é o modelo base configurado pelo tribunal.

Perfis aceitos:

Valores legados (alto, medio, baixo e sufixos audio) não são mais aceitos.

instance (opcional)

Lista de instâncias para as quais o prompt é aplicável. Filtra o prompt na interface conforme o processo selecionado.

Aceita um ou mais valores em lista YAML:

instance: [segundo-grau]

instance: [primeiro-grau, segundo-grau]

scope (opcional)

Lista de ramos da Justiça para as quais o prompt é aplicável.

scope: [justica-federal, justica-estadual]

matter (opcional)

Lista de matérias jurídicas para as quais o prompt é aplicável.

matter: [civel]

group (opcional)

Agrupa prompts relacionados em uma seção visual na interface. Todos os prompts com o mesmo slug aparecem juntos sob o mesmo title.

group:
  slug: admissibilidade-de-recursos
  title: Admissibilidade de Recursos

• slug: identificador do grupo (letras minúsculas, hífens, sem acentos)
• title: texto exibido como cabeçalho do grupo na interface

context (opcional)

Controla quando o prompt aparece automaticamente no painel lateral (Sidekick), baseado no contexto da tela atual do usuário. Esta opção deve ser usada para guiar a integração da Apoia ao sistema processual (eproc/PJe) através do IntelliAgent.

context:
  action: minuta-editar
  instance: segundo-grau

Ambos os subcampos são opcionais — você pode especificar apenas action, apenas instance, ou ambos.

Exemplo — prompt visível ao editar minutas de segundo grau:

context:
  action: minuta-editar
  instance: segundo-grau

Exemplo — prompt visível ao selecionar qualquer processo:

context:
  action: processo-selecionar

plugins (opcional)

Lista de plugins ativados para este prompt. Os plugins adicionam funcionalidades extras à execução (usados em relatórios em lote).

plugins:
  - triagem-json
  - normas

batch_report (opcional)

Indica que este prompt pode ser utilizado em relatórios de lote (Relatório de Acervo). Quando true, o prompt aparece como opção no processamento em lote de múltiplos processos.

batch_report: true

summary (opcional)

Controla se o prompt gera um resumo exibido na interface (por exemplo, o resumo de cada peça usado pelos prompts seguintes do workflow). Aceita sim ou nao.

summary: sim

editor_label (opcional)

Texto curto exibido no editor quando este prompt é selecionado como opção. Útil para diferenciar prompts com nomes semelhantes no contexto do editor.

editor_label: Minuta de Voto

piece_descr (opcional)

Lista de tipos de peça processual associados a este prompt. Tem papel duplo — define a seleção padrão e filtra as peças que o prompt recebe —, porém só tem efeito quando piece_strategy: tipos-especificos (o formulário só expõe o campo nessa estratégia). Os valores são as chaves do enum de tipos de peça, podendo ser escritas na forma canônica ou com hífens (slug).

A semântica é por presença:

• Ausente = sem filtro: o prompt recebe todas as peças selecionadas pela estratégia.
• Presente, mesmo com lista vazia = só entram peças dos tipos listados. A lista vazia ([]) significa que o prompt não recebe peças — útil para passos de workflow que usam apenas os resultados de prompts anteriores (ex.: uma busca de jurisprudência sobre os pedidos já extraídos).

Essa regra vale para o prompt raiz e para os steps de workflow. O casamento é feito sobre o tipo efetivo da peça, respeitando reclassificações. A sincronização preserva listas vazias declaradas e descarta valores inválidos.

Exemplos de valores aceitos: peticao-inicial, contestacao, sentenca, apelacao, recurso-especial, etc.

piece_descr:
  - peticao-inicial
  - contestacao
  - sentenca

# prompt que não recebe peças, apenas resultados anteriores
piece_strategy: tipos-especificos
piece_descr: []

predecessors (opcional)

Lista de prompts que devem ser executados antes deste. O sistema usa essa informação para montar o encadeamento do workflow (veja Workflows de Prompts).

Cada item pode referenciar outro prompt por path (slug do arquivo, sem extensão) ou por uuid:

predecessors:
  - path: pedidos-fundamentacoes-e-dispositivos
  - path: pesquisa-de-temas

predecessors:
  - uuid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d

O path é o nome do arquivo sem extensão, relativo ao diretório raiz que está sendo importado. Para arquivos em subpastas, use o caminho relativo:

predecessors:
  - path: admissibilidade-de-recurso/juizo-viabilidade-recurso

Campos adicionais opcionais por predecessor:

successors (opcional)

Lista de prompts sugeridos como próximo passo após a execução deste. Aparecem como sugestão ao usuário ao final da geração.

successors:
  - path: chat
  - path: voto

A sintaxe é idêntica à de predecessors.

Seção # SYSTEM PROMPT

Instrução de sistema enviada ao modelo de IA antes do prompt do usuário. Define o papel, tom, restrições e expertise esperados do modelo.

# SYSTEM PROMPT

Você é um assistente de magistrado altamente experiente, especialista em Direito Civil e Processual Civil.
Sua principal habilidade é redigir minutas de votos claras, bem fundamentadas e tecnicamente impecáveis.

{{salvaguardas}}

Seção # PROMPT

O texto principal do prompt, enviado como mensagem do usuário ao modelo. Suporta Markdown e variáveis de template.

# PROMPT

Com base nas peças do processo abaixo, elabore um resumo dos principais pedidos da parte autora:

{{textos}}

Variáveis de template

Seção # JSON SCHEMA (opcional)

Define o esquema JSON da resposta esperada do modelo, quando o prompt deve retornar dados estruturados em vez de texto livre. O sistema usa este schema para validar e processar a resposta.

# JSON SCHEMA

{
  "type": "object",
  "properties": {
    "pedidos": {
      "type": "array",
      "items": { "type": "string" }
    }
  }
}

Seção # FORMAT (opcional)

Template Nunjucks que transforma o JSON retornado pelo modelo em texto formatado para exibição ao usuário. É necessário sempre que o prompt usa # JSON SCHEMA ou ## FIELDS, pois o JSON bruto não é exibido diretamente — ele precisa ser renderizado em Markdown, tabela ou qualquer outra estrutura legível.

Fluxo de execução:

1. O modelo retorna um JSON (validado pelo schema)
2. O sistema interpreta o # FORMAT como um template Nunjucks, passando os campos do JSON como variáveis de contexto
3. O resultado renderizado é exibido ao usuário

Sintaxe de expressões

Há duas formas de inserir o valor de um campo do JSON no template:

Use {{ }} quando quiser que o usuário identifique facilmente que aquele trecho veio da análise do modelo. Use {= =} quando o valor deve aparecer como parte natural do texto, sem marcação.

{{ campo }}             → valor do campo, com highlight
{= campo =}            → valor do campo, sem highlight
{= objeto.subcampo =}  → acesso aninhado
{= array[0] =}         → primeiro elemento

Para blocos de controle (condicionais, laços), use a sintaxe {% %} normalmente:

{% if condicao %}...{% endif %}
{% for item in lista %}...{% endfor %}
{% set mapa = { CHAVE: 'valor' } %}
```### Filtros disponíveis

Além dos filtros padrão do Nunjucks, estão disponíveis:

| Filtro | Descrição |
|--------|-----------|
| `sortByDate(campo, ordem)` | Ordena um array por um campo de data no formato `DD/MM/YYYY`. `ordem` pode ser `'asc'` (padrão) ou `'desc'` |
| `blockquoteLines` | Escapa o texto e formata cada linha com `>` (blockquote Markdown) |
| `limpaHtml` | Limpa HTML desnecessário e embute HTML vivo sem escape (útil para campos JSON e resultados de ferramentas) |

### Funções de data disponíveis

As seguintes funções ficam disponíveis no contexto do template:

| Função | Descrição |
|--------|-----------|
| `date('DD/MM/YYYY')` | Converte uma string de data |
| `dateAddDays(data, n)` | Adiciona `n` dias a uma data |
| `dateAddMonths(data, n)` | Adiciona `n` meses a uma data |

### Marcadores de referência no `# FORMAT`

Trechos do FORMAT podem ser marcados como **referenciáveis** por prompts sucessores do workflow, usando pares de comentários HTML no namespace `apoia:`:

```
<!--apoia:ementa-->...conteúdo...<!--/apoia:ementa-->
```

* Os ids são únicos por prompt (letras, números, `.`, `_`, `-`), podem ser aninhados e os comentários são invisíveis no navegador.
* Um prompt sucessor pode copiar o trecho por referência (veja campos `Rf_` e o comando `copiar` abaixo) ou citá-lo com `step:<slug>#<id>`.
* Mecanismo **opt-in**: sem marcadores, nada é referenciável. Marcador não fechado é ignorado.

### Exemplos

**Lista numerada simples** (arquivo `indice.md`):

```nunjucks
# FORMAT

{% for d in indice %}
{{ loop.index }}. **{= d.descr =}** (evento {= d.event =}{% if d.label %}, {= d.label =}{% endif %}{% if d.pages %}, pág. {= d.pages =}{% endif %})
{% endfor %}
```**Tabela Markdown** (arquivo `linha-do-tempo-fatica.md`):

```nunjucks
# FORMAT

{% if Linha_Do_Tempo | length %}
| Data | Agente | Fato | Peça |
|------|--------|------|------|
{% for fato in Linha_Do_Tempo %}| {= fato.Tx_Data_Do_Fato =} | {= fato.Tx_Agente or "" =} | {= fato.Tx_Fato_Resumido =} | {= fato.Tx_Peca =} |
{% endfor %}{% endif %}
```**Mapeamento de enum para texto legível** (arquivo `pedidos-fundamentacoes-e-dispositivos.md`):

```nunjucks
# FORMAT

{% set tipos = {
    CONDENAR_A_PAGAR: 'Condenar a Pagar',
    CONDENAR_A_FAZER: 'Condenar a Fazer',
    ANULAR_RELACAO_JURIDICA: 'Anular Relação Jurídica'
} %}
{% for d in pedidos %}{{ loop.index }}. {{ tipos[d.tipoDePedido] }}: {= d.texto =}
{% endfor %}
```**Tabela com ordenação por data** (arquivo `prev-ppp.md`):

```nunjucks
# FORMAT

{% if PPP | length %}
| Início | Fim | Empresa | Profissão |
|--------|-----|---------|-----------|
{% for p in PPP | sortByDate('Dt_Inicio') %}| {= p.Dt_Inicio =} | {= p.Dt_Fim =} | {= p.Tx_Empresa =} | {= p.Tx_Profissao =} |
{% endfor %}{% endif %}

Importante: O # FORMAT só é executado quando a resposta do modelo começa com { (ou seja, é JSON). Se o modelo retornar texto livre, o FORMAT é ignorado e o texto bruto é exibido diretamente.

Seção ## FIELDS e ## FIELDS READONLY (opcional)

O recurso auto-json permite definir a estrutura dos campos de extração diretamente no corpo do # PROMPT, usando headings Markdown como definição de schema. O sistema lê esses headings, gera automaticamente o # JSON SCHEMA correspondente e injeta o boilerplate de instruções de preenchimento para o modelo.

O resultado é que o autor do prompt escreve apenas uma vez — as descrições dos campos servem simultaneamente como instrução para o modelo e como definição do schema JSON.

Diferença entre os dois títulos:

Todo schema ganha automaticamente um campo técnico errorMessage: se o modelo o preencher (por exemplo, para reportar que não encontrou os dados), o restante do JSON é descartado e o erro é tratado pelo canal normal da aplicação.

Estrutura dos headings

Os headings de nível H3 a H6 abaixo do marcador definem a hierarquia do JSON. O nível hierárquico determina o tipo:

O tipo primitivo de cada campo H6 é inferido pelo prefixo do nome:

O texto em itálico após o traço no nome do heading (### PPP[] - Perfis Profissiográficos) vira o rótulo de exibição; o texto antes do traço vira o nome do campo no JSON.

Modificadores de campo

No nome do heading de campos primitivos (H6) e de arrays primitivos, podem ser usados modificadores entre parênteses, combináveis:

Arrays declarados com [] aceitam lista vazia por padrão.

Exemplo — campo simples e array

# PROMPT

Extraia as informações do processo abaixo.

## FIELDS

### Processo - Dados do Processo

###### Tx_Numero - Número do Processo
- Número do processo no formato CNJ

###### Dt_Distribuicao - Data de Distribuição
- Data de distribuição no formato dd/mm/yyyy

### Partes[] - Partes do Processo

###### Tx_Nome - Nome
- Nome completo da parte

###### Tx_Polo - Polo
- "Ativo" ou "Passivo"

Isso gera automaticamente o JSON schema equivalente a:

{
  "Processo": {
    "Tx_Numero": "...",
    "Dt_Distribuicao": "..."
  },
  "Partes": [
    { "Tx_Nome": "...", "Tx_Polo": "..." }
  ]
}

Exemplo real — array com objeto agrupador (arquivo prev-ppp.md)

## FIELDS

### Docs_Analisados - Documentos Analisados

###### Nr_PPPs - Número de PPPs
- Número de PPPs extraídos dos documentos

### PPP[] - Perfis Profissiográficos Previdenciários
- Extraia as informações dos textos dos PPPs nos autos
- Se não houver PPPs, responda com um array vazio.

###### Ev_Event - Evento
- Número do evento processual

###### Dt_Inicio - Início do Período
- Data de início conforme consta no PPP ou "?" se não tiver certeza.

###### Tx_Empresa - Empresa
- Nome da empresa

###### Lo_EPI_Eficaz - EPI Eficaz
- true se o EPI foi considerado eficaz no PPP

Exemplo com hierarquia de arrays (pedidos-viabilidade-recurso.md)

Arrays podem conter sub-arrays usando H4 e H5:

## FIELDS READONLY

### Pedidos[] - Lista de Pedidos

#### Tx_Texto - Texto do Pedido
- Descrição concisa do pedido

##### Argumentos[] - Lista de Argumentos

###### Tx_Texto - Texto do Argumento
- Descrição concisa do argumento

###### Tx_Trecho - Trecho Comprobatório
- Trecho exato do texto onde o argumento aparece

Regras de aninhamento

• H3 na raiz → campo ou array de nível raiz
• H4 dentro de H3 → subcampo ou subarray
• H5 dentro de H4 → subsubcampo ou subsubarray
• H6 é sempre campo primitivo — não pode ter filhos nem ser array
• Nomes de campos no mesmo nível devem ser únicos
• Descrições (linhas de texto após o heading) tornam-se instrução para o modelo e não entram no schema JSON

O ## FIELDS é usado dentro da seção # PROMPT. O sistema injeta automaticamente o boilerplate de instruções gerais (tipos de dados, formatos de data, regras de preenchimento) antes do título, de modo que o autor não precisa repeti-las.

Campos de referência (Rf_)

Quando o valor de um campo deve ser copiado integralmente de um resultado anterior (de ferramenta ou de prompt predecessor) em vez de redigitado pela IA, use o prefixo Rf_. O modelo emite apenas uma referência e a Apoia materializa o valor exato — uma cópia literal por construção, sem risco de alucinação.

• Fontes de referência: <toolCallId>#<caminho>; <nomeDaFerramenta>#<n>#<caminho> (n-ésima execução); <nomeDaFerramenta>#<caminho> (última execução da ferramenta — forma recomendada); step:<slug>#<id> (resultado de prompt anterior do fluxo, onde <id> é o marcador <!--apoia:id--> do FORMAT).
• O <caminho> é um JSON Pointer (RFC 6901); em arrays com propriedade id, prefira id:<valor> ao índice.
• Regras: apenas cópia exata (sínteses vão em campos Tx_/Tg_); referência inválida é erro (registrado no painel de erros com a resposta crua); não combinável com (opções); no formulário editável, o usuário edita o valor mantendo a referência como procedência; no FORMAT, o valor é acessado diretamente.

Comando de cópia integral (copiar)

Em prompts de saída textual (sem FIELDS) cuja prosa precisa inserir trecho literal de um resultado anterior, o modelo pode emitir o comentário <!--apoia:copiar:<id>--> (forma curta — usa o último resultado que tiver o marcador) ou <!--apoia:copiar:step:<slug>#<id>--> (forma qualificada). A Apoia substitui o comando pelo conteúdo exato do trecho referenciado, reproduzindo os marcadores originais — o resultado permanece re-referenciável por prompts sucessores. Referência inválida é erro fatal (a resposta é substituída por ERRO: ...). A instrução para o modelo é autoral: inclua no PROMPT/SYSTEM PROMPT o parágrafo canônico de instrução documentado na documentação interna do repositório.

Exemplos Completos

Prompt simples de análise de processo

---
uuid: 9c8f98fb-0679-4f2a-9722-91c2e1b35600
name: Resumos e Análise
sort: 2
piece_strategy: mais-relevantes
context:
  action: processo-selecionar
successors:
  - path: chat
---

# SYSTEM PROMPT

Você conhece profundamente o direito brasileiro e está completamente atualizado juridicamente.
Você sempre presta informações precisas, objetivas e confiáveis.
Você não está autorizado a criar nada; suas respostas devem ser baseadas apenas no texto fornecido.

# PROMPT

Leia com atenção os textos a seguir e resuma as informações mais importantes:

{{textos}}

Prompt de segunda instância com workflow completo

---
uuid: 8c8bac70-1aaa-46fc-90fc-328b19906307
name: Voto
sort: 3
piece_strategy: mais-relevantes-segunda-instancia
instance: [segundo-grau]
context:
  action: minuta-editar
  instance: segundo-grau
predecessors:
  - path: pedidos-fundamentacoes-e-dispositivos
successors:
  - path: chat
---

# SYSTEM PROMPT

Você é um assistente de magistrado altamente experiente, especialista em Direito Civil e Processual Civil.

# PROMPT

Considerando as informações do processo em questão, gere uma minuta completa de voto de mérito.

{{textos}}

Prompt com grupo e share restrito

---
uuid: a1b2c3d4-e5f6-4a7b-8c9d-0e1f2a3b4c5d
name: Minuta de Decisão de Viabilidade de Recurso Especial
sort: 3
share: beta-teste
piece_strategy: viabilidade-recurso-especial
group:
  slug: admissibilidade-de-recursos
  title: Admissibilidade de Recursos
predecessors:
  - path: pedidos-viabilidade-recurso
  - path: pesquisa-de-temas
  - path: juizo-viabilidade-recurso
successors:
  - path: chat
---

# SYSTEM PROMPT

...

# PROMPT

...

Prompt de subpasta com scope específico

---
uuid: b01fed52-428c-47b1-aa7b-228be3b63ba4
name: Relatório de Aposentadoria Especial - Segunda Instância
sort: 1000
piece_strategy: mais-relevantes-segunda-instancia
author: Caroline Tauk/JFRJ
instance: [segundo-grau]
scope: [justica-federal]
matter: [civel]
successors:
  - path: pedidos-fundamentacoes-e-dispositivos
  - path: voto
  - path: chat
---

# SYSTEM PROMPT

...

# PROMPT

...

Boas Práticas

1. Nunca altere o uuid de um prompt já publicado. Isso quebraria as referências de workflow e o histórico de versões.
2. Use slugs legíveis ao referenciar prompts por path. O slug é o nome do arquivo sem .md e em letras minúsculas com hífens.
3. Mantenha o system prompt curto e focado. Defina papel e restrições; os detalhes da tarefa vão no # PROMPT.
4. Use {{textos}} no corpo do prompt quando o modelo precisar ler o conteúdo do processo. Sem essa variável, nenhum texto do processo será enviado.
5. Use sort para organizar. Prompts mais usados devem ter números menores (aparecem primeiro).
6. Defina instance e scope quando o prompt for específico para um tipo de tribunal ou grau — isso evita que apareça em contextos irrelevantes e melhora a experiência do usuário.
7. Use share: privado durante o desenvolvimento para que o prompt fique visível apenas para você antes de ser publicado.