---
title: "Dynamic Form LLM Rule Authoring Guide"
slug: "dynamic-form-llm-rule-authoring-guide"
description: "Guia operacional para criar, explicar, revisar e aplicar regras de Dynamic Form com apoio de LLM."
doc_type: "guide"
document_kind: "host-guide"
category: "architecture"
audience:
  - "business-analyst"
  - "frontend"
  - "host"
  - "platform-team"
  - "llm-agent"
level: "intermediate"
status: "active"
owner: "praxis-ui"
tags:
  - "dynamic-form"
  - "rules"
  - "llm"
  - "json-logic"
  - "governance"
toc: true
sidebar: true
reading_time: "10 min"
last_updated: "2026-04-22"
source_of_truth:
  - "projects/praxis-dynamic-form/docs/dynamic-form-rules-authoring-plan.md"
  - "projects/praxis-dynamic-form/src/lib/ai/dynamic-form-rule-authoring-context.ts"
  - "projects/praxis-dynamic-form/src/lib/ai/form-ai-capabilities.ts"
  - "projects/praxis-dynamic-form/src/lib/utils/rule-authoring-diagnostics.ts"
  - "projects/praxis-dynamic-form/src/lib/services/form-rules.service.ts"
  - "projects/praxis-core/src/lib/models/form/rule-property.schema.ts"
---

# Dynamic Form LLM Rule Authoring Guide

Este guia define como um analista, host corporativo ou agente LLM deve pedir,
gerar, explicar, revisar e aplicar regras em `praxis-dynamic-form`.

O objetivo e tirar a regra do improviso. A LLM nao deve "adivinhar codigo"; ela
deve operar sobre o vocabulario autoral publicado pelo componente:

- `formRules` e o contrato executavel.
- `formRulesState` e estado interno do builder visual.
- `fieldMetadata[].name` identifica campos de negocio.
- `sections[].rows[].columns[].items[]` identifica layout canonico.
- `RULE_PROPERTY_SCHEMA` define quais propriedades cada alvo aceita.
- `rule-authoring-diagnostics` e `ruleDiagnosticsChange` fecham o ciclo de
  validacao e explicacao.

## Contrato de responsabilidade

| Papel | Pode fazer | Nao deve fazer |
| --- | --- | --- |
| Analista | Descrever intencao, revisar impacto, aceitar ou rejeitar sugestao. | Editar `formRulesState` manualmente. |
| LLM | Gerar proposta em `formRules`, explicar impacto e corrigir diagnostics. | Escrever JS, handler, funcao ou regra fora de Json Logic. |
| Editor | Validar alvo, condicao, propriedades e round-trip visual. | Aplicar regra invalida silenciosamente. |
| Runtime | Aplicar somente propriedades saneadas e emitir diagnostics. | Criar campos, controles ou payload a partir de visual block. |

## Contexto minimo que a LLM precisa receber

A LLM nao precisa analisar codigo em runtime. Ela precisa receber um pacote de
conhecimento serializado pelo host/editor:

```json
{
  "component": "praxis-dynamic-form",
  "capabilityCatalogVersion": "v1.11",
  "fields": [
    { "name": "tipoContrato", "label": "Tipo de contrato", "type": "select" },
    { "name": "dataFim", "label": "Data fim", "type": "date" }
  ],
  "targets": {
    "field": ["tipoContrato", "dataFim"],
    "section": ["dados-contratuais"],
    "action": ["submit", "cancel"],
    "visualBlock": ["aviso-lgpd"]
  },
  "allowedRuleProperties": {
    "field": ["visible", "required", "disabled", "readonly", "label", "hint"],
    "visualBlock": ["visible", "hidden", "text", "title", "message", "rootClassName"]
  },
  "visualBlockNodes": {
    "aviso-lgpd": [
      { "id": "title", "label": "Aviso LGPD", "kind": "card", "roles": ["title"] },
      { "id": "message", "label": "Aviso", "kind": "text", "roles": ["text", "message"] }
    ]
  },
  "existingRules": [],
  "diagnostics": []
}
```

Esse pacote deve ser derivado de `FormConfig`, do catalogo de capacidades e dos
diagnostics atuais. Ele e o "mapa semantico operacional" do formulario.

