Justificativa: Definir uma persona especialista força o modelo a adotar vocabulário, tom e profundidade adequados ao domínio de Product Management.
Aplicação:
Você é uma Product Manager Sênior especializada em transformar bug reports em user stories acionáveis.
Isso garante respostas com tom profissional, centradas no usuário e com foco em valor de negócio — ao invés de respostas genéricas de assistente.
Justificativa: Bugs complexos exigem análise em etapas (identificar problema → persona → fatos → critérios → revisão). O CoT força o modelo a seguir esse roteiro antes de responder, reduzindo omissões e inconsistências.
Aplicação:
Aplique Chain of Thought (CoT) internamente antes de responder.
Roteiro interno obrigatório:
1) Identifique o problema principal e o impacto no usuário/negócio.
2) Identifique a persona correta.
3) Liste TODOS os fatos explícitos relevantes.
4) Defina critérios de aceitação observáveis e testáveis.
5) Para bugs médios/complexos, inclua soluções técnicas padrão.
6) Revise: não há conteúdo duplicado?
Regra crítica: nunca exponha seu raciocínio interno.
O passo 6 (revisão anti-duplicação) foi adicionado após feedbacks de avaliação que detectaram seções e critérios repetidos.
Justificativa: Exemplos concretos de entrada/saída calibram o modelo melhor do que instruções abstratas. Incluímos 5 exemplos cobrindo as 3 faixas de complexidade.
Aplicação: 5 pares bug_report → user_story no campo examples:
| # | Bug | Complexidade | Formato demonstrado |
|---|---|---|---|
| 1 | Botão de carrinho não funciona | Simples | User story + 5 critérios Dado/Quando/Então |
| 2 | Webhook de pagamento com HTTP 500 | Média | + Contexto Técnico |
| 3 | Relatório lento (>120s) | Média | + Contexto Técnico com metas |
| 4 | Cálculo de desconto errado | Média | + Exemplo de Cálculo |
| 5 | App Android trava com 50+ itens | Média | + Critérios Técnicos + Contexto do Bug |
Justificativa: Definir a estrutura exata da resposta (seções, ordem, formato) evita respostas desestruturadas e facilita avaliação automática.
Aplicação: Três templates de formato conforme complexidade:
- Simples: User story + Critérios de Aceitação (5 bullets)
- Média: User story + Critérios + Seções extras nomeadas (Contexto Técnico, Acessibilidade, etc.)
- Complexa:
=== USER STORY PRINCIPAL ===→=== CRITÉRIOS DE ACEITAÇÃO ===(A/B/C/D) →=== CRITÉRIOS TÉCNICOS ===→=== CONTEXTO DO BUG ===→=== TASKS TÉCNICAS SUGERIDAS ===→=== MÉTRICAS DE SUCESSO ===
Justificativa: Restrições explícitas eliminam os erros mais frequentes detectados durante as iterações de avaliação.
Aplicação — Restrições-chave:
| Restrição | Problema que resolve |
|---|---|
| "PROIBIDO DUPLICAR: nunca criar duas seções com o mesmo nome" | Seções "Contexto Técnico" duplicadas (clarity 0.63) |
| "Preservar valores EXATAMENTE como escritos no bug" | "1000" virando ">1000" (precision 0.75) |
| "Consistência interna: mesmo valor em toda a resposta" | "1 segundo" vs "2 segundos" contraditório (clarity 0.82) |
| "Escopo restrito ao bug: cada critério endereça o problema reportado" | Log de auditoria adicionado em bug de UI (precision 0.89) |
| "Critérios específicos: endpoint, HTTP, status DEVEM aparecer" | Webhook genérico sem HTTP 200/status (completeness 0.65) |
| "Bugs de integração: cobrir fluxo completo" | Critérios vagos em bugs de webhook/API |
- Prompt otimizado (v2) no LangSmith Hub: https://smith.langchain.com/hub/wduqu001/bug_to_user_story_v2
- Dataset de avaliação no LangSmith: https://smith.langchain.com/public/b49bebf7-0a17-472b-aa7f-9df5c0ffac8b/d
- Repositório GitHub: https://github.com/wduqu001/ia-pull-evaluation-prompt
| Métrica | v1 (prompt original) | v2 (prompt otimizado) | Delta |
|---|---|---|---|
| Acceptance Criteria Score | 0.59 | 0.95 | +0.36 |
| Clarity | 1.00 | 0.99 | -0.01 |
| Completeness Score | 0.79 | 0.96 | +0.17 |
| F1 Score | 0.60 | 0.84 | +0.24 |
| Precision | 0.93 | 0.99 | +0.06 |
| Tone Score | 0.91 | 0.98 | +0.07 |
| User Story Format Score | 0.94 | 0.97 | +0.03 |
| Média Geral | 0.82 | 0.96 | +0.14 |
- Modelo utilizado foi o gemini-2.5-flash
Os resultados completos com scores detalhados por exemplo estão disponíveis no dashboard do LangSmith.
| Iteração | Problema identificado | Ação tomada | Impacto |
|---|---|---|---|
| 1 | F1:0.00 no exemplo 1 — extract_json_from_response falhava quando LLM envolvia JSON em code fences (```json ) |
Adicionado strip de markdown code fences antes do parse em metrics.py |
F1 do exemplo 1 corrigido (0.00→1.00) |
| 2 | Clarity 0.72 — avaliador detectou: termos em inglês ("succeed", "timeout"), prolixidade/redundância entre seções, valores numéricos inventados (z-index 1100 vs >1050), falta de critérios de acessibilidade (ESC, backdrop) e reserva de estoque com tempo limite | Adicionados princípios: responder inteiramente em português; concisão (não repetir conceito entre seções); não inventar valores numéricos; regras para UI/UX (fechar com ESC, clicar fora, foco automático); regras para concorrência/estoque (reserva temporária com tempo limite) | Clarity subiu, Precision subiu |
| 3 | CoT step 5 mandava inferir funcionalidades não solicitadas (email, log) | Removido; escopo restrito ao bug | Precision subiu |
| 4 | Bugs complexos tinham user story duplicada (texto + seção === USER STORY PRINCIPAL ===) |
Formato complexo começa direto na seção, sem texto antes | Clarity subiu |
| 5 | Valores do bug alterados (1000→>1000), seções duplicadas, tempos contraditórios | Regras de fidelidade exata, anti-duplicação de nomes, consistência interna | Precision e Clarity subiram |
| 6 | Webhook genérico sem detalhes técnicos (HTTP 200, status, endpoint) | Regra de especificidade + regra de integração (fluxo completo) | Completeness subiu |
- Python 3.9+
- Conta no LangSmith com API Key
- API Key da OpenAI ou Google Gemini
# Clonar o repositório
git clone https://github.com/wduqu001/ia-pull-evaluation-prompt.git
cd ia-pull-evaluation-prompt
# Criar e ativar ambiente virtual
python3 -m venv venv
source venv/bin/activate
# Instalar dependências
pip install -r requirements.txt
# Configurar variáveis de ambiente
cp .env.example .env
# Editar .env com suas API keys# 1. Pull do prompt original (v1)
python src/pull_prompts.py
# 2. Push do prompt otimizado (v2)
python src/push_prompts.py
# 3. Avaliação
python src/evaluate.py
# 4. Testes de validação
pytest tests/test_prompts.py- Dataset de avaliação (20 exemplos): Acessar dataset
- Prompt público v2: Acessar prompt
- Execuções dos prompts v1 (ruins) com notas baixas e v2 (otimizados) com notas ≥ 0.9 estão visíveis no dashboard
- Tracing detalhado disponível para todos os exemplos avaliados
- Bug técnico (
metrics.py):extract_json_from_responseagora remove markdown code fences (```json...```) antes de parsear. Isso resolve o F1:0.00 no exemplo 1 onde precision=1.0 e recall=1.0 estavam sendo descartados. - Novo método de avaliação: Criado
run_official_evaluation()para registrar avaliadores e experimentos no dashboard do LangSmith.