6.1 Dois agentes, um projeto

🎯O que você ganha aqui

Workflow real e testado de quem vive com os dois agentes. Sai sabendo configurar setup VS Code, passar contexto entre eles em 30s, dividir trabalho sem atropelar, e antecipar a chegada de novos runtimes.

Conteúdo detalhado

📋 Session handoff — o resumo padronizado

Resumo curto e estruturado que você pede ao agente atual ANTES de passar a bola pro outro. Esta é a feature que destrava workflow dual. Sem ela, você fica re-explicando contexto. Com ela, é uma página de cola e segue.

Template de handoff (5 seções)

# Session handoff — 2026-05-24 16:30

## 🎯 Foco atual
Implementar autenticação OAuth no /api/auth com Google.

## 📂 Arquivos tocados (com estado)
- src/api/auth.ts          ← parcial, falta validação JWT
- src/api/auth.test.ts     ← testes do happy path passando
- prisma/schema.prisma     ← adicionou model OAuthAccount

## ✅ Decisões tomadas
- Usar passport.js (não auth0)
- JWT em cookie httpOnly (não localStorage)
- Refresh token rotacionando a cada 1h

## 🚧 Problema aberto
JWT verification falhando com "jwt malformed" no payload de teste.
Tentei 3 abordagens (recriar token, mudar secret, verificar
cookie parse) sem sucesso. Provável bug na lib ou no setup do test.

## ⏭ Próximos passos
1. Investigar setup do test (jest mock do passport?)
2. Se persistir, trocar passport por jose lib
3. Implementar refresh endpoint
4. Cobertura de erro paths

✓ Bom handoff

• Curto (cabe numa página)
• Estrutura fixa (5 seções)
• Lista de arquivos COM estado
• Decisões explícitas (não óbvias do código)
• Problema atual com tentativas anteriores

✗ Handoff inútil

• "Estou trabalhando na feature X" (vago)
• 20 páginas de contexto (ninguém lê)
• Sem problema atual (não sabe o que fazer)
• Decisões que dá pra ler do código (redundante)
• Sem próximo passo

💡Vira skill

Candidato perfeito pra skill session-handoff em ambos runtimes (escrita uma vez via polyskill). Você roda /session-handoff ou $session-handoff, recebe o template preenchido pronto, cola no outro agente.

Conceitos-chave

5 seções fixas
Foco, arquivos, etc.

Skill candidato
Padroniza

Curto > completo
Página única

Problema atual
+ tentativas

🖥️ Dois terminais, um projeto — setup VS Code

Setup prático que funciona: VS Code aberto no projeto, dois painéis de terminal — um rodando claude, outro rodando codex. Mesmo filesystem, mesmo git, mesmas docs. Você troca de painel com atalho.

Layout ASCII do VS Code

┌──────────────────────────────────────────────────────────────────┐
│ Explorer │  src/api/auth.ts                                       │
│          │  ──────────────────────────────────────                │
│ ▾ src    │  export async function login(req, res) {               │
│   api    │    // implementação aqui                               │
│   ui     │    ...                                                 │
│ ▸ tests  │  }                                                     │
│          │                                                        │
│          ├────────────────────────────┬───────────────────────────┤
│          │ TERMINAL 1: claude         │ TERMINAL 2: codex         │
│          │ > refatorando auth.ts      │ > escrevendo testes       │
│          │ [Claude pensa…]            │ [Codex pensa…]            │
│          │                            │                           │
└──────────┴────────────────────────────┴───────────────────────────┘

⌨️

Split terminal

Ctrl+Shift+5 (VS Code) divide o painel. Cada metade roda um agente.

🎨

Profile por agente

Crie 2 terminal profiles no VS Code: "Claude" e "Codex". Cores diferentes, autoboot do agente.

⚡

Atalho focus

