Blog

Quando você está tocando vários projetos ao mesmo tempo, o gargalo muda toda hora: contexto, revisão, QA, alinhamento de protótipo, "onde está aquela rota?", "qual componente é o certo?", "qual é o padrão do repo?", etc.

Na prática, agentes de IA (como o Codex) podem acelerar muito, mas só quando a esteira está organizada. Sem insumo bom e sem guard-rails, você só troca "tempo de implementação" por "tempo de correção + review + retrabalho".

Este playbook condensa aprendizados recorrentes de time (padronização, planejamento, automação) e transforma em um fluxo que dá para aplicar em qualquer squad.

TL;DR em 60 segundos

Se você quer velocidade sem perder padrão, foque em 4 pontos:

• Input padrão: protótipo consistente + design system "de verdade" (componentes + estados + navegação fechada).
• Plano antes de código: agente primeiro mapeia e planeja, depois implementa em incrementos pequenos.
• Isolamento de contexto: git worktree para rodar várias frentes em paralelo com menos atrito.
• Ferramentas com controle: MCP para conectar contexto e ações (Figma, issues, CI, docs, DB) com mínimo privilégio e auditoria.

O resto do post é "como fazer isso funcionar na vida real".

O que você vai encontrar

• Onde a IA acelera mais (e onde ela costuma falhar sem insumo bom).
• Como preparar protótipo e design system para reduzir retrabalho no front.
• Um fluxo simples de planejar -> implementar -> validar com agente.
• Como usar git worktree para trabalhar em paralelo com menos atrito.
• Como encaixar MCP para conectar ferramentas e contexto sem virar bagunça.
• Checklists finais para manter qualidade e previsibilidade.

O que é um "agente de IA" e onde o MCP entra

Um agente de IA é um modo de trabalho em que o modelo não só responde perguntas, mas executa tarefas: navega no repositório, implementa mudanças, roda validações e prepara entregas (ex.: PRs).

Já o MCP (Model Context Protocol) entra quando você quer que a IA conecte contexto e ferramentas de forma padronizada, sem depender de "prompt gigante" para explicar tudo de novo.

Pense assim: agente = "mão de obra assistida"; MCP = "porta padrão" para conectar contexto e ferramentas.

Se você quiser um modelo mental rápido:

• Agente: "faça X no repo, rode testes, abra PR".
• MCP: "conecte X a fontes e ações externas (dados, ferramentas, workflows) com um contrato padrão".

Onde agentes de IA aceleram (e onde eles quebram)

A regra que mais se repete é simples:

Agente replica o que você dá de insumo, inclusive os erros.
Se o protótipo está inconsistente, se o design system está "meio-que", ou se o fluxo de navegação está quebrado, o agente vai reproduzir e amplificar isso.

Uma matriz rápida de decisão

A partir daqui, o playbook é: melhore insumos + coloque guard-rails + quebre a entrega em incrementos.

A base do playbook: padronização antes de velocidade

Antes de "colocar o agente para trabalhar", invista em três padronizações que pagam rápido:

1. Protótipo consistente
2. Design system confiável
3. Fluxo fechado de navegação e estados

1) Prototipagem consistente: menos variação, menos retrabalho

Um protótipo "agent-ready" tem:

• Componentes bem definidos (cards, inputs, botões).
• Mesma tela = mesmo componente (evitar "cards iguais, mas diferentes").
• Nomeação coerente e repetível.
• Padrões de layout reutilizáveis (grid, espaçamentos, barras, cabeçalhos).
• Estados explícitos (loading/empty/error/success).

Checklist rápido do protótipo:

• Existe padrão de botão primário/secundário/terciário?
• Cards repetidos são o mesmo componente, com variações claras?
• Espaçamentos e grids são consistentes (ex.: 8pt grid)?
• Estados (loading/empty/error) existem no protótipo?
• Copys e labels estão definidos (para não virar "placeholder eterno")?
• As telas têm nomeação padronizada (para virar rota/componente sem adivinhação)?

