🎯Lo que obtienes aquí
Workflow real y probado de alguien que trabaja a diario con ambos agentes. Aprenderás a configurar el setup de VS Code, pasar contexto entre ellos en 30s, dividir el trabajo sin pisarse y anticipar la llegada de nuevos runtimes.
Contenido detallado
📋 Session handoff — el resumen estandarizado
Resumen breve y estructurado que le pides al agente actual ANTES de pasarle el trabajo al otro. Esta es la función que desbloquea el flujo de trabajo dual. Sin ella, tienes que volver a explicar el contexto. Con ella, tienes una página de referencia y sigues adelante.
Plantilla de handoff (5 secciones)
# 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
✓ Buen handoff
- • Corto (cabe en una página)
- • Estructura fija (5 secciones)
- • Lista de archivos CON estado
- • Decisiones explícitas (no obvias en el código)
- • Problema actual con intentos anteriores
✗ Handoff inútil
- • "Estoy trabajando en la función X" (vago)
- • 20 páginas de contexto (nadie las lee)
- • Sin un problema actual (no sabe qué hacer)
- • Decisiones que se pueden deducir del código (redundantes)
- • Sin próximo paso
💡Se convierte en skill
Candidato perfecto para una skill session-handoff en ambos runtimes (se escribe una vez con polyskill). Ejecutas /session-handoff o $session-handoff, recibes la plantilla completada y lista para pegar en el otro agente.
Conceptos clave
Enfoque, archivos, etc.
Estandariza
Página única
+ intentos
🖥️ Dos terminales, un proyecto — configuración de VS Code
Setup práctico que funciona: VS Code abierto en el proyecto, dos paneles de terminal — uno en ejecución claude, otro en ejecución codex. El mismo filesystem, el mismo git, la misma documentación. Cambias de panel con un atajo.
Diseño ASCII de 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…] │
│ │ │ │
└──────────┴────────────────────────────┴───────────────────────────┘
Terminal dividida
Ctrl+Shift+5 (VS Code) divide el panel. Cada mitad ejecuta un agente.
Profile por agente
Crea 2 perfiles de terminal en VS Code: "Claude" y "Codex". Colores diferentes, inicio automático del agente.
Atajo focus
Ctrl+Shift+` enfoca la terminal. Usa las flechas para navegar entre paneles sin mouse.
Configuración ideal del workspace
// .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
}
}
Conceptos clave
Paneles lado a lado
Distinción visual
Sin mouse
.vscode/ en git
⚠️ Evitar pisarse — cuando ambos editan
Si los dos agentes editan el mismo archivo al mismo tiempo, uno sobrescribe al otro. Es la forma #1 de perder trabajo con un workflow dual. La solución es una disciplina sencilla: dividir por área o por fase.
📂 División por área
Cada agente trabaja en carpetas diferentes:
Claude → src/api/ (backend) Codex → src/ui/ (frontend)
No hay superposición ni interferencias. Más simple.
⚙️ División por fase
La misma área, distintas fases:
Claude → implementa src/x.ts Codex → escreve testes/x.test.ts
Coordina: ¿terminó la implementación? Avisa a Codex para que haga pruebas.
Estrategias avanzadas
feat/x-impl, codex en feat/x-test. Merge después.// LOCKED by claude — 16:30 en la parte superior. Otra persona lo ve y lo respeta.⚠️El escenario que debes evitar
Dos agentes editando src/api/auth.ts en paralelo. Claude termina y escribe. Codex termina 30s después y escribe encima: se pierde el trabajo de Claude. Descubres en el siguiente commit que falta la mitad del cambio. Un lío de 1-2h para reconstruirlo.
Conceptos clave
Más simple
Impl vs test
Avanzado
Pierde trabajo
🔌 MCP servers compartidos
Los servidores MCP se ejecutan como procesos independientes. Lo configuraste una vez, los dos agentes se conectan al mismo. El Server no se duplica: solo la declaración en el client (JSON para Claude, TOML para Codex).
Configuración sincronizada
# 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 independiente
El servidor MCP es un proceso. Se inicia cuando se lo llama y queda disponible. No importa quién lo haya llamado.
Variables de entorno centralizadas
Usa .env compartido. El token de GitHub está en un solo lugar: ambos clientes lo leen.
Lista de permitidos por runtime
Cada client puede tener una allowlist diferente. Codex lo permite todo, Claude solo permite lectura. Está bien.
💡Mantenimiento
¿La skill necesita un MCP específico? Decláralo en el openai.yaml sidecar para Codex Y en el frontmatter o documento de Claude. Polyskill se encarga de esto automáticamente al compilar.
Conceptos clave
No duplica
Credenciales una sola vez
JSON + TOML
Por cliente
🪝 Hooks compartidos mediante script
Los hooks son comandos de shell. Coloca la lógica en scripts/check.sh en el proyecto, ambos runtimes apuntan a este script. Mantenimiento en un solo lugar: editas el script y ambos agentes lo siguen.
Estándar 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 en el script
- • Actualiza el script → sirve para ambos
- • El script se puede probar fuera del agente
- • Versionado junto con el código
- • También se puede usar en CI/pre-commit
✗ Lógica inline en los hooks
- • Duplica regex/comandos en ambos runtimes
- • Se olvida de actualizar uno de los lados
- • Difícil de probar de forma aislada
- • No se puede reutilizar fuera de los hooks
💡También el hook pre-commit de git
Coloca scripts/lint-on-edit.sh no .git/hooks/pre-commit (o mediante husky). La misma lógica se aplica tanto al agente como al commit manual. Triple garantía.
Conceptos clave
Lógica central
Solo llama al script
Pass/block
El mismo script
📊 Gobernanza — cuándo usar cada uno
Conjunto de reglas para elegir un agente según el tipo de tarea. Sin una regla escrita, la elección se vuelve una intuición inestable. Con una regla, los nuevos integrantes del equipo tienen un estándar que seguir.
Regla general (ejemplo real)
Escribe en CLAUDE.md/AGENTS.md
La regla va en el manual del proyecto. Todo el equipo la ve.
Prueba A/B periódica
Cada 2-3 meses, repite una tarea en ambos. Ajusta la regla.
"Toma el que está inactivo"
En caso de empate, usa el que tenga menos contexto cargado.
💡Revisión trimestral
Los modelos se actualizan todo el tiempo. Lo que era una fortaleza de uno puede serlo de otro 3 meses después. Programa una revisión de la regla general cada trimestre. Sin revisión, la regla se convierte en un mito.
Conceptos clave
Consulta de tiempo
Calibra
Siempre una alternativa
Revisión fija
🚀 Próximos runtimes — preparándose para el futuro
El ecosistema no se limita a Claude+Codex. Gemini CLI, Cursor, Copilot, JetBrains AI Assistant están en la hoja de ruta de polyskill. Tus skills compatibles con varios runtimes ya están listas; solo falta el adapter.
Hoja de ruta de polyskill
Cómo contribuir con un adapter nuevo
- Fork del repo
inematds/pollyskill - Crea un archivo nuevo en
src/adapters/<nome>.tsimplementando una interfazAdapter(parse, emit, validate) - Registra en el
src/adapters/index.ts:register(new SeuAdapter()); - Agrega un ejemplo en
examples/<nome>-example/con round-trip - Abre un PR con etiqueta
new-adapter
Comunidad — Early AI Dopters
Los patrones detrás de polyskill, las actualizaciones a medida que nuevos runtimes obtienen adapters y el working group de builders que publica herramientas cross-runtime: todo eso vive en:
🦜La inversión que perdura
Cada skill que escribes en el formato portable está preparada para el futuro. ¿Cuándo Gemini tenga un adapter? Tu skill funcionará desde el día 1. ¿Cuándo Cursor? Lo mismo. ¿Cuándo aparezca "Claude 5 Code"? Lo mismo. No tienes que reescribirla.
Conceptos clave
Contribución predeterminada
La inversión dura
Early AI Dopters
Barra simple
🎯Resumen del módulo
🏁 ¡Fin del curso!
Completaste las 6 rutas. Ahora conoces la anatomía de ambos runtimes, cómo migrar, cómo escribir skills cross-runtime con polyskill y cómo trabajar con ambos en el día a día.