Glossário¶

Esta página é a base terminológica da documentação do flower. Cada coisa tem um único nome em todo o site, e a correspondência chinês-inglês está fixada aqui — as versões traduzidas seguem esta mesma tabela.

Cada entrada dá três coisas: o que o termo designa, o que ele é no código e o que ele não é. A terceira costuma ser a mais útil, porque a maioria dos mal-entendidos vem de confundir um termo com outro.

Framework e run¶

Long-horizon¶

long-horizon

Um run que atravessa horas ou dias, várias sessions e reinícios de processo — não uma pergunta e uma resposta. Todos os mecanismos do flower existem para que esse tipo de run não desmonte no meio do caminho.

Referência medida: HT001 rodou 10.4 horas seguidas.

Run¶

run

O processo completo de um Runtime, do início ao fim. Um run pode conter vários steps, várias sessions, e pode ser interrompido e depois continuado. O registro do run fica em runs/manifest.json e runs/sessions.db.

Não é: uma chamada de API, nem uma session.

Session¶

session

Um contexto do lado do modelo. Tem seu próprio session_id, pode sofrer resume e fork. Um run pode queimar várias sessions — cada handoff troca por uma nova.

Step¶

step · Step

Uma unidade executável dentro de um workflow. Recebe um dicionário de contexto, roda um agent e escreve o resultado de volta no dicionário. Step é uma classe, veja a Python API.

Workflow¶

workflow · Workflow

Um conjunto de steps encadeados em ordem, mais as regras de como o estado passa entre eles e quando sair mais cedo.

Papéis¶

Papéis são a divisão de trabalho que o flower faz entre agents. Cada papel = um trecho de regras injetado + um conjunto de ferramentas + um conjunto de hooks. Os cinco papéis são funções de fábrica, veja a Python API.

Coordinator¶

coordinator · coordinator()

O agent que fica na main thread. Ele decompõe a tarefa, delega, lê relatórios e decide, mas não põe a mão — não recebe Write / Edit. As ferramentas básicas são Agent, TodoWrite, Read (roles.py:27), mas essa não é a lista final: conforme os parâmetros, mais três coisas entram. glance=True (padrão) adiciona um Bash restrito (o suficiente para comandos do tipo git status / ls, que se resolvem numa olhada, com o delegate_guard controlando); se houver um canal de perguntas, entram inbox e ask; e se os workers sob seu comando têm WebFetch / WebSearch, esses dois também são incorporados — allowed_tools é de nível de session, e sem essa incorporação o subagent trava numa aprovação de permissão que ninguém responde (roles.py:513-526).

O papel é definido como "alguém que sabe usar o Claude Code", não como executor.

Não é: um agent mais inteligente. Ele e o worker usam por padrão a mesma classe de modelo; o que se economiza é contexto, não modelo.

Worker¶

worker · worker()

O subagent que realmente trabalha: escreve código, roda testes, pesquisa. As ferramentas são Read Write Edit Bash Glob Grep WebFetch WebSearch.

O formato da resposta é restringido pelo texto de regras a quatro seções — conclusão / evidências / entregas / não verificado —, no máximo 30 linhas, proibido colar conteúdo de arquivo, saída de comando, log ou diff bruto.

Clarifier¶

clarifier · clarify()

O papel que esclarece o requisito antes de se pôr a mão na massa. Ele não executa nada, só pergunta, até ficar claro (sem limite de rodadas), e ao final produz um brief. Veja Clarify.

Judge¶

judge · judge()

O papel que decide "está pronto ou não". Ele faz uma de duas coisas: antes do run, define o objetivo (produz o objetivo + a checklist de julgamento); ou, ao fim de cada rodada, julga aquela rodada (produz um verdict). Veja Goal guard.

Ponto-chave: o judge julga o artefato entregue, não o código-fonte.

Em HT001 isso deu errado uma vez: o critério de aceite dizia "roda diretamente no terminal do macOS", e o artefato entregue, passado pelo file, deu ELF 64-bit LSB pie executable, ARM aarch64, GNU/Linux — e mesmo assim o veredito foi aprovado.

Dois pontos precisam ficar claros, senão esse exemplo é lido errado:

1. O que errou ali não foi o goal guard — o HT001 ainda não tinha esse mecanismo; quem errou foi um auditor que o coordinator despachou por conta própria.
2. O judge na configuração padrão provavelmente também deixaria passar. judge() usa can_run=False por padrão, e as ferramentas são só Read/Glob/Grep — ele não consegue rodar file; só vai ler o Makefile, ver que existe mesmo um ramo Darwin, e julgar como atingido.

