Programação em par com IA com o IBM Bob

Inicie o IBM Bob

Inicie o IBM Bob IDE.

Abra a interface de chat do Bob

Se a interface de chat do Bob não estiver visível, abra-a selecionando o ícone do Bob ao lado da barra de navegação. Você também pode pressionar Option + Command + B no Mac, ou Ctrl + Alt + B no Windows e Linux.

Abra uma pasta de projeto vazia

Crie uma pasta vazia chamada todo-api, depois abra-a no Bob com File > Open Folder. Se o Bob perguntar se você confia nos autores dos arquivos na pasta, selecione Yes, I trust the authors.

O Bob grava o aplicativo gerado nesta pasta. Você não precisa de um repositório existente para este tutorial.

Desative a aprovação automática

Abra Permissions e confirme que a aprovação automática está desativada. Com a aprovação automática desligada, o Bob solicita sua permissão antes de ler arquivos, editar arquivos ou executar comandos. Você mantém o controle de cada alteração neste tutorial.

Mude para o modo Plan

Abra o dropdown de modos na parte inferior da barra lateral do Bob e selecione Plan.

Modes aplicam o princípio do menor privilégio. No modo Plan, o Bob lê seu código e escreve um plano em Markdown. O Bob não executa comandos nem faz alterações de implementação. Você revisa a abordagem antes de o Bob escrever qualquer código da aplicação.

Defina os requisitos do aplicativo

Na interface de chat do Bob, insira o seguinte prompt:

Create a simple FastAPI To-Do API.

Requirements:

- Store tasks in a Python list.
- Each task should contain:
    - id
    - task_name

Implement these endpoints with explicit HTTP status codes:

- GET /tasks: list all tasks. Return 200.
- POST /tasks: create a task from a JSON body containing only task_name. Return 201 with the created task.
- DELETE /tasks/{task_id}: delete a task. Return 204 on success and 404 if no task has that id.

Use FastAPI and Pydantic. Use Pydantic model validation so an invalid request body returns 422.

Include a requirements.txt and a Dockerfile. The Dockerfile must start Uvicorn bound to 0.0.0.0 on port 8000 so the API is reachable through a published container port.

Save the plan as Markdown files in a folder named `plans`.

Put the FastAPI application in a single file named `main.py` at the project root.

Keep the implementation simple.

Don't install any dependencies locally or run local tests. Everything will run in a Docker container.

Para construir o plano, o Bob executa sua skill de planejamento. Quando solicitado, selecione Approve skill tools for task e Approve subagent tools for task para que o Bob possa explorar o workspace e elaborar o plano.

Refine o plano

Você pode alterar o plano antes que o Bob escreva qualquer código. Na interface de chat do Bob, insira um prompt de acompanhamento:

Update the plan to reject a task whose task_name is empty or longer than 200 characters.

O Bob revisa o plano para incluir a validação de entrada extra. Revise o plano atualizado.

Revise o plano

O Bob apresenta um plano ordenado e pode salvá-lo como um arquivo Markdown no projeto. Revise-o antes de continuar:

• Escopo: o plano cobre cada endpoint e a regra de validação que você adicionou, e nada que você não solicitou.
• Arquivos nomeados: cada etapa nomeia o arquivo que cria ou altera.
• Linguagem vaga: frases como "handle errors appropriately" escondem suposições. Peça ao Bob que as torne específicas.

Você mantém a responsabilidade por essas decisões de design. O Bob não implementa nada até você mudar para o modo Agent em Gere e revise o aplicativo.

Inicie uma nova janela de contexto

Selecione New task na caixa de chat ou + no topo do painel de chat para iniciar uma nova janela de contexto. Consulte Criar uma nova janela de contexto para mais contexto. O Bob salvou o plano na pasta plans, então você não precisa mais da conversa de planejamento no contexto. Um contexto limpo mantém a implementação focada no plano aprovado.

Mude para o modo Agent e execute o plano

Abra o dropdown de modos na parte inferior da barra lateral do Bob e selecione Agent. Depois, diga ao Bob para implementar o plano:

Implement the plan in the plans folder.
@plans/

