Visão geral
O ContextLab compara três formas de dar contexto a um agente de programação que escreve testes unitários. Ele prepara o material que o agente pode ver, pede uma suíte de testes, guarda a resposta sem alterá-la e só então a executa, em um ambiente separado.
L Local
O agente recebe o arquivo da função e os tipos usados na assinatura dela.
R Recuperado
Recebe o pacote L mais as definições de outros arquivos que a função usa diretamente.
A Autônomo
Começa só com o enunciado e escolhe o que ler, por listagem, leitura e busca.
Três ideias organizam todo o resto:
- Geração e avaliação são separadas. O agente nunca executa o projeto nem vê o resultado dos testes. Não há segunda chance nem reparo.
- Tudo fica registrado. O enunciado, o contexto, cada consulta, a resposta, os resultados por caso e as decisões de revisão ficam em arquivos, por tentativa.
- O que foi congelado não muda. Antes de executar, a configuração, a ordem sorteada e os arquivos do projeto recebem um hash. Se algo mudar depois, o ContextLab se recusa a continuar aquele lote.
Fluxo de uma tentativa
flowchart LR
A["Manifesto"] --> B["Contexto"] --> C["Geração<br/>Codex"] --> D["Entrega<br/>preservada"] --> E["Avaliação<br/>Docker"] --> F["Revisão<br/>humana"] --> G["Defeitos e<br/>relatórios"]
E -. "nenhum resultado volta ao agente" .-x C
Uma tentativa é a combinação de projeto, função, agente, estratégia e repetição. Um lote é o conjunto de tentativas de um plano congelado. Uma tentativa pode conter dezenas de casos de teste; o número de tentativas não muda por isso.
Como o contexto é preparado
O código do projeto é lido e analisado, nunca executado. O preparador monta primeiro uma visão preparada do repositório, um conjunto de arquivos virtuais em memória, e é dela que saem as três estratégias.
Na animação, o alvo real calcular_orcamento do OrçaAPI passa pelas três estratégias.
flowchart TD
I["include do contextlab.json<br/>arquivos candidatos"] --> F{"Filtros"}
F -- "testes, .git, runs, credenciais,<br/>instruções para agentes, links simbólicos" --> X["Excluído<br/>(motivo registrado)"]
F -- "aceito" --> D["Remoção dos exemplos doctest<br/>das docstrings e documentos"]
D --> V[("Visão preparada<br/>arquivos virtuais")]
V --> L["L: arquivo focal inteiro<br/>+ tipos da assinatura"]
L --> R["R: L + dependências diretas<br/>de outros arquivos"]
V --> A["A: todos os arquivos ficam<br/>disponíveis para consulta"]
O que entra e o que fica de fora
- Só entram arquivos listados em
include. Documentos (.md,.rst,.txt) precisam ser indicados pelo caminho exato, sem curinga. - Ficam de fora, mesmo se listados: pastas e arquivos de teste,
.git,runs,conftest.py, arquivos de credenciais, instruções para agentes (AGENTS.md,CLAUDE.md) e links simbólicos. - Um arquivo cujo conteúdo pareça teste ou contenha padrão de chave secreta também é excluído.
- Exemplos no formato doctest são retirados, porque trazem entradas e respostas esperadas. A numeração das linhas é preservada.
Como o trecho específico é escolhido
O alvo é localizado pelo campo symbol dentro do arquivo path, usando a árvore de sintaxe do Python (AST).
| Estratégia | O que é entregue | Como é decidido |
|---|---|---|
| L | O arquivo focal completo e as declarações dos tipos que aparecem na assinatura da função, mesmo que estejam em outro arquivo. | Regra fixa. Se não couber no limite de caracteres, a execução é recusada: o pacote L nunca é cortado. |
| R | Tudo de L, mais funções, classes e constantes de outros arquivos do projeto usadas no corpo do alvo. | Análise estática, profundidade um: não segue as dependências das dependências. Um trecho que não caiba é registrado como omitido. |
| A | Nada além do enunciado. Os arquivos da visão preparada ficam disponíveis. | O próprio agente escolhe, usando list_files, read_file e search. |
R pode ficar igual a L. Isso acontece quando a função não usa nada de outro arquivo, ou quando a origem do que ela usa não pode ser determinada sem executar o código, como self.atributo ou from modulo import *. O registro informa essa coincidência, e a aba Contexto de cada tentativa mostra o que foi entregue.
Limites
O limite de contexto é contado em caracteres e soma o pacote inicial com todas as respostas das ferramentas, inclusive releituras e erros. Há também um limite de número de consultas e um de tempo de geração. O enunciado informa esses limites ao agente, com o mesmo texto nas três estratégias. Ultrapassar um deles encerra a sessão sem entrega.
Como o Codex entra na história
O Codex roda no seu computador, numa pasta vazia. Ele só vê código pedindo ao ContextLab, que responde apenas com o pacote da estratégia.
flowchart LR
CL["ContextLab"] -- "1 · enunciado" --> CX["Codex<br/>pasta vazia"]
CX <-- "2 · pensa" --> M["Modelo<br/>OpenAI"]
CX <-- "3 · pede código" --> P[("Pacote<br/>L, R ou A")]
CX -- "4 · teste pronto" --> T["test_generated.py"]
- Enunciado. O ContextLab abre uma sessão nova do Codex e envia qual função testar. Em L e R, o código do pacote já vai junto; em A, não vai nada.
- Pensa. O Codex repassa a conversa ao modelo, pela internet.
- Pede código. Quando o modelo quer ver mais, usa
list_files,read_fileousearch. Quem responde é o ContextLab, só com arquivos do pacote, contando caracteres e consultas. Os passos 2 e 3 se repetem até o modelo terminar ou um limite estourar. - Teste pronto. A resposta é gravada sem alteração e a sessão acaba. Só depois o teste vai para o Docker.
Por que a pasta vazia
Para que o único caminho até o código seja o pacote. Com o projeto na pasta, o Codex poderia ler testes ou arquivos fora da estratégia.
Por que fora do Docker
Gerar não executa nada, só produz texto, e o Codex precisa de internet para falar com o modelo. O Docker fica para a etapa que executa código: a avaliação.
O que o agente consegue e não consegue fazer
Consegue
- Listar, ler e buscar nos arquivos virtuais permitidos.
- Reler o próprio pacote inicial em L e R.
- Entregar uma resposta final com o arquivo de teste.
Não consegue
- Executar comandos, o projeto ou os testes.
- Abrir arquivos do seu disco: as ferramentas só conhecem os arquivos virtuais.
- Navegar na internet, usar outras integrações ou a sua configuração pessoal do Codex.
- Ver testes de referência, defeitos ou resultados de avaliação.
Antes de cada sessão, o ContextLab faz uma sondagem com um servidor falso, local e sem credenciais, para conferir que o Codex realmente recusa um comando e uma leitura fora do pacote. Se a sondagem falhar, a tentativa não começa.
Desfechos possíveis da geração
| Desfecho | Significado | Conta como |
|---|---|---|
completed | O agente entregou uma resposta no formato pedido. | Geração observável; segue para a avaliação. |
invalid_submission | A resposta não continha um único arquivo Python. | Geração observável, reprovada. |
limit, timeout | O agente esgotou o contexto, as consultas ou o tempo. | Geração observável, reprovada: é resultado da estratégia. |
protocol_violation | Apareceu uma ferramenta ou um evento fora do previsto. | Geração observável, reprovada. |
infrastructure_error | Falha externa: serviço fora do ar, login, cliente. | Não observável; informada à parte. |
Como o contêiner funciona
O Docker é usado só para executar os testes. Cada execução sobe um contêiner novo, roda o pytest e se apaga. Por isso ele quase nunca aparece na lista do Docker: dura um ou dois segundos.
flowchart TD
S["test_generated.py<br/>cópia congelada da entrega"] --> P
subgraph P ["Preparação, fora do contêiner"]
C1["Copia o projeto para uma pasta temporária"] --> C2["Retira os testes de referência<br/>e as testemunhas"]
end
P --> K
subgraph K ["Contêiner temporário"]
direction TB
M1["/project: código, só leitura"]
M2["/submission: o teste, só leitura"]
M3["/results: único lugar gravável"]
R1["pytest + medição de cobertura<br/>sem rede, sem privilégios,<br/>memória e CPU limitadas"]
M1 --> R1
M2 --> R1
R1 --> M3
end
K --> O["Relatório por caso<br/>e cobertura da função"]
O --> Z["Contêiner removido"]
O --> V{"Passou tudo e<br/>exercitou o alvo?"}
V -- "sim" --> W["aguardando revisão"]
V -- "não" --> X["reprovada"]
Por que é rápido
- Um contêiner não é uma máquina virtual. Ele é um processo isolado que usa o sistema já em execução.
- A imagem já vem pronta. Python, pytest, coverage e as dependências do projeto são instalados uma vez, pelo comando
setup. - Nada é copiado para dentro. As pastas são montadas; o contêiner só lê.
O que protege a avaliação
| Controle | Para quê |
|---|---|
Sem rede (--network=none) | O teste gerado não baixa nem envia nada. |
| Sistema de arquivos só de leitura | O teste não altera o código de produção. Um resumo do conteúdo é comparado antes e depois. |
| Sem privilégios, com limite de memória, CPU e processos | Um teste mal escrito não derruba a máquina. |
| Limite de tempo | Uma suíte que trava vira timeout, não um resultado. |
| Testes de referência fora da pasta | A suíte gerada é medida sozinha, sem ajuda dos seus testes. |
Cobertura focal
A cobertura considera apenas o corpo da função-alvo, não o arquivo inteiro, e só conta o que foi executado durante os testes. Importar o módulo não conta. Funções sem ramificações recebem "não aplicável" na coluna de ramificações, nunca zero.
Revisão humana e defeitos controlados
Passar no pytest não basta para aprovar. Uma suíte que passa fica aguardando revisão, e a aprovação depende de uma pessoa, pelo comando review.
stateDiagram-v2
[*] --> Pendente
Pendente --> Gerando
Gerando --> Infraestrutura: falha externa
Gerando --> Reprovada: sem entrega válida ou limite esgotado
Gerando --> Avaliando: entrega preservada
Avaliando --> Reprovada: erro, falha ou alvo não exercitado
Avaliando --> AguardandoRevisao: passou em tudo
AguardandoRevisao --> Reprovada: revisão negativa
AguardandoRevisao --> Aprovada: revisão positiva
Aprovada --> [*]
Reprovada --> [*]
O que a revisão confere
| Critério | Pergunta |
|---|---|
--behavioral-assertions | Os testes verificam valores e comportamentos, e não apenas que a função "não quebrou"? |
--no-target-mock | A função-alvo foi chamada de verdade, sem ser trocada por uma resposta simulada? |
--no-production-changes | O código de produção ficou intacto? |
--dependency-doubles | Dependências da função foram trocadas por dublês? Marca para análise separada, sem reprovar. |
--http-requests | Só em alvos HTTP de piloto: a rota foi exercitada por requisições reais? |
A revisão reexecuta a mesma entrega e guarda a avaliação original. Ela não gera de novo e não permite editar o teste: se o arquivo mudou, o comando recusa.
Defeitos controlados
Um defeito é uma alteração pequena e proposital no código, definida antes da geração. Serve para medir se a suíte percebe quando o comportamento fica errado. Só é medido em suítes aprovadas.
flowchart LR
A["Suíte aprovada"] --> B["Para cada defeito"]
B --> C["Testemunha no<br/>código original"]
C -- "passa" --> D["Testemunha no<br/>código alterado"]
D -- "falha" --> E["Suíte gerada no<br/>código alterado"]
E -- "passou" --> F["sobreviveu"]
E -- "falhou" --> G{"A falha vem do<br/>comportamento alterado?"}
G -- "sim, na revisão" --> H["detectado"]
G -- "não" --> I["não atribuído"]
C -- "falha" --> J["defeito inelegível"]
D -- "passa" --> J
A testemunha é um teste seu que passa no código original e falha no alterado. Ela prova que o defeito muda mesmo o comportamento. Um defeito sem testemunha válida não entra na conta.
O arquivo contextlab.json
É o manifesto: descreve o experimento inteiro. Ele aponta para o código, sem copiá-lo. No uso por projeto fica em projects/NOME/contextlab.json; na coleta principal, um único manifesto reúne os quatro projetos.
{
"schema_version": 1,
"phase": "pilot", // demo, pilot ou main
"seed": 42, // semente do sorteio da ordem
"conditions": ["L", "R", "A"], // estratégias a executar
"repetitions": 3, // sessões novas por estratégia
"limits": {
"context_chars": 30000, // pacote inicial + respostas das ferramentas
"tool_calls": 20, // consultas por sessão
"generation_seconds": 120, // tempo máximo de geração
"evaluation_seconds": 20 // tempo máximo de cada execução no Docker
},
"agents": [
{ "id": "codex", "kind": "codex", "model": "gpt-6.1-sol",
"auth_file": "~/.codex-work/auth.json" } // caminho do login, nunca o conteúdo
],
"evaluation": { "backend": "docker", "image": "contextlab-orcamentos:local" },
"projects": [
{
"id": "orcamentos", // identificador fixo, igual ao nome da pasta
"name": "OrçaAPI", // opcional: nome mostrado na interface
"root": ".", // pasta do projeto, relativa ao manifesto
"source_roots": ["src"], // de onde os módulos são importados
"include": ["src/orcamentos/*.py"], // o que o agente pode ver
"evaluation_include": ["src/orcamentos/*.py", // o que vai para o avaliador
"tests/test_orcamentos.py"],
"targets": [
{
"id": "calcular_orcamento",
"path": "src/orcamentos/orcamentos.py",
"symbol": "calcular_orcamento",
"import": "orcamentos.orcamentos:calcular_orcamento",
"reference_tests": ["tests/test_orcamentos.py"],
"defects": [
{ "id": "total-sem-desconto",
"path": "src/orcamentos/orcamentos.py",
"old": "total=base + frete",
"new": "total=subtotal + frete",
"witness": "tests/test_orcamentos.py::test_testemunha_total_desconta_cupom" }
]
}
]
}
]
}
Os comentários acima são explicativos. O arquivo real é JSON puro e não aceita comentários.
Campos gerais
| Campo | Valores | O que controla |
|---|---|---|
schema_version | 1 | Versão do formato do arquivo. |
phase | demo, pilot, main | demo usa testes escritos por você, sem modelo. pilot chama o Codex em ensaios. main é a coleta principal e exige a matriz completa. |
seed | inteiro | Semente do sorteio. A mesma semente produz a mesma ordem. |
conditions | L, R, A | Estratégias que entram no plano. |
repetitions | inteiro ≥ 1 | Quantas sessões novas por combinação de função e estratégia. |
limits | quatro inteiros | Limites de contexto, consultas, geração e avaliação. Todos obrigatórios: não há valor implícito. |
agents e evaluation
| Campo | Valores | O que controla |
|---|---|---|
agents[].kind | codex, fixture | codex chama o cliente real. fixture carrega um teste já escrito e só vale em demo. |
agents[].model | texto | Identificador exato do modelo. Obrigatório para agentes reais. |
agents[].reasoning_effort | texto | Esforço de raciocínio do Codex: low, medium, high, xhigh, max ou ultra. Obrigatório na coleta principal; sem ele, vale o padrão do modelo, que muda entre modelos. |
agents[].auth_file | caminho | Onde está o login do Codex. Aceita ~. Sem ele, usa a variável CODEX_API_KEY. |
agents[].fixture_dir | pasta | Onde ficam os testes prontos do modo demo. |
evaluation.backend | docker, local | local só é aceito em demo, com --trusted-local. Código gerado por modelo sempre roda no Docker. |
evaluation.image | nome da imagem | Imagem com Python, pytest, coverage e as dependências do projeto. |
projects e targets
| Campo | O que controla |
|---|---|
id | Identificador do projeto. Só letras sem acento, números, - e _. No uso por projeto, precisa ser igual ao nome da pasta. Aparece nos nomes das pastas e nos registros, por isso não deve mudar depois da primeira execução. |
name | Opcional. Nome de exibição, livre, usado como título desta página. Exemplo: "OrçaAPI". |
root | Pasta do projeto, relativa ao manifesto. |
source_roots | Pastas a partir das quais os módulos são importados, como src. Usadas para resolver dependências e para montar o caminho de importação no avaliador. |
include | O que pode entrar na visão do agente. Aceita curingas para arquivos Python. |
exclude | Opcional. Exclusões adicionais dentro do que foi incluído. |
evaluation_include | O que é copiado para o avaliador: o código de produção e os testes de referência. |
targets[].path | Arquivo onde a função está. |
targets[].symbol | Nome da função, ou Classe.metodo. |
targets[].import | Caminho de importação, no formato modulo:simbolo. Vai para o enunciado. |
targets[].test_kind | unit (padrão) ou http. O tipo http só vale fora de main. |
targets[].reference_tests | Seus testes para o alvo. Precisam passar no avaliador antes de qualquer geração e nunca são mostrados ao agente. |
targets[].defects | Lista de alterações controladas. Cada uma tem id, path, o trecho old (que precisa aparecer exatamente uma vez no arquivo), o trecho new e a witness. |
Regras da fase main
Com "phase": "main", o ContextLab só aceita a matriz do experimento: 4 projetos × 3 funções × Codex × L, R e A × 3 repetições = 108 tentativas, com avaliação no Docker e alvos do tipo unit. O congelamento também exige a evidência de um piloto feito com a mesma versão do ContextLab, a mesma imagem, os mesmos limites e o mesmo modelo.
Alterar o contextlab.json vale para os próximos lotes. Lotes já criados guardam a própria cópia congelada e não são afetados.
Passo a passo, comando a comando
O caminho completo de um projeto, do cadastro à análise, com dados reais do piloto do OrçaAPI. Use os botões para pausar ou pular para um comando.
Os mesmos passos, em diagramas para consulta:
contextlab create NOME · cadastrar
flowchart LR
P["projects/NOME/"] --> S["Procura funções<br/>no código"] --> E["Você escolhe<br/>o alvo"] --> J[("contextlab.json")]
Lê o código sem executá-lo e grava o cadastro: alvo, testes de referência, modo, estratégias, repetições, modelo e imagem. Para mudar depois, use configure.
contextlab NOME setup · preparar o Docker
flowchart LR
D{"Docker<br/>disponível?"} -- "sim" --> I{"Imagem<br/>existe?"}
I -- "não" --> B["Constrói a imagem<br/>Python + pytest + coverage"] --> OK["Pronto"]
I -- "sim" --> OK
Deixa pronta a imagem em que os testes serão executados. Nenhum modelo é chamado.
contextlab NOME plan · ver o plano
flowchart LR
J[("contextlab.json")] --> M["Alvos × estratégias<br/>× repetições"] --> O["Sorteia a ordem"] --> T["Lista na tela"]
Mostra quais tentativas serão feitas e em que ordem. Não grava nada.
contextlab NOME context · ver o contexto
flowchart LR
C["Código do projeto"] --> F["Filtra testes,<br/>credenciais e docs"] --> X{"Estratégia"}
X -- "L" --> L["Arquivo da função"]
X -- "R" --> R["L + dependências"]
X -- "A" --> A["Lista de arquivos<br/>disponíveis"]
Mostra exatamente o que o agente receberia, sem gastar uma geração.
contextlab NOME run · executar
É o comando principal. Ele passa por três fases.
flowchart TD
subgraph V ["1 · Conferências"]
direction LR
V1["Codex<br/>responde?"] --> V2["Contexto cabe<br/>no limite?"] --> V3["Docker: referências passam<br/>e testemunhas pegam defeitos?"]
end
subgraph Z ["2 · Congelamento"]
direction LR
Z1["Grava protocol.lock.json<br/>configuração, ordem e hashes"]
end
subgraph T ["3 · Cada tentativa"]
direction LR
T1["Monta o<br/>contexto"] --> T2["Codex gera<br/>o teste"] --> T3["Grava a entrega<br/>sem alterar"] --> T4["Docker executa<br/>no projeto completo"] --> T5[("record.json")]
end
V --> Z --> T
- Conferências: se algo falhar aqui, nenhuma geração começa e nada é gasto.
- Congelamento: a partir daqui o lote não aceita mudanças no código, na configuração ou na ordem.
- Tentativas: seguem a ordem sorteada. O resultado de uma nunca volta ao agente. Se a execução parar no meio,
run --resume LOTEcontinua de onde parou. Só uma falha de infraestrutura (Docker, rede, serviço, interrupção) é repetida, uma única vez, com o motivo registrado e o original guardado.
Ao final, o teste pode ter passado, mas ainda fica aguardando revisão.
contextlab NOME runs e show ID · conferir
flowchart LR
R[("record.json")] --> L["runs<br/>uma linha por tentativa"]
R --> S["show<br/>casos, falhas e código"]
Só leem os registros. Servem para escolher o que revisar.
contextlab NOME review ID · revisar
flowchart TD
H["Você responde três perguntas<br/>verifica comportamento?<br/>sem mock do alvo?<br/>produção intacta?"] --> E["Docker reexecuta<br/>a mesma entrega"]
E --> Q{"Aprovada?"}
Q -- "não" --> N["Reprovada"]
Q -- "sim" --> D["Docker executa o teste<br/>em cada versão com defeito"]
D --> A["Você confirma se cada falha<br/>foi causada pelo defeito"] --> F[("Revisão gravada")]
A aprovação depende do teste passar e da revisão humana. Só as suítes aprovadas são testadas contra os defeitos.
contextlab NOME serve · analisar
flowchart LR
R[("Lotes do projeto")] --> P["Calcula médias,<br/>tokens e custo"] --> W["Esta página<br/>no navegador"]
Só lê. Nada é alterado nos lotes.
Comandos
Há duas formas de usar. Por projeto, para aprender, demonstrar e pilotar: contextlab NOME comando. Por manifesto, para controlar cada etapa da coleta principal: contextlab comando ARQUIVO.
Caminho típico por projeto
flowchart LR
A["create"] --> B["configure"] --> C["setup"] --> D["plan"] --> E["context"] --> F["run"] --> G["runs / show / serve"] --> H["review"]
F -. "interrompeu?" .-> F2["run --resume LOTE"] --> G
contextlab create NOMEcadastra um projetoProcura funções no código que já existe em projects/NOME/, deixa você escolher o primeiro alvo e grava o contextlab.json. Não executa o projeto e não sobrescreve um cadastro existente.
--target ARQUIVO:SIMBOLO | Escolhe o alvo sem perguntar. |
--reference TESTE | Teste de referência do alvo. Pode repetir. |
--mode demo|pilot | Modo inicial. |
--conditions L R A | Estratégias. |
--repetitions N | Repetições. |
--model ID | Modelo do Codex, obrigatório em pilot. |
--auth-file CAMINHO | Arquivo de login. |
--image NOME | Imagem Docker do avaliador. |
--fixture-dir PASTA | Pasta dos testes prontos do modo demo. |
contextlab NOME configureajusta o cadastroMuda modo, estratégias, repetições, modelo, login ou imagem. Sem opções, pergunta uma a uma. Aceita as mesmas opções de create, exceto as de alvo. Vale para os próximos lotes.
contextlab NOME setupprepara a imagem DockerConfere se o Docker está disponível e constrói ou reutiliza a imagem do avaliador. Não inicia gerações.
--dockerfile ARQUIVO | Receita própria, quando o projeto tem dependências além de pytest e coverage. |
contextlab NOME planmostra o que será executadoLista as tentativas na ordem sorteada. Não chama o modelo nem o Docker.
--json | Saída em JSON. |
contextlab NOME contextmostra o contexto de uma estratégiaExibe o pacote que L ou R entregariam, ou a lista de arquivos disponíveis em A. Serve para conferir o material antes de gastar uma geração.
--condition L|R|A | Estratégia a inspecionar. Padrão: L. |
--target ID | Obrigatório quando o projeto tem mais de um alvo. |
contextlab NOME runexecuta o planoCria um lote, valida os testes de referência e as testemunhas, congela o plano e executa cada tentativa: gera, preserva a entrega e avalia.
--max-runs N | Processa no máximo N tentativas nesta chamada. Não reduz o plano. |
--resume LOTE | Continua um lote. Pula o que já foi registrado. A única exceção é a falha de infraestrutura, repetida uma vez; falhas do agente nunca se repetem. |
--trusted-local | Só em demo: permite avaliar sem Docker testes escritos por você. |
contextlab NOME runslista as tentativasUma linha por tentativa de todos os lotes, com a situação. Só consulta.
--json | Saída em JSON. |
contextlab NOME show IDabre uma tentativa no terminalMostra contagens, tabela dos casos e detalhes das falhas. O ID tem o formato lote/01 e aparece em runs.
--code | Mostra também o teste entregue. |
--json | Mostra só o JSON da avaliação mais recente. |
contextlab NOME review IDregistra a revisãoGrava as decisões do revisor e reexecuta a mesma entrega. Em suítes aprovadas, executa também os defeitos.
--reviewer NOME | Quem revisou. |
--behavioral-assertions yes|no | Há verificações de comportamento. |
--no-target-mock yes|no | O alvo não foi simulado. |
--no-production-changes yes|no | A produção ficou intacta. |
--dependency-doubles yes|no | A suíte trocou dependências da função por dublês. Só marca, para análise separada; não reprova. |
--http-requests yes|no | Só em alvos HTTP. |
--defect-attribution ID=yes|no | Atribui a falha ao defeito. Pode repetir, uma vez por defeito. |
contextlab NOME serveabre esta páginaAbre o visualizador com todos os lotes do projeto. É somente leitura. No fluxo por manifesto: contextlab serve RESULTADOS.
--batch LOTE | Mostra só um lote. |
--port N | Porta local. Padrão: 8765. |
--no-open | Não abre o navegador. |
--prices ARQUIVO.json | Tarifas de API para estimar o custo. Por projeto, projects/NOME/precos.json é usado automaticamente. |
--export ARQUIVO.html | Grava a página em um arquivo único, que abre sem instalação. |
Fluxo por manifesto, usado na coleta principal
flowchart LR
A["plan"] --> B["doctor"] --> C["prepare"] --> D["validate"] --> E["freeze"] --> F["run"] --> G["review"] --> H["report"]
P["piloto com alvos<br/>fora da amostra"] -. "evidência exigida em main" .-> E
| Comando | O que faz | Opções |
|---|---|---|
contextlab plan MANIFESTO | Mostra a matriz na ordem sorteada. | |
contextlab doctor MANIFESTO | Confere o cliente do Codex: versão, opções exigidas, login e a sondagem das ferramentas. Não chama o modelo. | |
contextlab prepare MANIFESTO | Grava em uma pasta o contexto de um alvo e uma estratégia, para inspeção. | --project, --target, --condition, --out |
contextlab validate MANIFESTO | Executa os testes de referência e as testemunhas de todos os defeitos. | --out, --trusted-local |
contextlab freeze MANIFESTO | Congela configuração, arquivos, ambiente e ordem em um arquivo .lock.json. Nunca sobrescreve. | --out, --evidence |
contextlab run LOCK | Executa o plano congelado. | --out, --resume, --max-runs, --trusted-local |
contextlab review TENTATIVA | Registra a revisão de uma pasta de tentativa. | as mesmas de review por projeto |
contextlab report RESULTADOS | Exporta results.csv, report.json e report.md, sem reexecutar nada. | |
contextlab serve RESULTADOS | Abre este visualizador para uma pasta de resultados. | --port, --no-open, --prices, --export |
Todo comando aceita --help. No fluxo por manifesto, --resume não recebe argumento: o arquivo congelado e a pasta de resultados já identificam o lote.
O que fica gravado
Cada lote guarda tudo o que é necessário para conferir uma tentativa sem repeti-la.
projects/NOME/runs/LOTE/ ├── protocol.lock.json plano congelado, com hashes ├── validation/ referências e testemunhas executadas antes da geração └── results/ ├── run.json cabeçalho da execução ├── results.csv report.json report.md └── PROJETO__ALVO__AGENTE__ESTRATEGIA__REPETICAO/ ├── record.json situação, tempos, tokens, avaliação e revisão ├── prompt.txt enunciado enviado, com limites e pacote inicial ├── context.json o que foi preparado, omitido e não resolvido ├── response.txt resposta recebida ├── test_generated.py a entrega, sem alterações ├── agent/ eventos do Codex e auditoria das consultas ├── evaluation/ resultados por caso e cobertura └── reviews/ cada revisão e sua reavaliação
Como ler os números desta página
| Termo | Significado |
|---|---|
| Geração observável | Tentativa que chegou a um desfecho atribuível ao agente: entrega válida, entrega inválida ou limite esgotado. Falhas externas ficam de fora e são contadas à parte. |
| Casos | Casos de teste que passaram sobre os que foram executados. Um teste parametrizado gera um caso por conjunto de entradas. |
| Linhas, Ramif. | Cobertura do corpo da função-alvo. Um asterisco indica valor diagnóstico, de uma suíte ainda não aprovada. |
| Defeitos | Defeitos detectados sobre os elegíveis. Só existe depois da aprovação. |
| Tok. entrada, Tok. saída | Totais informados pelo Codex para a sessão. A entrada soma todas as trocas, por isso cresce com o número de consultas. |
| Caracteres | Contexto efetivamente entregue: pacote inicial mais respostas das ferramentas. |
| Custo est. | Estimativa por tarifas de API. Não é a despesa efetiva quando o login é por assinatura. |
| Custo por suíte aprovada | Custo de todas as gerações observáveis de uma estratégia dividido pelo número de suítes aprovadas. |