O que de fato funciona é HT002: lá o judge estava com judge_can_run ligado, rodou file e lsof para olhar a cena, e evitou explicitamente esse buraco. Ou seja: "julgar o artefato" só se sustenta com can_run=True.

Oracle¶

oracle · oracle()

Um desvio somente-leitura. Com o run ainda em andamento, você pode perguntar "onde estamos agora", e ele dá uma olhada nos eventos recentes e no workbench antes de responder. O que ele diz não entra no contexto daquele run — perguntar não afeta o run, e a resposta é descartada depois.

subagent¶

Conceito do Claude Agent SDK: um agent filho despachado pelo agent principal via a ferramenta Agent. Ele tem um transcript próprio; as chamadas de ferramenta e as tentativas erradas ficam registradas ali, e a main thread só recebe o relatório final.

Esta é a primeira camada de economia de contexto do flower, e a que mais economiza. Veja Economia de contexto.

Os quatro mecanismos¶

Clarify¶

clarify

Esclarecer o requisito antes de agir, congelá-lo em um brief e só então executar. Barra o "fizeram, mas não é o que eu queria". Veja Clarify.

Brief¶

brief · Brief

O documento que o clarifier produz depois de perguntar tudo, com exatamente quatro seções. Os steps seguintes o leem, em vez de adivinhar o requisito de novo.

Não confunda com task brief. O brief é "o que a pessoa quer"; o task brief é "o que este subagent vai fazer desta vez".

Task brief¶

task brief

O texto que o coordinator escreve para o worker ao delegar. Escreva apenas o que é específico desta tarefa — não repita a disciplina que o outro lado já conhece.

Medido: 8/8 dos task briefs repetiam disciplina já conhecida pelo destinatário; no mais curto deles, de 521 caracteres, só cerca de 120 caracteres eram específicos da tarefa — cerca de 4.8k de contexto permanente desperdiçados por rodada.

Goal guard¶

goal guard

Ao fim de cada rodada, o judge decide de forma independente se o objetivo foi atingido; se não foi, devolve para continuar. Barra o "disse que terminou, mas não terminou". Veja Goal guard.

Verdict¶

verdict · Verdict

O resultado de uma rodada de julgamento do judge, com exatamente três seções: conclusão / motivo / não aprovado.

A conclusão tem três valores: ACHIEVED (atingido), NOT_YET (ainda não), UNREACHABLE (não dá para verificar neste ambiente). Os dois últimos são conclusões diferentes — "aqui não dá para verificar" jamais é julgado como aprovado.

Continuidade¶

continuity

Rodar de novo no mesmo diretório retoma automaticamente o progresso da vez anterior — inclusive se o processo foi morto ou a máquina reiniciou. Barra o "rodou horas, quebrou, e começa tudo de novo". Veja Continuidade.

Não confunda com handoff: continuidade retoma o run anterior entre processos; handoff troca por uma session nova dentro do mesmo run.

Handoff¶

handoff

Quando o contexto está quase cheio, a session atual escreve um documento de handoff que uma pessoa consegue ler e editar, e então uma nova session assume. Barra o "o contexto encheu e virou um resumo de um parágrafo". Veja Handoff.

Não é compact. Veja compact.

Documento de handoff¶

handoff document · Handoff

O documento escrito no handoff, com cinco seções: doing (o que está sendo feito), decided (o que foi decidido), deadends (caminhos sem saída), next (próximo passo), scene (a cena).

Só doing e next são obrigatórios — exigir rigidamente que "caminhos sem saída" não seja vazio força o modelo a inventar.

Compact¶

compact

A abordagem nativa do Claude Code: quando o contexto enche, resume a conversa anterior em um parágrafo.

O flower não usa isso, usa handoff no lugar. A diferença: o resumo é gerado pelo modelo, não é legível nem editável, e você não sabe o que se perdeu; o documento de handoff é estruturado, gravado em disco, e você pode abrir, mudar uma linha e mandar continuar.

Gestão de contexto¶

Main thread¶

main thread

O contexto de session onde vive o coordinator. É o único contexto que atravessa o run inteiro, então é o que mais precisa ser economizado.

Como o código identifica a main thread: os dados do hook não têm agent_id. Os hooks de subagent trazem agent_id.

Workbench¶

workbench · Workbench

O diretório de trabalho gravado em disco, com três subdiretórios:

INDEX.md é o índice desses três diretórios e é injetado no system prompt, para que o agent saiba a cada rodada o que tem em mãos.

Spill¶

spill

Quando o resultado de uma ferramenta passa do limite (4000 caracteres por padrão), o hook PostToolUse o grava em <raiz do workbench>/spill/, e no contexto fica apenas uma linha com o caminho.

