Claude Code Mastery10 / 12
Workflows de equipo
Cómo los equipos de ingeniería integran Claude Code hoy en la práctica. La carpeta .claude/ compartida, los rituales de revisión y los antipatrones que veo una y otra vez en el campo.
Un desarrollador solo con Claude Code es una historia de productividad. Un equipo con Claude Code es una pregunta de operating model.
La mayoría de las victorias (y la mayoría de los fracasos) que veo a nivel de equipo no tienen nada que ver con el modelo. Tienen que ver con vocabulario compartido, restricciones compartidas y rituales de revisión compartidos.
Esto es lo que funciona, lo que no, y los patrones que yo robaría.
La carpeta .claude/ compartida es el desbloqueo
Haz commit de .claude/ al repo. Todo.
CLAUDE.md— contexto del proyecto, convenciones, lista "no modificar nunca"..claude/settings.json— allowlist / denylist de herramientas..claude/agents/*.md— tu tripulación de sub-agentes..claude/commands/*.md— tus slash commands.
Todo el equipo recibe el mismo operating model al hacer git pull. El onboarding pasa de "déjame mostrarte mis prompts" a "lee .claude/, lo vas a entender".
Propiedad de los agentes — elige un mantenedor
Cada sub-agente debe tener un owner en el equipo. No porque los agentes sean complejos (es un archivo .md), sino porque los agentes derivan.
Un code-reviewer escrito para un equipo de 5 ingenieros en el mes 1 estará equivocado en el mes 6. Alguien necesita:
- Leer el feedback de revisión que el agente saca a la luz.
- Notar cuándo se le escapa una clase de bug.
- Actualizar el system prompt.
Trata a los sub-agentes como infraestructura. Owned, versionados, revisados en PRs.
Rituales de PR que cambian con Claude Code
Tres rituales que he visto funcionar:
1. Las PRs escritas por IA lo declaran
Añade un label o una sección en la plantilla de PR:
## Asistida por IA
- Implementer: sí / no
- Autor de tests: humano / IA
- Code reviewer (pre-PR): n/a / agente `code-reviewer`
Esto no es burocracia. Es señal. Cuando algo se rompe, quieres saber qué clase de autoría investigar.
2. Revisión en dos niveles
Para PRs > 200 líneas o que tocan rutas críticas:
- Nivel 1: agente
code-reviewer(pre-push). - Nivel 2: reviewer humano (post-push).
Para todo lo demás, la pasada del agente + la revisión del diff por el autor es suficiente. Deja de fingir que lees cada línea de cada PR de menos de 50 líneas.
3. Revisión de código "diff-first"
Los reviewers dejan de abrir archivos. Leen el diff en gh pr diff y confían en la suite de tests. Suena temerario hasta que te das cuenta de que es el comportamiento correcto desde hace años — los humanos simplemente eran malos en eso.
La review-as-agent de Claude Code hace honesto el modelo diff-first: un agente separado ya lo verificó por lo obvio antes de que un humano lo tocara.
Lo que NO funciona
Una lista corta de patrones que parecen victorias pero no lo son:
- Una licencia de Claude Code, compartida por todo el equipo. Mata la personalización, mata las pistas de auditoría, crea una pesadilla de permisos. Licencias por usuario, punto.
- "Demos sprint IA" donde los managers eligen las mejores PRs. Sesgo del superviviente. Sigue métricas agregadas, no highlight reels.
- Banear Claude Code de los servicios "críticos". Lo opuesto al movimiento correcto. Los servicios críticos necesitan los sub-agentes más disciplinados y las allowlists más estrechas, pero son los que más se benefician del workflow.
- Forzar a todos a usar los mismos prompts. Fomenta
.claude/commands/compartidos; resiste imponer el estilo personal. La gente promptea diferente y eso está bien.
Qué cambia para los managers de ingeniería
Tres cosas cambian de verdad:
1. La velocidad se vuelve más legible
Puedes sacar estadísticas de ~/.claude/sessions/ (o su equivalente en tu log shipping). Tiempo medio por feature, número medio de rondas de agente antes de verde, fracción de PRs que pasan la revisión a la primera.
Estos datos son buenos. Úsalos para diagnóstico ("el equipo está luchando con la feature X"), no para evaluaciones de desempeño ("usaste menos el agente").
2. El onboarding se pliega a la codebase
Un nuevo fichaje se vuelve productivo más rápido — no porque sea más listo, sino porque .claude/CLAUDE.md y los sub-agentes precargan todo el conocimiento tribal de la codebase.
He onboardeado ingenieros en 2 días que habrían tardado 2 semanas antes de Claude Code. La codebase ahora está auto-documentada bajo instrucción.
3. El tiempo de los seniors se reasigna
Los ingenieros senior dejan de teclear el boilerplate. Revisan más diffs, escriben más CLAUDE.md, diseñan más ADRs. El agente maneja la tipeada; el senior maneja la arquitectura.
Es un cambio real. A algunos seniors les encanta. Otros echan de menos teclear. Ambos son legítimos. Solo reconoce que el cambio está ocurriendo.
El error de equipo más común
Dejar entrar a Claude Code en la codebase sin un .claude/ compartido primero.
Cada ingeniero termina con sus propios settings, su propio CLAUDE.md, su propia tripulación. El output del equipo se ve inconsistente porque, bueno, lo es.
Dedica dos días a escribir el .claude/ compartido. Pásalo por el equipo. Haz commit. Después despliega Claude Code.
Un plan de despliegue de 30 días que funciona
- Semana 1: 2-3 ingenieros senior usan Claude Code en tickets opt-in. Escriben la primera versión de
.claude/. - Semana 2: ábrelo al resto del equipo. Banéalo en migraciones de prod y PRs de infra. Stand-up diario de 15 min "qué funcionó / qué no" dedicado al workflow del agente.
- Semana 3: sub-agentes codificados. Rituales de revisión adoptados. Métricas en su sitio.
- Semana 4: levanta el ban de prod para los ingenieros que hayan enviado 3+ PRs asistidas por IA. Mantén el ban de infra por ahora.
Para el mes 2, Claude Code es solo "cómo trabajamos". Ya nadie habla de él específicamente. Ese es el objetivo.
Próximo artículo: Patrones avanzados — hooks, servidores MCP, herramientas custom y system prompts. Lo que construyes cuando te has quedado pequeño con los defaults.
Serie — Claude Code Mastery
- Parte 01Claude Code vs ChatGPT vs Copilot vs agentesLa mayoría de los desarrolladores usan la herramienta de IA equivocada para la tarea equivocada. Aquí tienes el porqué — y qué hacer en su lugar.
- Parte 02Instalación + el flujo de trabajo antigravedadInstalar Claude Code es cosa de 30 segundos. Configurar el flujo que hace que el agente parezca cargar con todo el trabajo pesado — eso es lo que nadie cuenta.
- Parte 03Escribir prompts que funcionan"Hazlo mejor" no es un prompt. "Refactoriza para rendimiento" no es un prompt. Aquí tienes la estructura de cuatro partes que hace que Claude Code termine de verdad lo que pediste.
- Parte 04Slash commands — construir un proyecto de la A a la Z/init, /agents, /compact y tus comandos personalizados. El kit que te lleva de carpeta vacía a app corriendo sin salir del prompt de Claude.
- Parte 05Sub-agentes — los 11 expertos especializados dentro de Claude CodeLos slash commands reutilizan prompts. Los sub-agentes reutilizan personas enteras — code-reviewer, test-writer, migration-runner. Aquí tienes el equipo que deberías tener desde el día uno.
- Parte 06Seguridad en bases de código de producciónPermisos, salvaguardas y qué no automatizar. El artículo nada sexy que decide si Claude Code se vuelve infraestructura o se vuelve la razón por la que te llamaron a las 2 a. m.
- Parte 07Pipelines multi-agenteEncadenar sub-agentes, ejecutarlos en paralelo y los patrones para 'revisar-mientras-codeo' sin perder la cabeza. Donde Claude Code empieza a sentirse como una pequeña organización de ingeniería.
- Parte 08Construir features completasDel ticket en Linear al PR mergeado con Claude Code. Un recorrido real y honesto — cómo era el prompt, qué acertó el agente, qué pillé en la review.
- Parte 09Pruebas y depuraciónDejar que Claude Code dueñe todo el bucle de tests. Incluidas las partes que ponen nerviosos a los ingenieros: regresiones, flakies, tests de integración y el susurrador de stack-traces.
- Parte 10Workflows de equipo — estás aquíCómo los equipos de ingeniería integran Claude Code hoy en la práctica. La carpeta .claude/ compartida, los rituales de revisión y los antipatrones que veo una y otra vez en el campo.
- Parte 11Patrones avanzados — Hooks, servidores MCP, herramientas custom, system promptsCuando ya creciste más allá de los defaults: hooks para efectos colaterales deterministas, servidores MCP para datos de la organización, herramientas custom y cirugía de system prompt.
- Parte 12El futuro del desarrollo agénticoHacia dónde va esto en 2026 y más allá. A qué le apostaría, a qué no, y la línea más allá de la cual me vuelvo escéptico del hype.