Testando habilidades de agentes de forma sistemática com avaliações

Ao iterar sobre uma habilidade para um agente como o Codex, é difícil saber se você está realmente melhorando a habilidade ou apenas mudando seu comportamento. Uma versão parece mais rápida, outra parece mais confiável, e então surge uma regressão: a habilidade não é acionada, pula uma etapa obrigatória ou deixa arquivos extras para trás.

Em essência, uma habilidade é uma coleção organizada de prompts e instruções para um LLM. A maneira mais confiável de melhorar uma habilidade ao longo do tempo é avaliá-la como você avaliaria qualquer outro prompt para aplicações de LLMs.

As avaliações (“evals”, abreviação de evaluations em inglês) verificam se a saída de um modelo e as etapas usadas para produzi-la correspondem ao que você pretendia. Em vez de perguntar “isso parece melhor?” (ou se basear em impressões), as avaliações permitem fazer perguntas concretas, como:

• O agente invocou a habilidade?
• Ele executou os comandos esperados?
• Ele produziu saídas que seguem as convenções importantes para você?

Concretamente, uma avaliação é: um prompt → uma execução capturada (rastro de execução + artefatos) → um pequeno conjunto de verificações → uma pontuação que você pode comparar ao longo do tempo.

Na prática, avaliações de habilidades de agentes se parecem muito com testes leves de ponta a ponta: você executa o agente, registra o que aconteceu e pontua o resultado com base em um pequeno conjunto de regras.

Este artigo apresenta uma abordagem clara para fazer isso com o Codex, começando pela definição de sucesso e depois adicionando verificações determinísticas e pontuação baseada em rubricas para tornar evidentes as melhorias (e as regressões).

1. Defina o sucesso antes de escrever a habilidade

Antes de escrever a habilidade em si, registre o que significa “sucesso” em termos que você possa realmente medir. Uma maneira útil de pensar nisso é dividir suas verificações em algumas categorias:

• Metas de resultado: A tarefa foi concluída? O aplicativo funciona?
• Metas de processo: O Codex invocou a habilidade, usou as ferramentas e seguiu as etapas que você pretendia?
• Metas de estilo: A saída segue as convenções que você pediu?
• Metas de eficiência: Ele chegou ao resultado sem desperdiçar esforço (por exemplo, com comandos desnecessários ou uso excessivo de tokens)?

Mantenha essa lista curta e focada nas verificações que precisam passar. O objetivo não é codificar todas as preferências logo de início, mas registrar os comportamentos mais importantes para você.

Neste artigo, por exemplo, o guia avalia uma habilidade que configura um aplicativo de demonstração. Algumas verificações são concretas. Ela executou npm install? Criou package.json? O guia combina essas verificações com uma rubrica de estilo estruturada para avaliar convenções e organização.

Essa combinação é intencional. Você precisa de sinais rápidos e específicos que revelem regressões pontuais logo no início, em vez de um único veredito de aprovação ou reprovação no final.

2. Crie a habilidade

Uma habilidade do Codex é um diretório com um arquivo SKILL.md que inclui um cabeçalho de metadados YAML (name, description), seguido das instruções em Markdown que definem o comportamento da habilidade, além de recursos e scripts opcionais. O nome e a descrição importam mais do que pode parecer. São os principais sinais que o Codex usa para decidir se deve invocar a habilidade e quando inserir o restante de SKILL.md no contexto do agente. Se forem vagos ou sobrecarregados de informações, a habilidade não será acionada de forma confiável.

A maneira mais rápida de começar é usar o criador de habilidades integrado ao Codex (que também é uma habilidade). Ele orienta você no processo:

$skill-creator

O criador pergunta o que a habilidade faz, quando deve ser acionada e se contém apenas instruções ou também usa scripts (a recomendação padrão é usar apenas instruções). Para saber mais sobre como criar uma habilidade, consulte a documentação.

Uma habilidade de exemplo

Este artigo usa um exemplo intencionalmente mínimo: uma habilidade que configura um pequeno aplicativo de demonstração em React de forma previsível e repetível.

Essa habilidade vai:

