boostprompt

O BoostPrompt conduz o levantamento de requisitos com perguntas adaptativas, alternativas, trade-offs e recomendações. Ao final, ele organiza as decisões em um prompt Markdown único, autocontido, com requisitos, decisões, critérios de aceite e plano de execução.

Landing page

O projeto inclui uma landing page estática e imersiva em site/, com narrativa de scroll e uma cena 3D carregada apenas em dispositivos compatíveis. Para executá-la localmente:

cd site
npm install
npm run dev

Enquanto este repositório pertencer a AirtonLira, a publicação via GitHub Pages fica em https://airtonlira.github.io/boostprompt.

Você pode usar o projeto de duas formas independentes:

• CLI/TUI local: uma aplicação interativa com sessões persistidas localmente em DuckDB;
• Skills para Claude Code e Codex: discovery conduzido diretamente na conversa do seu harness.

O que o BoostPrompt oferece

• Entrevistas de discovery com 30 a 50 perguntas, adaptadas às respostas anteriores;
• dois modos de saída: prompt_desenvolvimento e roteiro_perguntas_cliente;
• retomada de sessões e continuação de entrevistas concluídas;
• geração e persistência de prompts de implementação em Markdown;
• resumo estruturado para manter o contexto compacto em sessões longas;
• painel de qualidade com métricas locais de cobertura, clareza das decisões e prontidão do prompt;
• pesquisa técnica opcional via Exa, com fontes auditáveis;
• integração com endpoints compatíveis com a API da OpenAI, LiteLLM e OpenAI;
• skills instaláveis para Claude Code e Codex.

Escolha o caminho certo

Sumário

• CLI/TUI local
  • Pré-requisitos
  • Instalação
  • Configuração do modelo
  • Iniciar a aplicação
  • Fluxo de uma sessão
  • Persistência e retomada
  • Pesquisa técnica
• Skills para Claude Code e Codex
  • Instalar as skills
  • Usando no Claude Code
  • Usando no Codex
  • Comportamento esperado
• Desenvolvimento
• Estrutura do projeto
• Contribuição
• Licença

1. CLI/TUI local

Pré-requisitos

• Python 3.11 ou superior;
• uv;
• um endpoint compatível com a API da OpenAI e sua credencial, como LiteLLM, OpenRouter, vLLM ou a própria OpenAI.

Instalação

Na raiz do repositório, instale as dependências:

uv sync --extra dev

Copie o arquivo de exemplo e configure as credenciais:

cp .env.example .env

O arquivo .env é carregado automaticamente, sem sobrescrever variáveis já exportadas no shell. Ele não deve ser versionado.

Configuração do modelo

Para usar LiteLLM, configure:

LLM_MODEL=gpt-4o-mini
LLM_BASE_URL=http://localhost:4000/v1
LLM_API_KEY=sua-chave-litellm

Também são aceitos os nomes legados LITELLM_BASE_URL e API_KEY.

Para usar a OpenAI diretamente, configure OPENAI_API_KEY e, opcionalmente, OPENAI_MODEL e OPENAI_BASE_URL.

Variáveis úteis:

Iniciar a aplicação

uv run boostprompt

Ao iniciar, escolha Usar LiteLLM ou Usar OpenAI. Depois, use o menu para criar uma sessão, listar sessões salvas ou retomar uma sessão pelo código BP-AAAA-NNN.

Fluxo de uma sessão

1. Escolha o provedor do modelo.
2. Escolha Nova sessão.
3. Informe um nome identificável.
4. Escolha o modo de saída.
5. Descreva a demanda inicial.
6. No modo prompt_desenvolvimento, responda uma pergunta por vez. A aplicação fará entre 30 e 50 perguntas adaptadas às respostas anteriores.
7. Depois de dez respostas, selecione Gerar prompt agora para salvar um rascunho sem encerrar a entrevista.
8. Ao final, selecione Gerar/abrir Markdown para visualizar e salvar o prompt mestre de implementação.

Cada interação é persistida automaticamente; não há botão de salvar.

Métricas e histórico

O painel de qualidade acompanha três métricas locais e determinísticas: cobertura do contexto, clareza das decisões e prontidão do prompt. O histórico de sessões mostra a última prontidão calculada e a data da atualização. O modo roteiro_perguntas_cliente não recebe nota, pois não executa uma entrevista.

Persistência e retomada

O banco padrão é data/boostprompt.db. Ele armazena:

• metadados da sessão e contadores de perguntas exibidas e respostas confirmadas;
• respostas do usuário e perguntas/respostas dos agentes;
• snapshots de contexto e decisões;
• referências de pesquisa;
• resumo estruturado do histórico antigo;
• Markdown final gerado.

Ao retomar uma sessão, a aplicação carrega as mensagens recentes e um resumo com objetivo, fatos confirmados, decisões, restrições, riscos e pendências.

Ao abrir uma sessão concluída, a aplicação exibe o resumo e oferece Continuar em nova entrevista. A continuação cria outra sessão com um novo código e usa apenas o resumo estruturado da anterior, preservando o histórico original e mantendo o contexto do modelo compacto.

O arquivo exportado fica em:

output/<nome_da_sessão>_prompt_mestre.md

Pesquisa técnica

Para pesquisas técnicas, a CLI/TUI usa a API da Exa quando EXA_API_KEY está configurada. A pesquisa é planejada somente para decisões externas e mutáveis, prioriza fontes oficiais ou primárias e preserva URL, data, trecho e decisão fundamentada. Se a Exa estiver indisponível, a entrevista continua em modo degradado sem inventar fontes.

2. Skills para Claude Code e Codex

As skills mantêm a mesma regra de discovery e os mesmos modos da CLI, mas funcionam inteiramente na conversa do harness. Elas não usam o banco DuckDB da TUI nem recuperam sessões locais: o histórico é o da própria conversa do Claude Code ou Codex.

Instalar as skills

O instalador copia a skill correta e configura o MCP remoto exa para o harness escolhido:

# Claude Code e Codex
uv run python install.py --harness both

# Somente Claude Code
uv run python install.py --harness claude

# Somente Codex
uv run python install.py --harness codex

O instalador exige somente o executável do harness no PATH.

Para instalar ou atualizar somente a skill, sem alterar a configuração MCP:

uv run python install.py --harness both --skip-mcp

Para conferir as ações sem modificar nada:

uv run python install.py --harness both --dry-run

Onde cada skill é instalada: