El registro de riesgos antes de llevar Claude Code a tu equipo

Un viernes por la tarde, un compañero soltó: “Claude Code es buenísimo, desde la semana que viene lo usamos todos”.

Y a mí se me revolvió el estómago. Cuando él lo usaba solo, revisaba su propia rama, la mergeaba él mismo y, si algo salía mal, el único afectado era él. Pero en equipo la cosa cambia. ¿Con permiso de quién, hasta dónde se le deja tocar y quién confirma los cambios? Si seis personas empiezan a usarlo sin eso resuelto, es perfectamente normal que un cambio que borra la base de datos de producción aparezca mergeado sin que nadie sepa cómo.

De hecho, en otro equipo lo viví. Tres personas corrían Claude Code cada una con su propia configuración, alguien pidió “ordéname esto un poco” y el archivo de configuración compartido quedó reescrito. El lunes por la mañana, todos los despliegues fallaron. Medio día para encontrar la causa. Nadie tuvo mala intención. Simplemente no existía una regla para “qué pasa cuando le delegamos en equipo”.

Por eso armamos lo que te muestro en este artículo: un registro de riesgos. Cuando digo registro suena grande, pero es una sola tabla. La diferencia entre tenerla o no es la diferencia entre que llevar Claude Code al equipo termine en “qué cómodo” o en “se nos fue el mes apagando incendios”.

Puntos clave

• Los accidentes al desplegar en equipo no vienen de lo inteligente que sea el modelo, sino de que nadie definió “quién, hasta dónde y con la confirmación de quién”.
• Un registro de riesgos es una tabla con una línea por cada zona peligrosa: responsable, forma de verificar y condición para avanzar. Con tres líneas alcanza al inicio.
• Fija primero tres cosas: permisos (qué archivos puede tocar), CI (la prueba de que el cambio no rompió nada) y publicación (verificar lo que sale a producción).
• A Claude Code le delegas hasta el “borrador y la ejecución de la verificación”. Borrar, escribir en la base de producción, gastar dinero y hacer force push siempre los aprueba una persona.
• Incluyo una plantilla de registro que corre con copiar y pegar, y un ejemplo de configuración que bloquea operaciones peligrosas. El truco es probar primero con un solo archivo.

¿Qué es exactamente un registro de riesgos?

Es una tabla que lista los “lugares donde es fácil tener un accidente” cuando le delegas trabajo a Claude Code en equipo.

Cada fila se resuelve con solo tres columnas. Dónde está el peligro, cuál es la prueba de que es seguro y quién hace esa verificación. Nada más. No necesitas una herramienta de gestión complicada. Al principio basta una hoja de cálculo, o incluso un arreglo dentro del propio código.

¿Por qué pasarlo a una tabla? Porque “tener cuidado más o menos” es justo lo más peligroso. Cuando la gente está ocupada, siempre se salta las verificaciones. Si lo pones en una tabla y decides “no se mergea hasta que esta fila esté completa”, el accidente se frena incluso un viernes ocupado por la tarde. El accidente de despliegue del principio se evitaba con una sola línea que marcara el archivo de configuración compartido como “zona prohibida de tocar”.

Los tres puntos peligrosos que hay que fijar primero

Los lugares donde se tropieza al desplegar en equipo se reducen casi siempre a estos tres. Dicho al revés: si los escribes en el registro, evitas casi todos los accidentes graves del primer día.

1. Permisos (qué archivos puede tocar)

El accidente más común es “dejar tocar de más”. Si le pides “ordena el repositorio”, Claude Code reescribe sin pestañear los archivos de configuración y hasta la definición del CI. Por eso decides de antemano qué lugares puede editar y cuáles no debe tocar nunca, y lo dejas por escrito.

Mi criterio es simple. Artículos, borradores y código de pruebas: puede tocarlos. La carpeta .github/, las variables de entorno de producción, la configuración de despliegue y las migraciones de base de datos: “para hasta que una persona lo confirme”. Si dejas este límite al gusto de cada quien, las reglas se vuelven distintas según la persona y, al final, la configuración de la persona más laxa es la que causa el accidente. Lo clave es unificarlo en uno solo para todo el equipo.

2. CI (que entregue la prueba de que no rompió nada)

Que Claude Code diga “ya lo arreglé” es una opinión, no una prueba. Por eso anotas en el registro el comando que entrega la evidencia de que el cambio no rompió nada. Que la build pase, que las pruebas estén en verde, que no haya errores de tipos. Decides que alguna de esas se ejecute siempre antes de reportar éxito.

Lo importante aquí es que el comando de verificación sea rápido. Si la batería completa de pruebas tarda diez minutos, nadie la corre. Si dejas listo correr en 30 segundos solo las pruebas relacionadas con el archivo que cambiaste, la verificación se vuelve costumbre.

3. Publicación (mirar siempre lo que sale a producción)

Sea la página de ingresos del blog o una API, de todo lo que sale al exterior dejas registro de “si lo viste en la URL real”. Que la build pase y que la página que ve el usuario esté correcta son dos cosas distintas. Abres la URL de producción y guardas una captura de pantalla. Eso es la condición para dar algo por terminado.

Aunque la URL pública devuelva un 200, si el contenido es otra página, es como si no estuviera publicada. Si es una página en español pero se cuela cuerpo en inglés, también está sin terminar. Parece obvio, pero cuanto más apurado va el día, más se salta esto.

Lo que delegas a la IA y lo que decides tú

Si dudas en dónde poner el límite, usa esta tabla tal cual. El criterio es “¿se puede revertir o no?”.

Operación	Se delega a Claude Code	Una persona aprueba antes de ejecutar
Crear y corregir borradores	◯
Ejecutar pruebas y build	◯
Explicar el cambio (resumen del diff)	◯
Borrar archivos		◯
Escribir en la base de datos de producción		◯
Operaciones que generan cobros		◯
Force push y reescritura de historial		◯
Despliegue y publicación en producción		◯

La regla es una sola. Toda operación difícil de revertir empieza en “pregúntale a una persona”. Solo las operaciones que ya comprobaste seguras pasan después a automáticas. Empezar laxo y accidentarse sale más caro que empezar estricto e ir aflojando poco a poco; al final, esto último es más rápido.

Plantilla de registro de riesgos para copiar y pegar

Antes del pedido, conviene convertir en plantilla las instrucciones que le pasas a Claude Code. Pegar esto cada vez evita que se expanda por su cuenta.

Antes de trabajar, respeta lo siguiente:
- Solo puedes editar dentro de src/content/ y tests/.
- No toques .github/, variables de entorno de producción, configuración de despliegue ni migraciones de BD. Si necesitas tocarlas, no edites: reporta el motivo.
- Después de cambiar, ejecuta siempre `npm run check` y reporta el resultado.
- Si hace falta borrar, escribir en la BD de producción, generar un cobro o hacer force push, no lo ejecutes: pide confirmación.
Antes de editar, repite las restricciones de arriba con tus propias palabras y luego empieza.

Y el registro en sí. Al principio bastan tres líneas. Reemplaza con los puntos peligrosos de tu propio equipo.

// Registro de riesgos de despliegue: una línea por punto peligroso con "responsable, prueba y condición para avanzar"
type RolloutRisk = {
  area: string;       // zona peligrosa
  risk: string;       // qué podría pasar
  owner: string;      // quién verifica
  proof: string;      // prueba de que es seguro
  nextGate: string;   // condición para poder avanzar
};

const rolloutRisks: RolloutRisk[] = [
  {
    area: "permisos",
    risk: "Claude Code reescribe hasta la configuración compartida",
    owner: "líder",
    proof: "existe una lista documentada de qué se puede editar y qué no",
    nextGate: "probar primero con un solo archivo",
  },
  {
    area: "CI",
    risk: "el comando de verificación es lento o no existe",
    owner: "desarrollo",
    proof: "build en verde, o solo las pruebas relacionadas en verde",
    nextGate: "incluir los pasos de verificación en la plantilla de PR",
  },
  {
    area: "publicación",
    risk: "el cambio que sale a producción no se verificó en real",
    owner: "operaciones",
    proof: "captura de pantalla de la URL pública",
    nextGate: "dejar anotado el procedimiento de reversión",
  },
];

console.table(rolloutRisks);

Si lo guardas para que corra con node y lo ejecutas, te imprime la tabla. No es nada vistoso, pero el valor está en “poner en palabras los puntos peligrosos antes de empezar a trabajar”. Si la regla es “no se mergea hasta que cada fila esté completa”, el registro se vuelve el guardián que frena los accidentes.

En qué equipos funciona (tres ejemplos reales)

Si tu situación se parece, no rehagas el registro: cambia solo los nombres y úsalo.

1. Un equipo pequeño de dos personas Antes de tocar el código compartido, lean juntos en voz alta qué lugares se pueden editar, cuáles no se deben tocar y qué operaciones requieren aprobación de una persona, y resúmanlo en una sola hoja. Solo con eso desaparece el accidente de que “uno rompe la configuración sin que el otro se entere”. Cuanto más pequeño es el equipo, más se accidenta con el “se entiende sin decirlo”, así que ponerlo por escrito al inicio vale mucho.

2. Un equipo que pasa por revisión El líder vuelve obligatorio que, antes de que un cambio creado por Claude Code llegue a revisión, venga con “el resultado de ejecutar el comando de verificación” y “el resumen de los cambios”. Decide: el PR que no traiga esto, no lo miro. El objetivo es llegar a que el revisor pueda leer el diff, volver a correr la verificación y explicar cómo revertir.