• Criar a estrutura inicial de um projeto usando o template React + TypeScript do Vite
• Configurar o Tailwind CSS usando a abordagem oficial com o plug-in do Vite
• Exigir uma estrutura de arquivos mínima e consistente
• Estabelecer uma “definição de pronto” clara para facilitar a avaliação do sucesso

Abaixo está um rascunho compacto que você pode colar em um destes locais:

• .codex/skills/setup-demo-app/SKILL.md (com escopo de repositório), ou
• ~/.codex/skills/setup-demo-app/SKILL.md (com escopo de usuário).

---
name: setup-demo-app
description: Scaffold a Vite + React + Tailwind demo app with a small, consistent project structure.
---

## When to use this

Use when you need a fresh demo app for quick UI experiments or reproductions.

## What to build

Create a Vite React TypeScript app and configure Tailwind. Keep it minimal.

Project structure after setup:

- src/
  - main.tsx (entry)
  - App.tsx (root UI)
  - components/
    - Header.tsx
    - Card.tsx
  - index.css (Tailwind import)
- index.html
- package.json

Style requirements:

- TypeScript components
- Functional components only
- Tailwind classes for styling (no CSS modules)
- No extra UI libraries

## Steps

1. Scaffold with Vite using the React TS template:
   npm create vite@latest demo-app -- --template react-ts

2. Install dependencies:
   cd demo-app
   npm install

3. Install and configure Tailwind using the Vite plugin.
   - npm install tailwindcss @tailwindcss/vite
   - Add the tailwind plugin to vite.config.ts
   - In src/index.css, replace contents with:
     @import "tailwindcss";

4. Implement the minimal UI:
   - Header: app title and short subtitle
   - Card: reusable card container
   - App: render Header + 2 Cards with placeholder text

## Definition of done

- npm run dev starts successfully
- package.json exists
- src/components/Header.tsx and src/components/Card.tsx exist

Esta habilidade de exemplo adota escolhas bem definidas de propósito. Sem restrições claras, não há nada concreto para avaliar.

3. Acione a habilidade manualmente para revelar suposições implícitas

Como a invocação de habilidades depende tanto do nome e da descrição em SKILL.md, a primeira coisa a verificar é se a habilidade setup-demo-app é acionada quando você espera.

Logo no início, ative a habilidade explicitamente, pelo comando de barra /skills ou fazendo referência a ela com o prefixo $, em um repositório real ou em um diretório de testes, e observe onde ela falha. É aqui que você identifica os problemas: casos em que a habilidade não é acionada, é acionada com facilidade excessiva ou é executada, mas se desvia das etapas previstas.

Nesta etapa, o foco ainda não é otimizar a velocidade nem refinar o resultado. Você está procurando suposições implícitas da habilidade, como:

• Suposições sobre o acionamento: Prompts como “configure uma demonstração rápida em React” que deveriam invocar setup-demo-app, mas não invocam, ou prompts mais genéricos (“adicione estilos com Tailwind”) que a acionam involuntariamente.

• Suposições sobre o ambiente: A habilidade pressupõe que está sendo executada em um diretório vazio ou que npm está disponível e tem preferência sobre outros gerenciadores de pacotes.

• Suposições sobre a execução: O agente pula npm install porque pressupõe que as dependências já estão instaladas, ou configura o Tailwind antes de o projeto Vite existir.

Quando estiver pronto para tornar essas execuções repetíveis, passe a usar codex exec. Ele foi projetado para automação e CI: envia o progresso continuamente para stderr e grava apenas o resultado final em stdout, o que facilita automatizar as execuções com scripts, capturá-las e inspecioná-las.

Por padrão, codex exec é executado em um sandbox restrito. Se a tarefa precisar gravar arquivos, execute-o com --full-auto. Como regra geral, especialmente ao automatizar, use apenas as permissões mínimas necessárias para concluir o trabalho.

Uma execução manual básica pode ser assim:

codex exec --full-auto \
  'Use the $setup-demo-app skill to create the project in this directory.'

