Claude Code para equipos de desarrollo: hooks, sub-agents y MCP en producción

Claude Code dejó de ser un asistente de IDE en 2025 y se convirtió en un agente operativo del SDLC. La diferencia es práctica: un asistente espera que le pidas autocompletar; un agente abre archivos, corre comandos, lee logs, ejecuta tests, escribe commits y abre PRs. Si tu equipo lo usa como autocompletar, está dejando 70% del valor sobre la mesa.

Esta guía sintetiza lo que aprendimos en WITS aplicándolo en proyectos productivos durante 2025–2026: cómo configurarlo, cómo dominarlo y cómo medirlo. Sin marketing — todo viene de codebases reales que pasaron por code review humano.

Asistente vs agente: la distinción que importa

Ambos coexisten. Pero los equipos que mueven la aguja tratan a Claude Code como un colaborador junior senior: le delegas tareas completas, no líneas de código.

Configuración base que todo equipo necesita

settings.json y allowlists

El primer error es operar sin allowlist explícita. Resultado: Claude pide permiso 30 veces por sesión y la fricción mata adopción. La solución es un .claude/settings.json compartido en el repo con los comandos seguros pre-aprobados.

CLAUDE.md: la memoria del proyecto

Archivo en raíz del repo donde documentas convenciones, stack, comandos críticos y reglas que el agente debe respetar. Ejemplo de secciones útiles: stack (Python 3.12, FastAPI, Postgres 16), comandos (`pytest -x`, `make migrate`), reglas ("todos los nuevos endpoints requieren test de integración"), idioma de commits, restricciones ("nunca tocar el schema sin migración").

Slash commands: convirtiendo workflows en una palabra

Los slash commands son scripts reusables que destilan un workflow en un comando. Algunos que usamos en WITS:

• /review-pr — corre el diff actual contra rúbrica del proyecto y reporta hallazgos por severidad
• /refactor-tests — toma un archivo de test, identifica duplicación y propone consolidación
• /migrate-schema — genera migración Alembic + tests + actualiza tipos
• /security-scan — busca patrones inseguros (SQL strings, secrets en código, CORS abierto) en el cambio actual
• /changelog — genera entry de CHANGELOG basado en commits desde último tag

Cada slash command vive en .claude/commands/ como un archivo Markdown con instrucciones. Versionado en git, evoluciona con el equipo.

Sub-agents: paralelizar para no contaminar contexto

Un sub-agent es una instancia secundaria con un prompt acotado y herramientas específicas. Útil cuando una subtarea (ej. buscar en una librería de 200 archivos) generaría ruido en el agente principal. Patrones que funcionan:

• Explorer — solo lectura. Encuentra dónde vive una funcionalidad sin tocar nada.
• Reviewer — corre evaluación independiente del cambio sin sesgo del que lo escribió.
• Test runner — ejecuta tests largos y reporta resumen al agente principal.
• Doc generator — genera/actualiza docs de un módulo sin reabrir el contexto del feature.

MCP servers: extender el agente a tu infra

Model Context Protocol (MCP) es el estándar de Anthropic para que los agentes hablen con sistemas externos. En equipos de producto, los MCPs útiles son:

Regla de oro: los MCPs de lectura son de bajo riesgo (úsalos generosamente); los de escritura requieren allowlist explícita y review humano antes de fusionar.

Hooks: automatizar lo que pasa antes y después

Hooks son comandos shell que se ejecutan en eventos del agente. Los tres más útiles:

• PostToolUse — tras editar un archivo, corre el linter/formatter y deja el repo limpio
• PreToolUse — antes de un comando peligroso (rm, git push), valida con un script propio
• SessionStart — cuando arranca una sesión, imprime estado actual del proyecto (branch, PRs abiertos, tests pendientes)

Patrones productivos para el día a día

Issue → PR end-to-end

Pegas la issue de Linear/Jira al agente. Le dices: "plan it first, then implement". Plan-mode produce el plan; tú revisas y aprobas. El agente ejecuta, escribe tests, abre PR con descripción, link a la issue y notas de testing manual. Tiempo típico: una feature de 200-400 LOC en 30-60 minutos vs 3-5 horas a mano.

Refactor guiado por tests

Para refactors no triviales: pides al agente que escriba primero los tests que protegen el comportamiento actual, los corres, y luego refactoreas. El agente identifica regresiones inmediatamente. Patrón conocido pero subutilizado.

Debugging con logs reales

Conectas el MCP de Sentry (o pegas el stacktrace), pides reproducción local, el agente busca la causa raíz, propone fix con test que reproduce el bug. Mucho más rápido que el ciclo manual de "copiar log → buscar → editar → reproducir".

Errores comunes que vemos

1. 1Sin CLAUDE.md — el agente reinventa convenciones cada sesión
2. 2Sin allowlist — fricción mata adopción en la primera semana
3. 3Saltarse el plan-mode en cambios complejos — código generado sin diseño previo, costo posterior alto
4. 4No usar sub-agents para exploración — contexto principal contaminado, calidad baja
5. 5Aceptar PRs sin code review humano — el agente puede generar correcto-pero-equivocado
6. 6Mantener slash commands en cabezas, no en .claude/commands/ — el equipo no escala el aprendizaje

Cómo medir el ROI sin engañarse

Las métricas de vanidad (LOC generadas, sugerencias aceptadas) no cuentan. Las métricas reales:

Los números varían por contexto, pero el patrón es consistente: 30-50% mejora en métricas operativas, sin pérdida de calidad si hay code review humano.

¿Reemplaza ingenieros?

No. Cambia el perfil. Ingenieros junior puros pierden ventaja relativa; seniors ganan apalancamiento brutal. El equipo ideal 2026: senior con Claude Code rinde como un equipo de 3 mid-level de hace 2 años — pero la calidad arquitectural depende del senior, no del agente.