No runtime/editor, use `buildDynamicFormRuleAuthoringContext(config)` para
montar esse pacote de forma canonica. A funcao publica:

- remove campos `formHidden` dos alvos de regra;
- coleta campos, secoes, linhas, colunas, actions e visual blocks;
- publica `allowedRuleProperties` a partir de `RULE_PROPERTY_SCHEMA`;
- publica `visualBlockNodes` com os nos editaveis de cada rich content block
  quando regras puderem alterar `text`, `title` ou `message`;
- inclui `existingRules` e `diagnostics`;
- carrega guardrails permanentes para a LLM, incluindo a regra de que
  `formRulesState` e gerado apenas por internals Praxis apos revisao humana.

## Prompt recomendado para criar regra

Use pedidos com intencao, alvo, condicao, efeito e criterio de aceite:

```text
Crie uma regra para o formulario de funcionario.

Intencao: quando tipoContrato for "temporario", o campo dataFim deve ficar
obrigatorio e visivel. Quando nao for temporario, dataFim deve ficar opcional.

Use somente JSON Logic canonico.
Use somente alvos existentes no target catalog.
Para valores calculados de campos, use somente envelope fechado
`{ "expression": <JsonLogic> }` ou `{ "literal": <valor> }`.
Nao misture `literal` e `expression` nem adicione chaves extras ao envelope.
Nao altere formRulesState.
Marque metadata.origin como "llm" e metadata.reviewStatus como "pending".
Explique o impacto antes de aplicar.
```

Resposta esperada da LLM:

```json
{
  "formRules": [
    {
      "id": "rule-data-fim-contrato-temporario",
      "name": "Data fim obrigatoria para contrato temporario",
      "description": "Exige data fim quando o contrato do funcionario for temporario.",
      "metadata": {
        "origin": "llm",
        "reviewStatus": "pending"
      },
      "targetType": "field",
      "targets": ["dataFim"],
      "effect": {
        "condition": {
          "==": [{ "var": "tipoContrato" }, "temporario"]
        },
        "properties": {
          "visible": true,
          "required": true
        },
        "propertiesWhenFalse": {
          "required": false
        }
      }
    }
  ]
}
```

## Prompt para regra LGPD

```text
Crie uma regra LGPD para o formulario.

Quando o campo consentimentoLgpd for false, o botao submit deve ficar
desabilitado e o bloco visual aviso-lgpd deve mostrar a mensagem:
"Aceite o termo de privacidade para continuar."

Use targetType "action" para submit e "visualBlock" para aviso-lgpd.
Nao coloque aviso-lgpd em fieldMetadata.
Nao crie FormControl para aviso-lgpd.
Use JSON Logic canonico.
Deixe a sugestao pendente de revisao humana.
```

Resposta esperada:

```json
{
  "formRules": [
    {
      "id": "rule-submit-bloqueado-sem-lgpd",
      "name": "Bloquear envio sem consentimento LGPD",
      "metadata": {
        "origin": "llm",
        "reviewStatus": "pending"
      },
      "targetType": "action",
      "targets": ["submit"],
      "effect": {
        "condition": { "===": [{ "var": "consentimentoLgpd" }, false] },
        "properties": { "disabled": true },
        "propertiesWhenFalse": { "disabled": false }
      }
    },
    {
      "id": "rule-aviso-lgpd-sem-consentimento",
      "name": "Aviso LGPD sem consentimento",
      "metadata": {
        "origin": "llm",
        "reviewStatus": "pending"
      },
      "targetType": "visualBlock",
      "targets": ["aviso-lgpd"],
      "effect": {
        "condition": { "===": [{ "var": "consentimentoLgpd" }, false] },
        "properties": {
          "visible": true,
          "message": "Aceite o termo de privacidade para continuar."
        },
        "propertiesWhenFalse": {
          "visible": false
        }
      }
    }
  ]
}
```

## Prompt para explicar regra existente

```text
Explique esta regra para um analista de negocio.

Responda com:
1. Quando ela dispara.
2. O que ela altera.
3. Se afeta payload ou apenas UI.
4. Riscos de negocio.
5. Diagnostics que precisam correcao.
```

A explicacao deve traduzir Json Logic para linguagem de dominio e citar os
alvos por label quando o contexto tiver label disponivel.

## Prompt para corrigir diagnostics