Essa primeira rodada prática serve menos para validar se tudo está correto e mais para descobrir casos extremos. Cada correção manual que você fizer aqui, como adicionar um npm install que faltava, corrigir a configuração do Tailwind ou tornar a descrição de acionamento mais precisa, pode se tornar uma avaliação futura. Assim, você consolida o comportamento pretendido antes de avaliar em escala.

4. Use um conjunto pequeno e direcionado de prompts para detectar regressões cedo

Você não precisa de um grande benchmark para se beneficiar das avaliações. Para uma única habilidade, um pequeno conjunto de 10 a 20 prompts é suficiente para revelar regressões e confirmar melhorias logo no início.

Comece com um CSV pequeno e amplie-o ao longo do tempo, à medida que encontrar falhas reais durante o desenvolvimento ou o uso. Cada linha deve representar uma situação em que importa se a habilidade setup-demo-app é ativada ou não é ativada , e o que caracteriza o sucesso quando ela é ativada.

Por exemplo, uma versão inicial de evals/setup-demo-app.prompts.csv pode ser assim:

id,should_trigger,prompt
test-01,true,"Create a demo app named `devday-demo` using the $setup-demo-app skill"
test-02,true,"Set up a minimal React demo app with Tailwind for quick UI experiments"
test-03,true,"Create a small demo app to showcase the Responses API"
test-04,false,"Add Tailwind styling to my existing React app"

Cada um desses casos testa algo ligeiramente diferente:

• Invocação explícita (test-01)
  Este prompt menciona a habilidade pelo nome. Ele garante que o Codex consiga invocar setup-demo-app quando solicitado e que mudanças no nome, na descrição ou nas instruções da habilidade não prejudiquem seu uso direto.

• Invocação implícita (test-02)
  Este prompt descreve exatamente o cenário para o qual a habilidade foi criada (configurar uma demonstração mínima com React + Tailwind), sem mencionar a habilidade pelo nome. Ele testa se o nome e a descrição em SKILL.md são claros o suficiente para que o Codex selecione a habilidade por conta própria.

• Invocação contextual (test-03)
  Este prompt adiciona contexto de domínio (a Responses API), mas ainda exige a mesma configuração de base. Ele verifica se a habilidade é acionada com prompts realistas que contêm um pouco de ruído e se o aplicativo resultante ainda segue a estrutura e as convenções esperadas.

• Controle negativo (test-04)
  Este prompt não deve invocar setup-demo-app. É uma solicitação relacionada e comum (“adicione Tailwind a um aplicativo existente”) que pode corresponder involuntariamente à descrição da habilidade (“demonstração com React + Tailwind”). Incluir pelo menos um caso should_trigger=false ajuda a detectar falsos positivos, em que o Codex seleciona a habilidade com facilidade excessiva e cria a estrutura de um novo projeto quando o usuário queria uma alteração incremental em um projeto existente.

Essa combinação é intencional. Algumas avaliações devem confirmar que a habilidade se comporta corretamente quando invocada explicitamente; outras devem verificar se ela é ativada em prompts reais nos quais o usuário nem sequer menciona a habilidade.

À medida que descobrir falhas, prompts que não acionam a habilidade ou casos em que a saída se afasta das suas expectativas, adicione-os como novas linhas. Com o tempo, esse pequeno CSV se torna um registro vivo dos cenários em que a habilidade setup-demo-app deve continuar funcionando corretamente.

Com o tempo, esse pequeno conjunto de dados se torna um registro vivo do que a habilidade deve continuar fazendo corretamente.

5. Comece com avaliadores determinísticos leves

Este é o ponto central da etapa de avaliação: use codex exec --json para que seu harness de avaliação possa pontuar o que realmente aconteceu, e não apenas verificar se a saída final parece correta.

Quando você habilita --json, stdout passa a ser um fluxo JSONL de eventos estruturados. Isso facilita escrever verificações determinísticas diretamente ligadas ao comportamento que importa para você, por exemplo:

• Ele executou npm install?
• Ele criou package.json?
• Ele executou os comandos esperados, na ordem esperada?

Essas verificações são intencionalmente leves. Elas fornecem sinais rápidos e fáceis de interpretar antes de você adicionar qualquer avaliação baseada em modelos.

Um executor mínimo em Node.js

