# [Arquivado] Guia do Engenheiro: Pair Programming com IA

> **Doc histórica — sem substituto direto.**
> Para o fluxo atual de pair programming e continuidade, veja [`../4-agentes/deyvin.md`](../4-agentes/deyvin.md) e [`../2-comecar/projeto-existente.md`](../2-comecar/projeto-existente.md).
> Conteúdo abaixo preservado para referência histórica.

---

# Guia do Engenheiro: Pair Programming com IA

> Baseado na metodologia de Fabio Akita — ["Do Zero à Pós-Produção em 1 Semana"](https://akitaonrails.com/2026/02/20/do-zero-a-pos-producao-em-1-semana-como-usar-ia-em-projetos-de-verdade-bastidores-do-the-m-akita-chronicles/)

Este guia não é sobre agentes — é sobre **como você trabalha com eles**. A diferença entre um desenvolvedor que usa IA com eficiência e um que perde tempo é quase sempre a qualidade das instruções e a disciplina do processo, não a IA em si.

---

## O mito do one-shot prompt

Você não vai resolver um problema real de software com um único prompt bem construído. Isso é mito.

A IA é como um programador extremamente esforçado que:
- Executa ordens explícitas e sem ambiguidade com alta precisão
- Comete erros frequentes quando as instruções são vagas
- Não conhece o seu negócio, seu cliente, sua história de decisões
- Toma decisões arquiteturais ruins sem contexto suficiente
- Perde o fio da meada em sessões longas sem documentação

**A sua spec é a sua proteção.** Quando algo der errado — e vai dar — a primeira pergunta não é "a IA errou?", mas: "minha instrução estava clara o suficiente?"

---

## Squad mode vs Engineer mode

O AIOSON oferece dois modos de trabalho. Escolha o que se encaixa no momento:

| | Squad mode | Engineer mode |
|---|---|---|
| **O que é** | Pipeline sequencial de agentes | Pair programming iterativo |
| **Quando usar** | Greenfield, times, iniciantes, feature grande | Dev experiente com visão clara do que fazer |
| **Documento central** | `discovery.md` → `architecture.md` → `prd.md` | `spec.md` (vivo, evolui com o projeto) |
| **Cadência** | Feature completa por ciclo de agentes | Passos atômicos, commit por passo |
| **Ideal para** | "Não sei exatamente o que o projeto precisa" | "Sei o que preciso, quero executar rápido" |

Os dois modos **coexistem**. Você pode usar o squad para descobrir e arquitetar, depois usar o engineer mode para implementar rapidamente.

---

## O spec.md: a spec viva

O `spec.md` é o documento mais importante para projetos que duram mais de uma sessão. É o único que evolui — os outros são estáticos.

### Por que não o project.context.md?

`project.context.md` captura o **início** do projeto: stack, classificação, framework. Não muda.

`spec.md` captura o **presente**: o que está feito, o que está em andamento, as decisões tomadas hoje, os bloqueios atuais. Muda toda sessão.

### Quando usar

- Projetos SMALL e MEDIUM que duram mais de um dia
- Quando você para e retoma o projeto dias depois
- Quando há decisões técnicas que precisam ser preservadas entre sessões

### Como manter

1. Crie via `/aioson:agent:setup` (o agente vai perguntar) ou manualmente
2. Atualize ao final de cada sessão com `*update-spec`
3. Releia no início de cada sessão antes de qualquer prompt

O `spec.md` fica em `.aioson/context/spec.md` e **não é obrigatório** — para projetos MICRO e sessões curtas, não precisa.

---

## O ritual de sessão

A diferença entre sessões produtivas e sessões onde você "ficou dando voltas" quase sempre está no início.

### Início (2 minutos)

```
1. Ler project.context.md
2. Ler spec.md (se existir)
3. Definir UMA coisa a fazer nessa sessão
4. Escrever em texto simples o que espera ao final
```

Não comece sem saber onde quer chegar. "Vou trabalhar no projeto" não é um objetivo.

### Durante

- Um passo de cada vez
- Valide antes de avançar
- Commite cada passo que funciona
- Documente decisões no spec.md enquanto estão frescas

### Fim (3 minutos)

```
1. Resumir o que foi feito
2. Listar o que ficou pendente
3. Digitar *update-spec para o @orchestrator atualizar o spec.md
4. Fazer o commit final se necessário
```

---

## Anatomia de uma instrução eficaz

### Prompt ruim

```
Crie o sistema de notificações
```

Por que é ruim: deixa tudo em aberto — onde fica o código, que tipo de notificação, qual padrão seguir, o que não criar. A IA vai inventar.

### Prompt bom

```
Preciso criar um Job chamado SendNotificationJob em app/Jobs/ que usa a
interface NotificationChannel (já existe em app/Contracts/). O job deve
receber $userId e $message, buscar o usuário via User::find(), e chamar
$channel->send($user, $message). Deve implementar ShouldBeUnique com
uniqueId() baseado em $userId. Não crie nenhuma migration nem modifique
o model User.
```

Por que é bom: localização exata, dependências nomeadas, comportamento esperado, e o que **não** fazer.

### Template para qualquer instrução

```
Preciso [ação] chamado [nome] em [localização].
Deve [comportamento esperado].
Depende de: [dependências existentes].
Não crie/modifique: [o que está fora do escopo].
```

---

## A checklist de clarificação (antes de codar)

Use isso antes de pedir implementação de qualquer feature:

```
[ ] O que exatamente precisa ser feito? (comportamento esperado)
[ ] Quem usa isso? (contexto de usuário/ator)
[ ] Qual o critério de "pronto"? (definição de done)
[ ] Isso quebra algo existente? (impacto)
[ ] Existe uma forma mais simples? (YAGNI check)
[ ] Quais arquivos/classes serão criados ou modificados?
[ ] Precisa de migration? Job? Event?
[ ] O padrão está alinhado com o architecture.md?
```

Se você não consegue responder todas, pergunte ao @analyst antes de ir para @dev.

---

## Execução atômica

A instrução ao @dev foi incorporada ao agente, mas o conceito vale para qualquer interação:

**Regra:** Um passo de cada vez. Valide antes de avançar.

```
Sessão típica com @dev:

[você] Próximo passo: criar a migration da tabela appointments.
[dev]  Migration criada. [mostra código]
[você] OK. Próximo: criar o model Appointment com os relacionamentos.
[dev]  Model criado. [mostra código]
[você] OK. Próximo: criar o CreateAppointmentAction.
```

Nunca: "Crie a migration, o model, a action, o controller e os testes."

Por quê? Porque se a action estiver errada, você vai ter que refazer o controller e os testes junto. E a IA vai misturar decisões entre os arquivos de formas que você não pediu.

---

## Quando a IA diverge do esperado

1. **Não discuta** — corrija com precisão
2. Errado: "Isso não está certo, tente de novo"
3. Certo: "Você criou a classe em `app/Services/` mas o padrão deste projeto é `app/Domain/{Modulo}/Services/`. Mova para lá."
4. Se acontecer duas vezes, adicione uma regra explícita ao `spec.md` ou `architecture.md`

---

## Vigilância permanente

Estas áreas exigem revisão sua — não delegue cegamente:

| Área | Por quê revisar |
|---|---|
| Segurança | Auth, autorização, sanitização: a IA não conhece seu modelo de ameaças |
| Performance | N+1 queries, falta de índices, cache ausente |
| Concorrência | Race conditions em Jobs, falta de locks |
| Arquitetura global | A IA vê o arquivo, não o sistema. Você vê o todo |
| Regras de negócio edge cases | Ela não conhece seu cliente como você |

Estas áreas são confiáveis para delegação:

| Área | Por quê confiar |
|---|---|
| Boilerplate com padrão definido | Sem ambiguidade, resultado previsível |
| Transformações de dados com spec clara | Input/output bem definidos |
| Testes unitários para lógica delimitada | Escopo fechado |
| Refactoring com instrução precisa | "Mova X para Y seguindo o padrão Z" |
| Documentação de código existente | Não há o que inventar |

---

## Métricas que importam

Ao final de um projeto ou sprint:

| Métrica | O que revela |
|---|---|
| Features em produção estáveis | Qualidade real do processo |
| Retrabalho por sessão | Clareza das instruções |
| Decisões documentadas no spec.md | Maturidade do processo |
| Commits por sessão | Cadência de entrega |

Uma feature bem feita vale mais que dez features quebradas.

---

## Veja também

- [Cenários práticos](./cenarios.md) — exemplos por stack com todos os agentes
- [Guia de agentes](./agentes.md) — o que cada agente faz
- [Início rápido](./inicio-rapido.md) — primeiros passos