2) Design system como "contrato" entre design e código

Pense no design system como uma API: ele precisa ter contratos claros.

O que ajuda muito na prática:

• Tokens (cores, spacing, tipografia) com nomeação estável.
• Biblioteca de componentes com variações permitidas (e proibidas).
• "Matriz de estados" (ex.: input: default/focus/error/disabled/loading).
• Referência de "como implementar" (Storybook ou exemplos no repo).

Checklist mínimo de design system:

• Tokens nomeados (não "Azul 1 / Azul 2" sem semântica).
• Componentes de formulário fechados (input/select/textarea/mask).
• Feedbacks padronizados (toast/alert/inline error).
• Loading/empty/error definidos por componente e por tela.
• Padrão de tabela e paginação (ou decisão explícita de não usar).

3) Navegação completa e fluxo "fechado"

Para IA (e para dev), faz muita diferença ter o fluxo completo:

• telas conectadas de ponta a ponta,
• botões apontando para destinos claros,
• sem "buracos" em que alguém precisa adivinhar.

Isso reduz a chance do agente inventar navegação, rotas ou componentes.

Checklist de fluxo:

• Cada CTA tem destino (rota, modal, ação).
• Existe "caminho de volta" (breadcrumbs, back, cancel).
• O fluxo principal funciona sem "tela fantasma" no meio.
• Existe comportamento definido para erro (ex.: falha ao salvar).

Planeje antes de pedir para o agente implementar

Um padrão que funciona bem: pedir para o agente estudar/mapejar antes de codar.

Um fluxo simples que funciona (e escala)

1. Mapear o projeto
2. Gerar um plano por etapas (features pequenas)
3. Revisão humana do plano
4. Implementação em incrementos
5. Validação no meio do caminho
6. PR pequeno + checklist
7. QA + merge com confiança

Se o "plano" não está bom, a implementação tende a ficar cara. Ajuste o plano primeiro.

Template: "brief de tarefa" agent-ready

Use esse template como entrada para o agente (isso vale para Codex, Cursor, etc.):

Objetivo:
- (1 frase) O que precisamos entregar e por quê.

Escopo:
- Inclui:
  - ...
- Não inclui:
  - ...

Critérios de pronto (DoD):
- [ ] ...
- [ ] ...
- [ ] ...

Referências:
- Figma: (link)
- Rotas relacionadas: (se souber)
- APIs/contratos: (Swagger/Postman/Docs)
- Padrões do repo: (arquivo/pasta, ex.: src/ui/components)

Restrições técnicas:
- Stack: (ex.: Next.js + TS + Tailwind)
- Padrões: (ex.: sem libs novas, lint sem warnings)
- Observabilidade: (ex.: log/metrics obrigatórios em X)

Como validar:
- Comandos:
  - npm test
  - npm run lint
  - npm run e2e (se existir)
- Cenários:
  - ...

Prompt padrão: mapear -> planejar -> executar

Em vez de "implemente X", use algo como:

1. Faça um mapa rápido do repo para esta feature:

   • Onde ficam rotas, páginas e componentes?
   • Existe feature parecida? Aponte arquivos.

2. Escreva um plano em etapas pequenas:

   • Cada etapa com arquivos a tocar.
   • Critério de pronto por etapa.
   • Riscos e decisões.
3. Só depois execute a etapa 1.
   Pare e peça revisão antes da etapa 2.

Isso muda o jogo porque:

• você corrige caminho antes de ter 20 arquivos alterados,
• o agente passa a trabalhar com critérios verificáveis,
• review fica previsível.

Rode várias frentes em paralelo com git worktree

Quando você quer tocar múltiplas features (ou múltiplos projetos) em paralelo, git worktree evita o ciclo de "troca de branch + stash + conflito + contexto perdido".