Uma abordagem “boa o suficiente” funciona assim:

1. Para cada prompt, execute codex exec --json --full-auto "<prompt>"
2. Salve o registro de execução JSONL em disco
3. Analise o registro de execução e execute verificações determinísticas sobre os eventos

// evals/run-setup-demo-app-evals.mjs
import { spawnSync } from "node:child_process";
import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
import path from "node:path";

function runCodex(prompt, outJsonlPath) {
  const res = spawnSync(
    "codex",
    [
      "exec",
      "--json", // REQUIRED: emit structured events
      "--full-auto", // Allow file system changes
      prompt,
    ],
    { encoding: "utf8" }
  );

  mkdirSync(path.dirname(outJsonlPath), { recursive: true });

  // stdout is JSONL when --json is enabled
  writeFileSync(outJsonlPath, res.stdout, "utf8");

  return { exitCode: res.status ?? 1, stderr: res.stderr };
}

function parseJsonl(jsonlText) {
  return jsonlText
    .split("\n")
    .filter(Boolean)
    .map((line) => JSON.parse(line));
}

// deterministic check: did the agent run `npm install`?
function checkRanNpmInstall(events) {
  return events.some(
    (e) =>
      (e.type === "item.started" || e.type === "item.completed") &&
      e.item?.type === "command_execution" &&
      typeof e.item?.command === "string" &&
      e.item.command.includes("npm install")
  );
}

// deterministic check: did `package.json` get created?
function checkPackageJsonExists(projectDir) {
  return existsSync(path.join(projectDir, "package.json"));
}

// Example single-case run
const projectDir = process.cwd();
const tracePath = path.join(projectDir, "evals", "artifacts", "test-01.jsonl");

const prompt =
  "Create a demo app named demo-app using the $setup-demo-app skill";

runCodex(prompt, tracePath);

const events = parseJsonl(readFileSync(tracePath, "utf8"));

console.log({
  ranNpmInstall: checkRanNpmInstall(events),
  hasPackageJson: checkPackageJsonExists(path.join(projectDir, "demo-app")),
});

A vantagem aqui é que tudo é determinístico e pode ser depurado.

Se uma verificação falhar, você poderá abrir o arquivo JSONL e ver exatamente o que aconteceu. Cada execução de comando aparece como um evento item.*, na ordem em que ocorreu. Isso facilita explicar e corrigir regressões, que é exatamente o que você quer nesta etapa.

6. Faça verificações qualitativas com o Codex e avaliação baseada em rubricas

As verificações determinísticas respondem à pergunta “ele fez o básico?” , mas não à pergunta “ele fez do jeito que você queria?”

Para habilidades como setup-demo-app, muitos requisitos são qualitativos: a estrutura dos componentes, as convenções de estilo ou se o Tailwind segue a configuração pretendida. É difícil verificar esses aspectos apenas conferindo a existência de arquivos ou contando comandos.

Uma solução pragmática é adicionar uma segunda etapa, com auxílio de um modelo, ao seu pipeline de avaliações:

1. Execute a habilidade de configuração (isso grava código em disco)
2. Execute uma verificação de estilo somente leitura no repositório resultante
3. Exija uma resposta estruturada à qual seu harness possa atribuir uma pontuação de forma consistente

O Codex oferece suporte direto a isso por meio de --output-schema, que restringe a resposta final a um JSON Schema definido por você.

Um pequeno esquema de rubrica

Comece definindo um pequeno esquema que contemple as verificações importantes para você. Por exemplo, crie evals/style-rubric.schema.json:

{
  "type": "object",
  "properties": {
    "overall_pass": { "type": "boolean" },
    "score": { "type": "integer", "minimum": 0, "maximum": 100 },
    "checks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "pass": { "type": "boolean" },
          "notes": { "type": "string" }
        },
        "required": ["id", "pass", "notes"],
        "additionalProperties": false
      }
    }
  },
  "required": ["overall_pass", "score", "checks"],
  "additionalProperties": false
}

Esse esquema fornece campos estáveis (overall_pass, score, resultados de cada verificação) que você pode combinar, comparar e acompanhar ao longo do tempo.