O modo Agent permite que o Bob escreva arquivos e execute comandos. O Bob solicita aprovação antes de cada alteração porque você desativou a aprovação automática. Aprove as etapas conforme o Bob avança pelo plano.

Revise o aplicativo gerado

Quando a implementação estiver concluída, revise o código gerado. Como a saída do Bob é probabilística, o estilo de código e os nomes internos podem diferir dos exemplos mostrados aqui. O aplicativo consiste nas seguintes partes.

Modelos de dados. O Bob gera dois modelos Pydantic: um para o corpo da requisição ao criar uma tarefa e outro para uma tarefa armazenada. O modelo de criação aplica a regra de comprimento que você adicionou durante o planejamento:

class TaskCreate(BaseModel):
    task_name: Annotated[str, Field(min_length=1, max_length=200)]


class Task(BaseModel):
    id: int
    task_name: str

Os caminhos dos endpoints e os códigos de status correspondem aos requisitos fornecidos ao Bob, mas os nomes das classes de modelo e o layout dos arquivos podem variar. Este tutorial assume os modelos Task e TaskCreate. Ajuste os prompts a seguir se o Bob tiver escolhido nomes diferentes.

Armazenamento de dados em memória. O Bob armazena tarefas em uma lista Python vazia e atribui a cada nova tarefa um id incremental:

tasks: list[dict] = []
id_counter = 0

Operações da API. O aplicativo fornece os seguintes endpoints:

• GET /tasks
• POST /tasks
• DELETE /tasks/{task_id}

POST /tasks recebe apenas task_name no corpo da requisição e retorna 201 com a tarefa criada. DELETE /tasks/{task_id} retorna 204 em caso de sucesso e 404 quando nenhuma tarefa possui aquele task_id.

Dependências. O Bob gera um arquivo requirements.txt que lista FastAPI, Uvicorn e Pydantic.

Container. O Bob gera um Dockerfile que instala as dependências e executa a API na porta 8000 com Uvicorn.

O contrato HTTP segue o prompt de requisitos, incluindo métodos, caminhos e códigos de status. As seguintes etapas de validação se aplicam como descritas.

Abra o arquivo do aplicativo

Abra o arquivo main.py que o Bob gerou e posicione o cursor em uma linha vazia no final do arquivo, após o último route handler.

Ative o modo literate coding

Pressione Command + I no Mac, ou Ctrl + I no Windows e Linux. Você também pode selecionar o ícone de varinha mágica na barra de ferramentas do editor.

Escreva a instrução

Insira a seguinte instrução na linha vazia. Ela aparece destacada em uma cor diferente do restante do código.

Add a PUT /tasks/{task_id} endpoint that updates the task_name of an existing task, matching the style and conventions of the existing routes. Return 200 with the updated task, or 404 if no task has that id.

O Bob infere o nome do parâmetro, o modelo de requisição e o tratamento de erros a partir do código ao redor, então você só precisa especificar o método e o caminho.

Gere e aceite o código

Selecione Generate, ou pressione Command + Enter no Mac, ou Ctrl + Enter no Windows e Linux. O Bob substitui sua instrução por uma implementação e mostra um diff inline.

Revise o diff e, em seguida, selecione Accept All para aplicar a alteração. Pressione Command + I no Mac, ou Ctrl + I no Windows e Linux novamente para sair do modo literate coding.

Peça ao Bob para explicar o código

Inicie uma nova janela de contexto com New task e, em seguida, selecione Ask no dropdown de modos. O modo Ask responde perguntas e analisa código sem editar arquivos. Use-o quando quiser uma explicação sem alterações.

Entender o código gerado é uma parte importante da programação em par com IA. Pergunte ao Bob:

Explain the generated To-Do API.

O Bob pode explicar a arquitetura do aplicativo, o fluxo de dados, os componentes do FastAPI, os modelos Pydantic, o comportamento dos endpoints e as decisões de design. Use a explicação para confirmar que o código faz o que você espera antes de alterá-lo ou estendê-lo.

Execute o aplicativo

Volte para o modo Agent para que o Bob possa executar comandos. Peça ao Bob para construir e executar a API em um container:

Build the Docker image and run the container with port 8000 mapped to the host. Confirm the API is reachable.