Exemplo (um repo, duas features em pastas diferentes):

git worktree add ../feature-auth feature/auth
git worktree add ../feature-billing feature/billing

Rotina prática de worktrees

# listar worktrees
git worktree list

# remover worktree depois do merge
git worktree remove ../feature-auth

# limpar metadados de worktrees apagadas "na mão"
git worktree prune

Benefícios no dia a dia (especialmente com agente)

• menos conflito de contexto (cada feature "mora" em uma pasta),
• mais previsibilidade para revisão (PRs curtos por feature),
• isolamento natural para "tarefas do agente" (um worktree por objetivo),
• fácil pausar e retomar sem stash.

Checklist rápido:

• cada worktree tem um objetivo claro (1 feature / 1 hotfix).
• PR por feature (não "mega PR").
• remover worktrees antigas após merge (remove + prune).
• um README curto no worktree (opcional) com contexto da tarefa.

Guard-rails: o que impede velocidade de virar bagunça

Sem guard-rails, agente vira "gerador de diffs". Com guard-rails, ele vira "acelerador confiável".

Aqui vai um baseline que funciona:

1) Sempre rodar validações no meio do caminho

Não deixe para descobrir tudo no fim. O fluxo bom é:

• lint/typecheck cedo,
• testes unitários no meio,
• E2E/Playwright no final da feature.

Exemplo de "definição de pronto" técnica:

• lint sem warnings
• typecheck ok
• testes unit ok (quando aplicável)
• E2E ok (quando aplicável)
• PR com descrição + checklist + prints quando UI

2) Política de "mudança mínima"

Quanto mais aberto o escopo, mais o agente inventa.

Use sempre:

• limite de arquivos (ou pastas) por etapa,
• "não crie abstração nova sem justificar",
• "sem dependência nova sem aprovação".

3) Review humano com foco (não burocrático)

Uma revisão boa para agente tem 3 perguntas:

• O comportamento bate com os critérios de pronto?
• O padrão do repo foi respeitado (componentes, rotas, naming)?
• Existe risco escondido (edge cases, permissão, migração, performance)?

Onde o MCP entra: conectar ferramentas e contexto sem prompt gigante

MCP funciona com uma ideia simples: padronizar a forma como aplicações de IA se conectam a dados e ferramentas.

Em vez de todo mundo criar integrações ad-hoc ("cada agente com um prompt diferente"), você tem:

• servers expondo "capacidades" (dados, ferramentas, prompts),
• clients no host (IDE/app/agente) consumindo isso.

O que você ganha com MCP (na prática)

• Menos "prompt manual" para explicar contexto repetidamente.
• Integrações reaproveitáveis (um server para Figma, outro para Jira, outro para DB).
• Melhor governança (permissão, auditoria, limite de escopo).
• Evolução incremental: hoje read-only, amanhã ações com aprovação.

Conceitos que você precisa saber (sem virar curso)

No dia a dia, 3 conceitos já te colocam no jogo:

• Resources: contexto/dados (ex.: documento de arquitetura, lista de rotas, design tokens).
• Tools: ações (ex.: criar PR, abrir issue, consultar DB, rodar pipeline).
• Prompts: templates de instrução e workflows (ex.: "gerar plano de implementação com DoD").

A sacada: você troca texto livre por contrato.

Um exemplo de estrutura (conceitual):

{
  "mcpServers": {
    "nome-do-server": {
      "command": "<comando-para-subir-o-server>",
      "args": ["..."],
      "env": {
        "TOKEN": "${env:TOKEN}"
      }
    }
  }
}

Use isso como ponto de partida e aplique boas práticas:

• mínimo privilégio (read-only quando possível),
• segredos via env (não hardcode),
• ações destrutivas com humano no loop,
• logs: "o que foi executado e por quê".

Como não transformar MCP em "integração infinita"

Três regras que evitam caos:

1. Um server por domínio de contexto
   Ex.: mcp-figma (design), mcp-jira (tracking), mcp-repo (repo), mcp-ci (pipelines).
2. Comece read-only
   Primeiro faça o agente entender o sistema com resources. Depois libere tools (com aprovação).
3. Defina contratos mínimos
   Nome de tool, schema, exemplos e limites. Se não dá para descrever, não dá para automatizar.

Exemplo realista: "Figma -> feature -> PR" com agente + worktree + MCP

Vamos supor que você precisa entregar uma nova tela com fluxo fechado e integração simples.

Passo 0: criar isolamento

git worktree add ../feature-nova-tela feature/nova-tela
cd ../feature-nova-tela

Passo 1: pedir mapa do repo (antes de codar)

Prompt:

Mapeie como este repo implementa telas:
- Onde ficam rotas/páginas?
- Onde ficam componentes de UI?
- Existe uma tela similar à "Nova Tela X"? Liste arquivos.
- Existe padrão para loading/empty/error? Aponte referência.

Resultado esperado:

• lista de arquivos a reutilizar,
• "o padrão do time" explícito.

Passo 2: pedir plano por etapas (com DoD)

Prompt:

Com base no mapeamento, escreva um plano em 4-6 etapas.
Para cada etapa:
- arquivos que serão alterados/criados
- critério de pronto
- validações a rodar
Inclua riscos e dependências (API, tokens, ambiente).
Não implemente ainda.

Você revisa o plano, corta escopo, adiciona restrições (ex.: "não criar componente novo", "usar componente X").

Passo 3: implementar em incrementos pequenos

Você autoriza apenas a etapa 1:

Implemente apenas a etapa 1 do plano.
Regras:
- mantenha o padrão do repo
- sem libs novas
- rode lint/typecheck antes de finalizar
- pare e me mostre um resumo das mudanças + próximos passos

Passo 4: validar e preparar PR

Checklist de PR:

• descrição do que mudou,
• prints/gravação quando UI,
• lista de testes executados,
• notas de risco e rollback (se necessário).

Se o agente tiver acesso a ferramentas via MCP, ele pode:

• buscar dados do Figma (resource),
• abrir um ticket ou atualizar status (tool),
• rodar checks em CI (tool),
• anexar links (prompt padronizado).

Checklist final: IA no projeto sem caos

Inputs (design/produto):

• Protótipo consistente (componentes, grid, estados).
• Navegação fechada (sem buracos).
• Critérios de pronto claros (DoD).
• Escopo "não inclui" explícito (anti-scope creep).

Fluxo com agente:

• Agente mapeia antes de implementar.
• Plano revisado por humano (etapas pequenas e verificáveis).
• Implementação em incrementos pequenos (1 etapa por vez).
• PRs curtos e frequentes (sem mega PR).

Qualidade (engine):

• Lint/typecheck rodando no meio do caminho.
• Testes unit/E2E quando aplicável.
• UI validada contra protótipo (prints, checklist).
• Sem dependências novas sem aprovação.

MCP (governança):

• Servidores separados por domínio.
• Read-only primeiro; tools depois.
• Segredos em env, mínimo privilégio.
• Aprovação humana para ações sensíveis.
• Logs e rastreabilidade.

Próximo passo

Se você quer aplicar esse playbook no seu time (ou precisa montar a esteira para rodar múltiplos projetos com mais velocidade e controle), comece pelo básico:

• padronize protótipo e componentes,
• transforme o escopo em features pequenas,
• defina critérios de pronto,
• só então escale com agente + MCP.

Referências (docs oficiais)

• Model Context Protocol (MCP): visão geral
• Model Context Protocol (MCP): spec
• MCP Registry: about e registry
• OpenAI Codex: documentação e Codex CLI
• Git Worktree: docs
• Playwright: docs
• Strapi Content-type Builder: docs
• NGINX Reverse Proxy: docs