O prompt de verificação de estilo

Em seguida, execute codex exec uma segunda vez para apenas inspecionar o repositório e gerar uma resposta JSON em conformidade com a rubrica:

codex exec \
  "Evaluate the demo-app repository against these requirements:
   - Vite + React + TypeScript project exists
   - Tailwind is configured via @tailwindcss/vite and CSS imports tailwindcss
   - src/components contains Header.tsx and Card.tsx
   - Components are functional and styled with Tailwind utility classes (no CSS modules)
   Return a rubric result as JSON with check ids: vite, tailwind, structure, style." \
  --output-schema ./evals/style-rubric.schema.json \
  -o ./evals/artifacts/test-01.style.json

É aqui que --output-schema se torna útil. Em vez de texto livre, difícil de analisar ou comparar, você recebe um objeto JSON previsível ao qual seu harness de avaliação pode atribuir pontuações ao longo de várias execuções.

Se depois você levar esse conjunto de avaliações para a CI, a GitHub Action do Codex oferece suporte explícito à passagem de --output-schema por meio de codex-args, permitindo exigir a mesma saída estruturada em fluxos de trabalho automatizados.

7. Amplie suas avaliações conforme a habilidade amadurece

Depois de estabelecer o ciclo básico, você pode ampliar suas avaliações nos aspectos mais importantes para a sua habilidade. Comece com pouco e adicione verificações mais aprofundadas apenas quando elas de fato aumentarem a confiança nos resultados.

Alguns exemplos incluem:

• Contagem de comandos e repetições improdutivas: Conte os itens command_execution no registro de execução JSONL para detectar regressões em que o agente começa a entrar em ciclos ou a executar comandos novamente. O uso de tokens também está disponível nos eventos turn.completed.

• Orçamento de tokens: Acompanhe usage.input_tokens e usage.output_tokens para identificar aumentos acidentais no tamanho dos prompts e comparar a eficiência entre versões.

• Verificações de build: Execute npm run build após a conclusão da habilidade. Isso fornece um sinal mais robusto de funcionamento de ponta a ponta e detecta importações com problemas ou ferramentas configuradas incorretamente.

• Verificações básicas em tempo de execução: Inicie npm run dev e faça uma requisição ao servidor de desenvolvimento com curl, ou execute uma verificação leve com Playwright, caso já tenha uma. Use essa abordagem de forma seletiva. Ela aumenta a confiança nos resultados, mas consome tempo.

• Limpeza do repositório: Garanta que a execução não gere arquivos indesejados e que a saída de git status --porcelain esteja vazia (ou corresponda a uma lista explícita de arquivos permitidos).

• Regressões de Sandbox e permissões: Verifique se a habilidade continua funcionando sem elevar as permissões além do que você pretendia. Configurações padrão com privilégio mínimo são ainda mais importantes quando você automatiza.

O padrão é o mesmo: comece com verificações rápidas que expliquem o comportamento e só adicione verificações mais lentas e pesadas quando elas reduzirem o risco.

8. Principais aprendizados

Este pequeno exemplo de setup-demo-app mostra a passagem de “parece melhor” para “há comprovação”: execute o agente, registre o que aconteceu e avalie o resultado com um pequeno conjunto de verificações. Com esse ciclo estabelecido, fica mais fácil confirmar cada ajuste, e cada regressão se torna evidente. Estes são os principais aprendizados:

• Meça o que importa. Boas avaliações tornam as regressões evidentes e as falhas fáceis de explicar.
• Comece com uma definição de conclusão que possa ser verificada. Use $skill-creator para dar os primeiros passos e depois refine as instruções até que não haja ambiguidade sobre o que é sucesso.
• Baseie as avaliações no comportamento. Capture JSONL com codex exec --json e escreva verificações determinísticas para os eventos command_execution.
• Use o Codex quando as regras não forem suficientes. Adicione uma etapa estruturada, baseada em rubrica, com --output-schema para avaliar o estilo e as convenções de forma confiável.
• Deixe que as falhas reais orientem a cobertura. Cada correção manual é um sinal. Transforme-a em um teste para que a habilidade continue acertando.