3. Un equipo con páginas de ingresos Para cambios en páginas ligadas al dinero, como el blog o las páginas de producto, antes de darlos por terminados guardan una captura de la URL pública. No se cierra con “la build pasó”: se confirma la pantalla que el usuario ve de verdad. Se revisa con los ojos que el título, el cuerpo, la imagen y el recorrido sean los esperados.

Fallos comunes y cómo arreglarlos

Voy a ser honesto: este registro tampoco funcionó bien al principio. Comparto tres metidas de pata.

Cada quien inventó sus propias reglas Al inicio dejamos la configuración a criterio de cada persona y el rango editable terminó distinto según quién. La persona con la configuración más laxa es la que provoca el accidente. La solución es simple: unificamos en una sola lista de “qué se puede editar y qué está prohibido” para todo el equipo y la pusimos en el repositorio.

Dejamos los fallos de CI para después Cuando “luego lo arreglo todo junto” se vuelve muletilla, el primer despliegue del equipo termina con la mala impresión de “metimos Claude Code y se rompió”. Pusimos la regla de que, si el comando de verificación falla, se para ahí mismo y se mantiene como borrador hasta que vuelva al verde.

Dejamos el responsable difuso y esquivamos las decisiones difíciles Si no defines “quién aprueba”, la decisión más difícil —la de pasar a producción— queda en el aire. Llena siempre la columna owner del registro. No avances con ella en blanco. Solo con eso, las decisiones dejan de atascarse.

Cuando sientas que el trabajo empieza a desbordarse, no reescribas todo el pedido: aprieta en este orden, reduce el rango que puede tocar, exige la verificación antes y nombra a una sola persona responsable de confirmar. También es importante dejar registrados los fallos como aprendizaje del equipo. Si solo miras los casos de éxito, no te das cuenta de que entraste en una situación peligrosa.

Preguntas frecuentes

P. ¿Incluso un equipo pequeño necesita registro? Sí, aunque sean dos. Al contrario: cuanta menos gente, más se cree que “se entiende sin decirlo” y más se accidenta. Al inicio basta la plantilla de tres líneas, así que créala en cinco minutos y compártela.

P. ¿No alcanza solo con la configuración de permisos de Claude Code? La configuración de permisos es el “mecanismo que impide tocar”, y el registro es la regla operativa de “quién verifica y con qué”. Necesitas ambos. Bloqueas técnicamente con la configuración y haces girar la confirmación humana con el registro. Lo detallo en la guía de configuración de permisos.

P. ¿Qué comando de verificación elijo? El comando más corto con el que ese equipo pueda decir “no está roto”. Chequeo de tipos, ejecutar solo las pruebas relacionadas o la build, alguno de esos. Si la batería completa tarda diez minutos, nadie la corre, así que define primero uno que termine en 30 segundos.

P. ¿Funciona aunque haya miembros que no son ingenieros? Funciona. El registro solo se lee y se completa en una tabla, así que se opera sin saber leer código. Para empezar sin perfil técnico, te sirve cómo usarlo sin ser ingeniero.

P. ¿Dónde escribo las reglas propias del proyecto? Si las escribes en el CLAUDE.md del repositorio, Claude Code las lee cada vez. Concentrar ahí las zonas prohibidas de editar y los comandos de verificación hace más fácil mantenerlas alineadas con el registro. Cómo redactarlo está resumido en cómo escribir el CLAUDE.md. Revisa también como fuente primaria la documentación oficial de Claude Code de Anthropic.

Lo que comprobé al probarlo de verdad

Después del accidente de despliegue del principio, dejé de torturarme con la pregunta “¿confío en Claude Code?”. Lo que miro en su lugar es qué fila del registro está sin completar.

Cuando de verdad introduje el registro de tres líneas y dejé por escrito el archivo de configuración compartido como “zona prohibida de tocar”, los merges que rompían la configuración bajaron a cero. Cuando volví “obligatorio antes del reporte de éxito” el comando de verificación, dejé de enterarme de las roturas recién en la revisión, y los rechazos bajaron de forma visible. Y desde que metí la confirmación con captura de pantalla en las páginas publicadas, también frené el descuido de “la build pasó pero salía otra página”.

Solo comprobé estos tres puntos. Antes que buscar un agente más inteligente, conviene armar primero una operación que te permita revertir cuando te caes. Parece un rodeo, pero mi sensación hoy es que, para desplegar en equipo, esto es lo más rápido.

Si ya estás en la etapa de impulsar en serio la adopción de Claude Code en tu empresa y diseñar juntos las reglas operativas, en formación y consultoría podemos armar contigo el procedimiento concreto. Empieza por escribir tres líneas con los puntos peligrosos de tu propio equipo.