Ctrl+Shift+` foca o terminal. Setas pra navegar entre painéis sem mouse.

Workspace settings ideal

// .vscode/settings.json
{
  "terminal.integrated.profiles.osx": {
    "Claude Code": {
      "path": "/bin/zsh",
      "args": ["-c", "claude"],
      "color": "terminal.ansiBlue"
    },
    "OpenAI Codex": {
      "path": "/bin/zsh",
      "args": ["-c", "codex"],
      "color": "terminal.ansiMagenta"
    }
  },
  "files.watcherExclude": {
    "**/.claude/**": false,
    "**/.codex/**": false,
    "**/.agents/**": false
  }
}

Conceitos-chave

Split terminal
Painéis lado a lado

Profile colorido
Distinção visual

Atalhos foco
Sem mouse

Settings repo
.vscode/ no git

⚠️ Evitar atropelo — quando os dois editam

Se os dois agentes editam o mesmo arquivo ao mesmo tempo, um sobrescreve o outro. É a forma #1 de perder trabalho com workflow dual. Solução é disciplina simples: dividir por área ou por fase.

📂 Divisão por área

Cada agente trabalha em pastas diferentes:

Claude   → src/api/    (backend)
Codex    → src/ui/     (frontend)

Não há sobreposição, não há atropelo. Mais simples.

⚙️ Divisão por fase

Mesma área, fases diferentes:

Claude   → implementa src/x.ts
Codex    → escreve testes/x.test.ts

Coordena: terminou implementação? Avisa o Codex pra fazer teste.

Estratégias avançadas

Git branch por agente: claude trabalha em feat/x-impl, codex em feat/x-test. Merge depois.

Lock manual via comment: primeiro a chegar adiciona // LOCKED by claude — 16:30 no topo. Outro vê e respeita.

git stash entre trocas: antes de mudar de agente, stash do trabalho parcial. Outro agente trabalha em estado limpo.

⚠️O cenário a evitar

Dois agentes editando src/api/auth.ts em paralelo. Claude termina, escreve. Codex termina 30s depois, escreve em cima — perde o trabalho do Claude. Você descobre no próximo commit que falta metade da mudança. Drama de 1-2h pra reconstruir.

Conceitos-chave

Divisão por área
Mais simples

Divisão por fase
Impl vs test

Branch por agente
Avançado

Last-write-wins
Perde trabalho

🔌 MCP servers compartilhados

MCP servers rodam como processos independentes. Configurou uma vez, os dois agentes conectam no mesmo. Server não é duplicado — só a declaração no client (JSON pro Claude, TOML pro Codex).

Configuração espelhada

# Claude: .mcp.json (no projeto)
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@mcp/github"],
      "env": { "TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

# Codex: .codex/config.toml (no projeto)
[mcp_servers.github]
command = "npx"
args = ["-y", "@mcp/github"]

[mcp_servers.github.env]
TOKEN = "${GITHUB_TOKEN}"

# Resultado:
# Os dois agentes apontam pro MESMO server (mesmo binário,
# mesmas credenciais, mesmas ferramentas expostas).

🔧

Server independente

MCP server é processo. Sobe quando é chamado, fica disponível. Não importa quem chamou.

🔑

Env centralizada

Use .env compartilhado. Token de GitHub está num lugar só — os dois clients leem.

🛡️

Allowlist por runtime

Cada client pode ter allowlist diferente. Codex libera tudo, Claude libera só leitura. OK.

💡Manutenção

Skill que precisa de MCP específico? Declare no openai.yaml sidecar pro Codex E no frontmatter ou doc do Claude. Polyskill cuida disso automaticamente ao buildar.

Conceitos-chave

Server único
Não duplica

.env central
Credenciais uma vez

Declaração 2x
JSON + TOML

Allowlist indep.
Por client

🪝 Hooks compartilhados via script

Hooks são shell commands. Coloque a lógica em scripts/check.sh no projeto, os dois runtimes apontam pra esse script. Manutenção em um único lugar — edita o script, os dois agentes obedecem.

Padrão recomendado

# scripts/lint-on-edit.sh — lógica central
#!/bin/bash
set -e

CHANGED_FILE="$1"  # passado pelo hook

if [[ "$CHANGED_FILE" == *.ts ]]; then
  npx tsc --noEmit "$CHANGED_FILE"
  npx eslint "$CHANGED_FILE"
fi

if [[ "$CHANGED_FILE" == *.py ]]; then
  ruff check "$CHANGED_FILE"
fi

# .claude/settings.json — declara o hook
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit",
      "hooks": [{
        "type": "command",
        "command": "./scripts/lint-on-edit.sh ${file}"
      }]
    }]
  }
}

# .codex/config.toml — mesma coisa
[[hooks]]
event = "post_tool_use"
matcher = "edit"
command = "./scripts/lint-on-edit.sh ${file}"

✓ Lógica no script

• Atualiza script → vale pros dois
• Script é testável fora do agente
• Versionado junto com código
• Pode ser usado em CI/pre-commit também

✗ Lógica inline nos hooks

• Duplica regex/comandos nos dois runtimes
• Esquece de atualizar um lado
• Difícil de testar isolado
• Não dá pra reusar fora dos hooks

💡Pre-commit hook do git também

Coloque scripts/lint-on-edit.sh no .git/hooks/pre-commit (ou via husky). Mesma lógica vale pra agente E pra commit manual. Garantia tripla.

Conceitos-chave

Script shared
Lógica central

Hook = wrapper
Só chama script

Exit 0/1
Pass/block

Reuso em CI
Mesmo script

📊 Governança — quando usar qual

Conjunto de regras pra escolher agente por tipo de tarefa. Sem regra escrita, escolha vira intuição instável. Com regra, novos integrantes do time têm padrão pra seguir.

Rule of thumb (exemplo real)

Categoria

Claude Code

Codex

Refactor longo (multi-arquivo)

✓ Padrão

backup

Debug profundo (hipóteses)

✓ Padrão

backup

Geração de teste

backup

✓ Padrão

CRUD bem definido

backup

✓ Padrão

Research/arquitetura (sub-agents)

✓ Padrão

backup

Travou em loop

handoff →

→ pra cá

📝

Escreva no CLAUDE.md/AGENTS.md

A regra vai no manual do projeto. Tudo no time vê.

🔬

A/B periódico

A cada 2-3 meses, refaz uma tarefa nos dois. Calibra a regra.

🎲

"Pega o ocioso"

Quando empate, usa o que estiver com menos contexto carregado.

💡Revisão trimestral

Modelos atualizam toda hora. O que era força de um pode ser força do outro 3 meses depois. Marca revisão da rule of thumb a cada trimestre. Sem revisão, a regra vira mito.

Conceitos-chave

Regra escrita
Time consulta

A/B test
Calibra

Default + backup
Sempre uma alternativa

Trimestral
Revisão fixa

🚀 Próximos runtimes — preparando o futuro

O ecossistema não para em Claude+Codex. Gemini CLI, Cursor, Copilot, JetBrains AI Assistant estão no roadmap do polyskill. Suas skills cross-runtime já estão prontas — falta só o adapter.

Roadmap polyskill

✓

Claude Code — adapter completo, prod

✓

OpenAI Codex — adapter completo, prod

✓

Portable — source canônico

🔜

Gemini CLI — em discussão, esperando spec estável

🔜

Cursor — em discussão

🔜

GitHub Copilot — em discussão

🔜

JetBrains AI Assistant — em discussão

Como contribuir adapter novo

Fork do repo inematds/pollyskill
Cria arquivo novo em src/adapters/<nome>.ts implementando interface Adapter (parse, emit, validate)
Registra no src/adapters/index.ts: register(new SeuAdapter());
Adiciona exemplo em examples/<nome>-example/ com round-trip
Abre PR com tag new-adapter

Comunidade — Early AI Dopters

Os padrões por trás do polyskill, atualizações conforme novos runtimes ganham adapters, e working group de builders shippando ferramentas cross-runtime — tudo isso vive em:

skool.com/earlyaidopters/about

🦜O investimento que sobrevive

Cada skill que você escreve no formato portable é à prova de futuro. Quando Gemini ganhar adapter? Sua skill funciona lá no dia 1. Quando Cursor? Mesma coisa. Quando aparecer o "Claude 5 Code"? Mesma coisa. Você não reescreve.

Conceitos-chave

Adapter via PR
Contribuição padrão

Skill futuro-proof
Investimento dura

Comunidade
Early AI Dopters

parse+emit+validate
Barra simples

🎯Resumo do módulo

✓

Session handoff em 5 seções — vira skill, padroniza transição.

✓

Dois terminais no VS Code com profile colorido — atalho de foco, settings commitada.

✓

Evita atropelo: por área OU por fase — disciplina simples, perde-trabalho zero.

✓

MCP server compartilhado, declaração 2× — credenciais centrais (.env).

✓

Hooks chamam script central — reuso em CI/pre-commit também.

✓

Governança = rule of thumb escrita + revisão trimestral — sem mito.

✓

Gemini/Cursor/Copilot vêm aí — skills portáveis estão prontas.

🏁 Fim do curso!

Você completou as 6 trilhas. Agora sabe: anatomia dos dois runtimes, como migrar, como escrever skills cross-runtime com polyskill, e como operar com os dois no dia a dia.

← Voltar para Trilha 6 🏁 Landing do Curso