Guía de colaboración en equipo con Claude Code: traspasos, revisiones y permisos

Claude Code acelera mucho el trabajo individual: investigar código, aplicar cambios y escribir pruebas se vuelve más fluido. En equipo, sin embargo, aparece otro tipo de problema. Hay que saber quién aprobó cada comando, qué archivos leyó Claude, qué riesgos siguen sin verificar y si una sugerencia de la IA fue aceptada por una persona.

Esta guía propone un flujo práctico para equipos de desarrollo pequeños y medianos. Cubre traspasos, revisión previa de PR, reglas en CLAUDE.md, límites de permisos, onboarding, traspasos de incidentes y fallos de comunicación. Un límite de permisos es el alcance de archivos y comandos que Claude Code puede leer, editar o ejecutar. Un recibo de revisión es una nota breve en el PR que deja claro cómo se trataron las sugerencias de la IA.

flowchart LR
  A["Solicitud del desarrollador"] --> B["CLAUDE.md y reglas"]
  B --> C["Trabajo de Claude Code"]
  C --> D["Pruebas y diff"]
  D --> E["Recibo de revisión"]
  E --> F["Revisión humana del PR"]

Cuatro lugares compartidos

El flujo de equipo no puede depender de que una persona recuerde buenos prompts. Las reglas deben vivir en archivos reutilizables.