O caminho acompanha o workbench, não é fixo — só quando o workbench está no local padrão <workspace>/.flower é que ele fica exatamente em .flower/spill/. Com isolamento ligado, e o workbench apontado para fora do repositório via home=, o spill se muda junto.

Corta na hora, em vez de esperar o contexto encher para depois fazer compact.

Comando efêmero¶

ephemeral command

Comandos cujo resultado expira e não tem valor de retenção — ls, git status, ps e afins. O resultado deles não entra no registro persistido da session. A decisão de "pode liberar a main thread para dar uma olhada" e a de "o resultado será cortado" usam a mesma função, então os dois conjuntos são sempre iguais.

Trim¶

trim · TrimmingSessionStore

Reescreve, antes do resume, a cópia de mensagens que será alimentada de volta ao modelo (resultados de comandos efêmeros, saídas de ferramenta muito longas).

Ele só sobrescreve load(): o texto original no SQLite nunca é tocado; o que se corta é só aquela cópia enviada ao contexto neste resume. Portanto o trim é reversível — troque a política, faça resume de novo, e o registro completo volta.

Prune¶

prune · PruningSessionStore

Mantém as mensagens de erro fora do contexto. A pilha de erros produzida durante retentativas com a rede caída não deve ocupar o contexto depois do resume.

Não confunda com trim: o trim descarta por volume e valor; o prune descarta por "é erro ou não".

Runtime¶

Isolamento¶

isolation

Papéis marcados recebem automaticamente um git worktree próprio, imposto por hook, sem depender do prompt. Assim não há briga ao alterar o mesmo repositório em paralelo.

Resiliência¶

resilience · Resilience

Com a rede caída, espera em vez de falhar e sair: sondas de DNS + TCP monitoram, e quando a rede volta o run continua via resume. As mensagens de erro geradas durante a espera são mantidas fora do contexto pelo prune.

Linhagem¶

lineage · Lineage

Registra, entre processos, "de qual session este run foi forkado", gravado em lineage.json. A continuidade usa isso para achar onde a última vez parou.

Não confunda com o run manifest — aquele é runs/manifest.json, e registra a contabilidade de cada run.

Run manifest¶

run manifest · runs/manifest.json

O registro contábil de cada run: quanto custou, quanto tempo levou, qual o tamanho do contexto. Todos os números das páginas de caso podem ser recalculados a partir daqui.

Wake¶

wake · wake_state()

Uma sondagem somente-leitura antes da largada: verifica se este workspace já tem um brief e um objetivo, para decidir se esta vez é um começo do zero ou uma continuidade. Não escreve um único byte.

wake_state() é o único lugar que define a localização do workbench — se o programa driver quiser saber onde está o brief, também tem que passar por ele. Montar o caminho na mão e errar não gera erro, só falha em silêncio.

Evento¶

event · Event

O fluxo de mensagens do SDK achatado numa estrutura estável. A camada de interação só conhece Event e não importa nenhum tipo do SDK — é essa a fronteira que permite trocar de UI sem mexer no núcleo.

Camada de interação¶

interaction layer

A camada de UI entre a pessoa e o run. O padrão é o terminal; pode ser trocada por Web, TUI, HTTP, ou por operação totalmente automática sem supervisão. Veja Trocar a camada de interação.

Session store¶

session store · SessionStore

O backend de persistência das mensagens de session. O padrão, SqliteSessionStore, escreve em runs/sessions.db, e pode receber as duas camadas de wrapper: trim e prune.

Budget¶

budget · max_budget_usd

O teto de gasto de um run; ao ultrapassar, para. Sem isso, um run long-horizon fica caro — HT001 custou $171.62.

Portabilidade¶

Portável¶

portable

Troque de máquina e o comportamento é o mesmo. A forma é setting_sources=[] — não lê o ~/.claude/ da máquina hospedeira, nem o .claude/ do projeto. A capacidade de domínio viaja com o repositório via plugin, e as credenciais vêm no .env.

O custo: as credenciais precisam vir junto, não há herança automática da configuração da máquina.

Append¶

append

As instruções de domínio são acrescentadas depois do system prompt nativo do Claude Code, em vez de substituí-lo:

system_prompt = {"type": "preset", "preset": "claude_code", "append": spec.instructions}

Assim, a especialização não custa a capacidade geral.

plugin¶

Um pacote de capacidade de domínio que viaja com o repositório. Carregado via plugins=[local], e o diretório pode conter skills/, agents/, hooks/, .mcp.json. Veja Deploy.