Escreve prompts eficazes para o Bob Shell adicionando um papel, contexto e exemplos e, em seguida, transforma um pedido vago em código Python documentado com tratamento de erros.

O IBM Bob Shell produz código mais preciso quando o teu prompt indica a tarefa, um papel, contexto e um exemplo. Neste tutorial, transforma um pedido vago num prompt estruturado e compara os resultados.

Pré-requisitos

Bob Shell

Instala o Bob Shell v2.x ou posterior e inicia sessão.

Para confirmar que o Bob Shell está instalado, abre um terminal e verifica a versão:

bob --version

O que é um prompt?

Um prompt é uma pergunta, pedido ou comando que dás ao Bob para obteres o output que queres. Prompts vagos produzem respostas vagas. Um bom prompt é claro, específico e fornece contexto suficiente para que o Bob entenda o que queres.

Componentes de um prompt

Um prompt eficaz combina os seguintes componentes:

Componente	Finalidade	Exemplo
Instrução	Diz ao Bob qual tarefa executar. Instruções fortes reduzem a ambiguidade.	"Gera um software bill of materials (SBOM) para esta API."
Papel	Atribui uma persona para que o Bob adapte a resposta a essa perspetiva.	"És um engenheiro de software sênior com expertise em Python."
Contexto	Adiciona contexto de fundo, como a situação, o público, o tom ou as restrições.	"A função é executada num serviço de produção e deve incluir tratamento de erros."
Exemplo	Mostra o padrão, formato ou estilo que queres que o Bob siga.	"Segue a estrutura de `@src/api/users.py`."
Dica	Introduz a resposta que queres, geralmente no final do prompt.	"Retorna apenas a função, começando com `def`."

Podes guardar os teus prompts como comandos slash personalizados para reutilizar e partilhar com a tua equipa.

O que torna um prompt eficaz?

As seguintes boas práticas podem ajudar-te a escrever prompts eficazes para o Bob.

Sê específico: Quanto mais específico for o teu prompt, melhor o Bob pode entender o que queres. Em vez de perguntar "Como escrevo uma função Python?", pergunta "Como escrevo uma função Python que recebe uma lista de números e retorna a média?"

Fornece contexto: Se o teu prompt for sobre um projeto ou base de código específico, fornece algum contexto sobre isso. Isso ajuda o Bob a gerar uma resposta relevante para a tua situação. Usa referências @, como @src/main.py, para apontar o Bob para ficheiros específicos.

Divide as tarefas: Como farias ao refinar uma tarefa no teu backlog, divide tarefas complexas em etapas menores e mais gerenciáveis. Isso pode ajudar o Bob a gerar respostas mais precisas e focadas.

Inclui exemplos: Se estás a adicionar uma nova API, indica ao Bob que reveja APIs bem escritas na tua base de código para usar como exemplos. Podes também incluir exemplos no teu prompt para mostrar ao Bob o formato ou estilo que queres.

Refinar um prompt vago

Nesta secção, escreves um prompt vago para o Bob e revês o output. Em seguida, refinas o teu prompt com base nas boas práticas para melhorar a qualidade da resposta.

O objetivo é que o Bob gere uma função Python que imprima a data e hora atuais no formato UTC. A função deve estar bem documentada e incluir tratamento de erros.

Abre um terminal e inicia uma sessão interativa no modo Agent:

bob chat --mode agent

Insere o seguinte prompt:

Write a Python function that prints the date and time.

O Bob gera uma resposta, mas pode não satisfazer todos os teus requisitos.

from datetime import datetime

def print_datetime():
    now = datetime.now()
    print(now.strftime("%Y-%m-%d %H:%M:%S"))

A função não tem tratamento de erros e imprime a hora local, não UTC.

Insere /clear para repor o histórico da conversa, para que a primeira resposta não influencie a próxima:

/clear

Refina o teu prompt com os componentes de prompt:

Papel: "És um engenheiro de software sênior com expertise em Python 3."
Instrução: "Escreve uma função Python 3 que imprime a data e hora atuais no formato UTC."
Contexto: "A função deve estar bem documentada e incluir tratamento de erros."
Exemplo: Aponta o Bob para uma fonte autoritativa, como as boas práticas de tratamento de exceções do Real Python.

Insere o prompt refinado:

You are a senior software engineer with expertise in Python 3. 
Write a Python 3 function that prints the current date and time in UTC format. 
The function should be well documented and include error handling, 
modeled after https://realpython.com/ref/best-practices/exception-handling/.

"""
utc_datetime.py — Utility for printing the current UTC date and time.
"""

from datetime import datetime, timezone

def print_utc_datetime() -> None:
    """Print the current date and time in UTC (ISO 8601 format).

    Retrieves the current moment from the system clock, attaches UTC timezone
    info, formats it as an ISO 8601 string, and writes it to stdout.

    Returns:
        None

    Raises:
        OSError: If the system clock cannot be read (e.g., hardware failure or
            OS-level permission restrictions).
        ValueError: If datetime formatting unexpectedly fails (e.g., year out
            of the supported range).

    Example:
        >>> print_utc_datetime()
        Current UTC date and time: 2025-07-15T13:42:00.123456+00:00
    """
    try:
        now_utc: datetime = datetime.now(tz=timezone.utc)
    except OSError as exc:
        # System clock is unavailable or inaccessible.
        raise OSError("Failed to read the system clock.") from exc

    try:
        formatted: str = now_utc.isoformat()
    except ValueError as exc:
        # Extremely unlikely, but guard against out-of-range datetime values.
        raise ValueError(
            f"Failed to format the datetime object: {now_utc!r}"
        ) from exc

    print(f"Current UTC date and time: {formatted}")


if __name__ == "__main__":
    print_utc_datetime()

O prompt refinado produz uma função que usa UTC, inclui docstrings e trata exceções.

IBM SkillsBuild

IBM SkillsBuild é uma plataforma de aprendizagem online gratuita com cursos sobre como escrever prompts eficazes para assistentes de IA como o Bob.

Para saber mais sobre a escrita eficaz de prompts, faz o curso Craft Precise Prompts for AI Models.

Próximos passos

Neste tutorial, aprendeste os componentes de um prompt eficaz e refinaste um prompt vago num que produz de forma fiável o output que queres.

Avança para Criar e usar skills para transformar um prompt bem escrito num workflow reutilizável e repetível que o Bob pode aplicar automaticamente.

Escrever prompts eficazes para o Bob Shell