Lugar	Propósito	En Git
CLAUDE.md	Convenciones, acciones prohibidas, comandos de prueba	Sí
.claude/settings.json	Permisos compartidos, reglas deny, hooks	Sí
.claude/settings.local.json	URLs personales y ajustes temporales	No
.claude/prompts/*.md	Plantillas de traspaso, revisión e investigación	Sí

La documentación oficial explica memoria de Claude Code, configuración, permisos y seguridad. Como lectura interna, revisa también buenas prácticas de CLAUDE.md, guía de hooks de Claude Code y GitHub Actions avanzado.

Caso 1: traspaso de desarrollador a revisor

El fallo más común es entregar un PR con un simple “Claude lo arregló”. El revisor necesita saber qué archivos se revisaron, qué comandos fueron aprobados, qué pruebas fallaron y qué decisiones siguen siendo humanas.

Crea .claude/prompts/handoff.md:

# Escribir nota de traspaso para el equipo

Lee el diff actual y escribe el traspaso con este formato.

## Objetivo
- Problema que este cambio intenta resolver:

## Alcance
- Archivos modificados:
- Archivos no modificados pero posiblemente afectados:

## Verificación
- Comandos ejecutados:
- Resultado:
- Resumen de logs fallidos:

## Foco para el revisor
- Decisión de producto:
- Seguridad:
- Rendimiento:
- Pruebas faltantes:

## Próxima persona responsable
- Revisar primero:
- Puede esperar:

Después de preparar el diff, ejecuta:

claude -p "Lee git diff y crea una nota de traspaso usando .claude/prompts/handoff.md"

Pega el resultado en el cuerpo del PR. Así el revisor empieza por los riesgos conocidos y no tiene que reconstruir todo el contexto desde cero.

Caso 2: revisión previa de PR con IA

Claude Code no debe reemplazar la aprobación humana. Funciona mejor como una lectura previa que detecta bugs obvios, pruebas faltantes, riesgos de seguridad y cambios inconsistentes.

Crea .claude/prompts/pr-review.md:

# Revisión previa de PR

Revisa el diff con estos criterios:

1. Ramas, null/undefined y valores límite que puedan causar bugs
2. Autorización, validación y exposición de secretos
3. Consultas N+1, rerenders innecesarios y trabajo síncrono pesado
4. Incumplimientos de CLAUDE.md
5. Casos de prueba faltantes

Formato de salida:
- Severidad: alta / media / baja
- Archivo:
- Línea o función:
- Motivo:
- Sugerencia de corrección:

Marca las conclusiones especulativas como “requiere confirmación”.

Ejecución local con GitHub CLI:

gh pr diff 123 | claude -p "$(cat .claude/prompts/pr-review.md)"

Si lo automatizas con GitHub Actions, limita el flujo a publicar un comentario. La decisión de merge sigue siendo humana.

name: Claude PR pre-review
on:
  pull_request:
    types: [opened, synchronize]

jobs:
  pre-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - name: Install tools
        run: npm install -g @anthropic-ai/claude-code
      - name: Run Claude Code review
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          gh pr diff "$PR_NUMBER" > /tmp/pr.diff
          claude -p "$(cat .claude/prompts/pr-review.md)

          Diff:
          $(cat /tmp/pr.diff)" > /tmp/claude-review.md
          gh pr comment "$PR_NUMBER" --body-file /tmp/claude-review.md

La página oficial de flujos comunes también cubre revisión y pruebas. En un equipo, la regla debe ser explícita: los comentarios de IA orientan; las personas aprueban.

Caso 3: onboarding de nuevos miembros

Un nuevo miembro suele sufrir más por no saber qué comando es seguro, dónde están las reglas de negocio y qué archivo leer primero. Claude Code puede generar el primer mapa del repositorio.

claude -p "
Explica este repositorio para una persona nueva del equipo.
Incluye:
- Directorios principales y responsabilidades
- Comandos para ejecutar, lint, test y build
- Primeros 3 archivos que conviene leer
- Reglas de negocio que hay que revisar antes de cambiar código
- Errores comunes y cómo evitarlos
- Una tarea práctica de 30 minutos

No inventes. Lista lo desconocido como requiere confirmación.
"

No publiques la salida sin revisar. Pide a una persona senior que agregue restricciones de producción, decisiones históricas y riesgos operativos. Para exploraciones grandes, la guía de patrones con subagentes ayuda a separar investigación y resumen.

Caso 4: traspaso de incidentes

Durante un incidente, Claude Code puede resumir logs y ordenar hipótesis. Los fallos también son más graves: pegar secretos, compartir hipótesis no verificadas como hechos o perder lo que ya se intentó al cambiar de responsable.

Guarda esto como .claude/prompts/incident-handoff.md:

# Traspaso de incidente

## Síntoma
- Desde cuándo:
- Alcance:
- Impacto en usuarios:

## Hechos observados
- Logs:
- Métricas:
- Pasos de reproducción:

## Intentos realizados
- Comandos:
- Resultado:
- Hipótesis descartadas:

## Riesgo pendiente
- Posible corrupción de datos:
- Impacto de seguridad:
- Estado del rollback:

## Próxima persona responsable
- Primera pantalla/log a revisar:
- Comandos que no deben ejecutarse:

Antes de pasar logs a Claude Code, oculta correos, tokens y IDs de clientes. La documentación de seguridad oficial también advierte sobre permisos e inyección de prompts.

Reglas útiles para CLAUDE.md

CLAUDE.md debe contener hechos que el equipo repite constantemente. Mantén las instrucciones cortas, concretas y verificables.

# Instrucciones del proyecto para Claude Code

## Antes de trabajar
- Ejecutar `git status --short` antes de editar.
- No revertir cambios existentes de otras personas.
- Si el comportamiento de producto no está claro, escribir “requiere confirmación” en el PR.

## Reglas de código
- Validar todas las entradas de API.
- Explicitar límites de transacción en escrituras de base de datos.
- Reutilizar claves de traducción existentes antes de agregar texto UI.

## Pruebas
- Agregar pruebas unitarias para cambios de lógica.
- Agregar una prueba de regresión para cada bug corregido.
- Si no se pudieron ejecutar pruebas, explicar por qué.

## PR
- Incluir resumen, verificación y riesgo pendiente.
- Usar sugerencias de Claude Code solo tras revisión humana.

Si el repositorio ya usa AGENTS.md, impórtalo en lugar de duplicarlo.

@AGENTS.md

## Solo Claude Code
- Usar plan mode en facturación, autenticación y flujos de borrado.
- Las personas ejecutan `git push`, despliegues de producción y migraciones.

Fijar límites de permisos

El mayor riesgo de adopción es ampliar permisos por comodidad. Empieza con deny claro y allow mínimo.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm test)",
      "Bash(git diff *)",
      "Bash(git status *)",
      "Edit(src/**)",
      "Edit(tests/**)"
    ],
    "ask": [
      "Bash(npm install *)",
      "Bash(git commit *)",
      "Write(.github/**)"
    ],
    "deny": [
      "Read(.env*)",
      "Read(**/secrets/**)",
      "Bash(git push --force*)",
      "Bash(rm -rf *)",
      "Bash(npm publish*)"
    ]
  }
}

Los hooks pueden ejecutar comprobaciones tras editar o bloquear comandos peligrosos. Consulta la referencia oficial de hooks antes de desplegarlos.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --quiet"
          }
        ]
      }
    ]
  }
}

Este ejemplo solo sirve si existe npm run lint. En un monorepo grande, usa comprobaciones por archivo o deja el trabajo pesado a CI.

Dejar recibo de revisión en el PR

La revisión con IA se vuelve peligrosa cuando nadie registra qué sugerencias fueron aceptadas. Añade esto a la plantilla de PR:

## Recibo de revisión de Claude Code

- Prompt usado:
- Diff revisado por Claude Code:
- Sugerencias aceptadas:
- Sugerencias rechazadas y motivo:
- Comprobaciones humanas adicionales:
- Pruebas ejecutadas:
- Riesgo pendiente:

Responsable de la decisión final:

Si Claude Code no se usó, escribe “no usado”. La meta es que el trabajo asistido por IA sea igual o más transparente que el trabajo normal.

Fallos concretos y soluciones

Fallo	Impacto	Solución
CLAUDE.md desactualizado	Se usan comandos viejos y API retiradas	Revisarlo cada mes con fallos reales
Permisos amplios	Secretos y acciones de producción quedan demasiado cerca	Escribir deny primero y allow mínimo
Aprobación solo por IA	Desaparecen criterios de producto y responsabilidad	La aprobación del PR siempre es humana
Traspaso verbal	Al día siguiente no se rastrea el motivo	Pegar la nota en PR o Issue
/clear borra contexto	Se pierde el porqué del cambio	Guardar resumen antes de reset o compact
Hooks pesados	El equipo empieza a evitarlos	Usar hooks por archivo o CI

También falla la comunicación. “Arréglalo bien” obliga a Claude Code a adivinar el objetivo. Es mejor escribir límites cortos: “solo esta función”, “no tocar schema”, “leer primero el log del test fallido”.

Lista mínima del equipo

• CLAUDE.md contiene comandos, prohibiciones y reglas de PR
• .claude/settings.json separa allow, ask y deny
• .claude/settings.local.json está en .gitignore
• Existen prompts compartidos de traspaso, PR e incidente
• La plantilla de PR incluye recibo de revisión
• Está claro quién decide al final
• Hay una tarea de onboarding de 30 minutos

ClaudeCodeLab sigue mejorando plantillas de este tipo para equipos con IA. Si quieres acelerar la adopción interna, revisa los productos de ClaudeCodeLab.

Conclusión

Usar Claude Code en equipo no consiste en encontrar un prompt mágico. Consiste en instrucciones compartidas, permisos estrechos, traspasos duraderos y recibos de revisión auditables.

Para trabajo individual, memorizar algunos prompts útiles puede bastar. En equipo, otra persona debe poder reproducir el flujo, rastrear fallos y separar las sugerencias de Claude Code de las decisiones humanas.

Al probar esta estructura en un repositorio pequeño de validación de Masa, la mejora más inmediata vino de añadir notas de traspaso y recibos de revisión al PR. Los revisores hicieron menos preguntas del tipo “¿qué comprobaste?”. Lo menos útil fue ejecutar lint completo tras cada edición mediante hook: era demasiado lento, así que CI fue mejor lugar. Empieza por CLAUDE.md, el prompt de pre-revisión y el recibo de revisión.