Pular para o conteúdo
  1. fael.tech
  2. Estudos
  3. Radiant

Radiant.

Como transformo uma intenção em software com agentes, com contrato, verificação e aprendizado em cada ciclo.

Tipo
Método
Estado
Em andamento
Publicado em
Atualizado em

A pergunta

Como transformar uma intenção em um sistema real sem perder clareza, contexto, evidência e aprendizado no caminho? Trabalhar com agentes torna essa pergunta mais urgente. Um agente executa rápido, mas executa o que entendeu, e o que ele entendeu depende do que foi escrito antes.

O ciclo

O Radiant organiza o trabalho em etapas, cada uma com um documento próprio.

  1. Enquadrar e desafiar. O Project Frame registra a intenção, o problema e o que está fora do escopo. O Design Frame faz o mesmo para a experiência de quem vai usar. Antes de seguir, o desafio pergunta qual hipótese o incremento testa e qual alternativa mais simples atenderia.
  2. Especificar e planejar. A Spec e o Plan descrevem o sistema e a ordem de construção. A especificação da experiência fica num documento separado.
  3. Contratar. Cada tarefa vira um contrato com uma única mudança observável como objetivo, o escopo permitido, os resultados esperados, o que não fazer e como verificar.
  4. Construir. Um agente executa o contrato, e só ele.
  5. Verificar. Checagens automáticas, uma verificação focada no que mudou, uma releitura do resultado e uma crítica independente.
  6. Aprender. O que deu certo ou errado volta para o lugar responsável: o contrato, o template, o procedimento ou o próprio método.
# Radiant Task Contract
Status: READY | HOLD | IN_PROGRESS | VERIFY | DONE | FAIL
Risk tier: 0 | 1 | 2 | 3

## 1. Objective
Descreva uma única mudança observável.

## 6. Non-goals
Trecho do contrato que cada tarefa preenche antes de um agente começar.

Papéis

Cada etapa do ciclo tem um papel responsável. Uma sessão principal, o orquestrador, conversa comigo, decide o que delegar e faz o aceite final. O resto do trabalho vai para subagentes com escopo fechado. Nenhum deles fala comigo diretamente, e nenhum delega para outro.

Orquestrador
Conduz o ciclo, aplica os gates de aprovação e guarda para si mudança de escopo, ativação de contrato e ações irreversíveis.
Ideação
Pesquisa fontes para o Frame e faz a crítica adversarial de premissas e escopo, sem decidir nenhum dos dois.
Design
Redige Spec, Design Spec e decisões de arquitetura como propostas. A aprovação é minha.
Dev
Executa o contrato. O contrato é o pedido, e o relatório de conclusão é a resposta.
Verificador
Confronta o resultado com o contrato e a Spec e devolve achados com evidência, sem corrigir o que verifica.
Manutenção
Fica fora do ciclo. Observa o projeto e propõe o que fazer em seguida.

O orquestrador não aceita um trabalho como pronto só pelo relato de quem o fez. Ele relê a mudança, roda as checagens e compara com o contrato.

Capacidades

O método não cita modelos. Ele fala em três capacidades: deep para julgamento, crítica e aceite, standard para execução delimitada por um documento aprovado e light para busca, coleta e checagens mecânicas. Cada papel tem uma capacidade padrão, e só o contrato da tarefa muda isso, com uma linha de justificativa. O aceite nunca usa uma capacidade menor que a de quem produziu o trabalho. Assim o trabalho delimitado fica mais barato sem afrouxar a verificação.

Quem traduz capacidade em modelo é o adaptador de cada ferramenta. Hoje são dois, para Codex e Claude Code, sobre o mesmo núcleo. Cada delegação fica registrada com papel, capacidade e o modelo que de fato rodou.

{
  "capabilities": ["deep", "standard", "light"],
  "agents": [
    {
      "name": "radiant-verifier",
      "role": "verificador",
      "capability": "deep",
      "description": "Verifica outputs contra contrato, Spec e critérios, sem corrigir o que verifica."
    },
Trecho do arquivo com os perfis que podem receber trabalho delegado.

Unidades e roteamento

Um contrato pode se dividir em unidades de execução. Cada unidade declara o papel, a capacidade e os requisitos, mas nunca a ferramenta nem o modelo. Sem essa divisão, o contrato inteiro é uma unidade só.

Em qual ferramenta cada tipo de unidade roda é decidido por regras de roteamento que ficam na minha máquina, fora de qualquer projeto, porque as ferramentas instaladas e as assinaturas são fatos da máquina. O orquestrador escolhe a regra que descreve a unidade. Dos candidatos dessa regra, saem os que não têm adaptador do Radiant ou não atendem aos requisitos da unidade, e o primeiro que sobra fica com o trabalho. A decisão é registrada antes do lançamento.

Um candidato nunca roda numa capacidade abaixo da que a unidade pede. Sem candidato viável, a unidade fica parada em HOLD. Uma regra também pode exigir minha confirmação antes de despachar.

Quem lê as unidades e abre uma sessão para cada uma é o Demerzel, uma ferramenta à parte, com estudo próprio. O Radiant define o formato das unidades e das regras, e os validadores dele conferem o bloco de unidades do contrato.

Manutenção

A Manutenção roda na minha máquina, por comando ou agendada, e só propõe. Ela olha o estado dos contratos, as checagens que o projeto declarou seguras, divergências entre Spec e código, dependências e, quando autorizado, issues e CI. Fonte não autorizada é pulada, e o relatório diz por quê.

Cada candidato precisa de evidência: saída de comando, arquivo, linha. O resultado é um relatório com as propostas ordenadas por risco, valor e reversibilidade e um rascunho de contrato para as três primeiras. A única coisa que ela grava é esse relatório, numa pasta fora do Git. Um relatório sem nada relevante também é um resultado. Quando escolho uma proposta, o orquestrador cria o contrato e o ciclo começa.

Regras que valem para tudo

Acima dos documentos fica uma constituição, com os invariantes do método e a ordem de precedência quando duas regras entram em conflito. Ela separa o desenho do sistema do desenho da experiência e define que um aprendizado só vira regra geral quando se repete. Um problema isolado é corrigido no projeto onde apareceu.

Repositório do RadiantPúblico, licença MIT

Atualizações

  1. Unidades de execução, regras de roteamento, o despacho pelo Demerzel e o repositório público com licença MIT.
  2. Papéis com delegação, capacidades no lugar de modelos, a Manutenção e o desafio no enquadramento.
  3. Primeira publicação.
← Todos os estudos