O Bob executa os comandos de build e inicialização e informa quando o container está em execução.

Abra http://localhost:8000/docs no seu navegador.

O FastAPI serve uma interface Swagger UI interativa em /docs. Use-a para explorar cada endpoint, inspecionar esquemas de requisição e resposta, e executar chamadas de API pelo navegador.

Valide a API

Use o Swagger UI em /docs para exercitar cada operação. Para cada endpoint:

1. Expanda sua linha e selecione Try it out.
2. Insira quaisquer parâmetros de caminho ou corpo da requisição.
3. Selecione Execute.
4. Verifique o código e o corpo da Server response.

Adicionar uma tarefa

1. Expanda POST /tasks e selecione Try it out.

2. Substitua o corpo da requisição por:

   {
     "task_name": "My first API item!"
   }

3. Selecione Execute. Confirme que o código de resposta é 201 e que o corpo da resposta mostra a tarefa criada com um id atribuído.

Recuperar tarefas

1. Expanda GET /tasks e selecione Try it out.
2. Selecione Execute. Confirme que o código de resposta é 200 e que o corpo da resposta lista a tarefa My first API item! com o id atribuído quando você a adicionou.

Atualizar uma tarefa

1. Expanda PUT /tasks/{task_id} e selecione Try it out.

2. Insira o task_id da tarefa que você criou.

3. Substitua o corpo da requisição por:

   {
     "task_name": "Build and ship a To-Do API"
   }

4. Selecione Execute. Confirme que o código de resposta é 200 e que a tarefa retornada mostra o task_name atualizado.

5. Altere task_id para um valor que não existe e selecione Execute novamente. Confirme que o código de resposta é 404.

Excluir uma tarefa

1. Expanda DELETE /tasks/{task_id} e selecione Try it out.
2. Insira o task_id da tarefa que você criou e selecione Execute. Confirme que o código de resposta é 204.
3. Expanda GET /tasks, selecione Execute e confirme que a tarefa não aparece mais na resposta.
4. Expanda DELETE /tasks/{task_id} novamente, insira o mesmo task_id e selecione Execute. Confirme que o código de resposta é 404.

A implementação atende aos requisitos originais, incluindo o endpoint de atualização que você adicionou com literate coding.

Peça sugestões de melhoria ao Bob

Inicie uma nova janela de contexto com New task e, em seguida, insira:

Review the To-Do API and suggest improvements to code quality, error handling, and HTTP status codes.

O Bob identifica lacunas como um endpoint ausente para recuperar uma única tarefa, um armazenamento em memória que contém dicionários simples em vez de modelos Task validados, e um id_counter no nível do módulo que é difícil de redefinir ou testar.

Aplique as melhorias

Peça ao Bob para implementar as sugestões que você deseja manter:

Add a GET /tasks/{task_id} endpoint that returns 404 when the task ID does not exist, and store tasks as Task models instead of dictionaries.

Revise as alterações propostas e aprove para aplicá-las. Peça ao Bob para reconstruir a imagem e reiniciar o container e, em seguida, repita as etapas de validação. Confirme que GET /tasks/{task_id} retorna 200 com a tarefa para um ID válido e 404 para um ID desconhecido, e que os endpoints existentes ainda se comportam como antes.

Gere testes unitários

Inicie uma nova janela de contexto com New task e, em seguida, pergunte ao Bob:

Generate pytest unit tests for this application. Add pytest and httpx to a dev requirements file, build a test image, and run the suite in a container.

O Bob adiciona as dependências de teste pytest e httpx, constrói uma imagem que as inclui, executa o conjunto de testes em um container e reporta os resultados. Executar os testes em um container significa que você não precisa de um ambiente Python local. Revise e refine os testes gerados.

A revisão e manutenção dos testes gerados permanecem de sua responsabilidade.

Gere documentação técnica

Pergunte ao Bob:

Generate technical documentation for this To-Do API.

O Bob pode gerar uma visão geral do aplicativo, descrição da arquitetura, resumos de endpoints, exemplos de requisição e resposta, e instruções de uso. Esta documentação complementa a documentação da API que o FastAPI gera automaticamente.