```text
Corrija as regras abaixo usando os diagnostics do editor.

Nao mude a intencao de negocio.
Se um alvo nao existir, proponha o alvo existente mais proximo e explique.
Se uma propriedade for rejeitada pelo schema, substitua por uma propriedade
permitida ou remova com justificativa.
Mantenha metadata.reviewStatus como "pending".
```

Mapeamento operacional:

| Diagnostic | Acao esperada da LLM |
| --- | --- |
| `missing-targets` | Pedir ou preencher `targets`. |
| `field-target-not-found` | Trocar por `fieldMetadata[].name` existente. |
| `target-not-found` | Trocar por alvo existente no mesmo `targetType`. |
| `invalid-condition` | Reescrever como Json Logic canonico. |
| `invalid-value-expression` | Corrigir `effect.properties.value` ou `propertiesWhenFalse.value` para Json Logic valido ou envelope fechado `{ "expression": ... }` / `{ "literal": ... }`. |
| `computed-value-iteration-limit` | Remover ciclo ou ambiguidade entre valores calculados encadeados. |
| `unsupported-property` | Usar propriedade permitida por `RULE_PROPERTY_SCHEMA`. |
| `unsupported-target-type` | Escolher um `targetType` permitido. |
| `missing-effect` | Criar `effect.condition` e `effect.properties`. |
| `rule-evaluation-error` | Simplificar condicao e remover operadores nao suportados. |

Quando o diagnostic envolver apenas propriedade rejeitada, valor invalido ou
valor parcialmente saneado, o editor tambem pode aplicar a acao deterministica
`Corrigir`. Essa acao usa o mesmo sanitizer central do runtime, remove ou
coage propriedades conforme `RULE_PROPERTY_SCHEMA` e regenera `formRulesState`.
Use LLM quando a correcao exigir decisao semantica de dominio, por exemplo
trocar uma propriedade inexistente por outra intencionalmente equivalente ou
explicar por que uma regra deve ser removida.

## Fluxo de aplicacao seguro

1. Host/editor monta o pacote de contexto.
2. LLM gera uma proposta por operacao autoral ou em `formRules`.
   Para regra de negocio, politica, elegibilidade, validacao, compliance ou
   decisao compartilhada, use `domain-rules`/`shared_rule_authoring` antes de
   materializar `form_config`. Para uma projecao visual derivada de decisao ja
   governada, aceite `operationId: "rule.visualBlockGuidance.add"` com
   `type: "visualBlockGuidance"`, `targetType: "visualBlock"`,
   `context: "notification"` e metadata pendente.
3. Compilador/adapter rejeita qualquer tentativa de gravar `formRulesState`.
4. Editor valida alvos, condicao e propriedades.
5. Editor mostra diff e impacto para o analista.
6. Analista aceita, edita ou rejeita.
7. Ao aceitar, editor marca `metadata.reviewStatus: "accepted"`.
8. Editor tenta gerar `formRulesState` por conversor interno.
9. Runtime aplica regra e emite `ruleDiagnosticsChange` se houver problema.

## Guardrails permanentes

- Nunca persistir codigo executavel em regra.
- Nunca editar `formRulesState` diretamente por LLM.
- Nunca tentar contornar essa regra no patch final: `compileAiResponse` e
  `applyPatch` tambem rejeitam escrita direta em `formRulesState`.
- Nunca materializar regra visual direto no estado do builder. O editor preserva
  semantica de `formRules[].type` usando `config.ruleType` internamente no
  round-trip.
- Nunca criar alvo que nao exista no mapa de targets.
- Nunca usar propriedade fora do schema permitido.
- Nunca tratar `visualBlock` como campo.
- Para `visualBlock` com varios nos editaveis, usar o node id correspondente em
  `textNodeId`, `titleNodeId` ou `messageNodeId`.
- Nunca esconder erro de regra: todo descarte deve virar diagnostic ou status.
- Regras LLM entram como `pending`; aceite humano e uma decisao explicita.

## Sinal de prontidao para runtime

Uma regra esta pronta para runtime quando:

- todos os targets existem;
- a condicao e Json Logic valida;
- as propriedades passam pelo whitelist;
- o impacto foi explicado;
- o preview true/false foi revisado;
- a origem/revisao esta coerente;
- o runtime nao emite diagnostic apos aplicar.
