cadugevaerd grillme-langgraph
Esta skill não presume que todo workflow merece LangGraph. Ela trabalha em três modos:
- Gate de adequação — determina se LangGraph é justificado.
- Grilling sem LangGraph — quando o fluxo é daemon, pipeline fixo, worker, fila ou transação, produz a arquitetura direta adequada.
- Design LangGraph — somente para o subfluxo que de fato requer estado de grafo, roteamento adaptativo ou loop LLM→tools→LLM.
A entrega padrão é design + diagrama, sem código de implementação.
Fonte de referência
Leia references/padrao-langgraph.md antes de começar. Ela contém o modelo “Thinking in LangGraph”, Regra CRUE, Regra de Ouro de arestas, State-Check, fronteira determinística/não-determinística e o gate “quando não usar LangGraph”.
Fase 0 — Gate de adequação (obrigatório)
Antes de falar em nodes, faça uma pergunta por vez e investigue o que puder no projeto/documentação. Resolva:
- Caminho crítico. É daemon contínuo, captura/streaming de baixa latência, job por evento, consulta sob demanda ou processo humano longo?
- Fluxo real. Passos e destinos são conhecidos em design ou variam materialmente em runtime?
- LLM. Há ciclo imprevisível
LLM → tools → LLM, ou apenas chamada pontual de LLM/classificação? - Estado. Há estado que precisa pausar/retomar entre interações? Não é melhor representado por tabelas/eventos no banco?
- Coordenação. Há concorrência, idempotência, locks, serialização, rate limiting ou transações? Declare a fonte de verdade; não atribua essas garantias ao LangGraph.
- Falhas. Retry/checkpoint por etapa são conveniência ou razão estrutural? Filas/workers já resolvem isso?
- Alternativa mínima. Qual é a opção mais simples: função/serviço async, fila + workers, cron, banco transacional, ou um agente/tool loop?
Veredito fail-closed
Só recomende LangGraph se houver razão estrutural explícita:
✓ loop imprevisível LLM → tools → LLM;
✓ workflow adaptativo com revisão/retorno em runtime;
✓ estado durável, retomável e mais claro como grafo;
✓ subfluxo conversacional que escolhe dados/ferramentas dinamicamente.
Não use LangGraph como resposta automática a:
✗ daemon contínuo ou captura sub-segundo;
✗ pipeline fixo de ingestão/processamento;
✗ retry, rate limit, scheduling ou observabilidade;
✗ idempotência de side effect;
✗ lock, serialização ou integridade transacional entre execuções;
✗ branches determinísticas simples.
Saída do gate
Declare um veredito antes de continuar:
| Veredito | Próximo passo |
|---|---|
| SEM LANGGRAPH | Diga: “recomendo rodar o grill sem LangGraph”. Continue no modo Arquitetura Direta e use assets/template-sem-langgraph.md. Não invente State CRUE, nodes ou Mermaid de LangGraph. |
| USO PARCIAL | Separe fluxos: hot path determinístico fora; rode o grilling LangGraph somente no subfluxo justificado. Produza ambos os desenhos e a fronteira explícita. |
| LANGGRAPH JUSTIFICADO | Continue para Fase 1 e gere o design completo. |
Em qualquer veredito, explique evidências, alternativa mínima, o que LangGraph resolveria (se usado) e o que ele não resolveria.
Modo Arquitetura Direta — SEM LANGGRAPH
Quando o gate retornar SEM LANGGRAPH, continue uma pergunta por vez até fechar:
- entrada, saída e SLA/latência;
- unidade idempotente e chave de deduplicação;
- daemon/fila/worker/cron;
- fonte de verdade, transação, lock e concorrência;
- retries por classe de falha e DLQ/reprocessamento;
- observabilidade, métricas e auditoria;
- gatilho futuro que poderia justificar um subfluxo LangGraph.
Produza assets/template-sem-langgraph.md. Não chame a alternativa de “grafo simplificado”; nomeie a primitiva concreta: serviço async, worker, fila, banco, cron ou chamada de função.
Fase 1 — Grilling LangGraph
Execute somente para o escopo aprovado no gate. Faça uma pergunta por vez, com recomendação anexada, e desça cada galho antes de avançar:
- objetivo, entrada, saída/
ENDe fronteira fora do grafo; - passos discretos; mapear antes de otimizar;
- tipo: LLM, Data, Action, User-input ou Router;
- determinismo: fixo (
add_edge), roteado (Command[Literal]) ou loop de tools (agent-as-node); - agent-as-node somente para
LLM → tools → LLM; decisão pontual usa nodes explícitos; - HITL via State-Check, nunca
interrupt()como padrão; - State CRUE: apenas dados brutos; prompts nos nodes;
- falhas: retry transiente, loop recuperável, State-Check humano ou
raise; - padrão dominante: Prompt Chaining, Parallelization, Routing, Orchestrator-Worker, Evaluator-Optimizer ou Agent loop.
Antes do design, resuma em 3–5 linhas e confirme que o escopo do grafo permanece justificado.
Fase 2 — Saídas
Para LANGGRAPH JUSTIFICADO
Use assets/template-saida.md, nesta ordem:
- Parecer de adequação e fronteira com componentes fora do grafo.
- Resumo do fluxo.
- Diagrama Mermaid.
- Schema do State (CRUE).
- Tabela de nodes.
- Explicação de cada node.
- Decisões em aberto/riscos.
Para USO PARCIAL
Entregue primeiro o parecer e o desenho Arquitetura Direta do hot path. Depois gere o template LangGraph só para o subfluxo justificado. Declare a interface: evento/entrada, contrato de dados, idempotency key, dono da transação e SLA.
Princípios
- Decidir antes de modelar. A primeira entrega é adequação, não diagrama.
- Menor primitiva suficiente. Fluxo fixo continua função, worker ou fila mesmo com branches, retries e métricas.
- LangGraph não substitui infraestrutura. Locks/serialização pertencem ao banco; retries/scheduling podem pertencer à fila; captura de baixa latência pertence ao daemon.
- CRUE só dentro do grafo. Não force State LangGraph sobre estado operacional no banco.
- Fronteiras explícitas. Se apenas consulta adaptativa precisa de LangGraph, não contamine o hot path.