Intensivo Gratis 21–22.11Intensivo gratuito de 2 días en Vibecoding (21–22 nov, 16:00 MSK) · Cohorte 3 inicia 23.11Registrarse gratis →Cohorte 3 (23.11)
LanzamientoAPI / Producto · Listo para usarHabr AI→ original

La configuración de Claude Code funcionaba para una persona, pero falló en manos de sus colegas: 5 pasos para hacerla portable

El arnés (harness) es el conjunto de skills, conexiones MCP, subagentes y comprobaciones que rodean a un agente de IA como Claude Code. El autor de Directum lo usó durante un año sin incidencias, pero al compartirlo con sus compañeros dejó de funcionar: los scripts conservaban rutas de su propia máquina y una máquina virtual limpia no tenía Python ni Node.js. Describe cinco pasos para eliminarse a sí mismo del esquema: ahora las rutas se calculan desde la raíz del repositorio y el instalador verifica el entorno por su cuenta. La conclusión es probar la instalación en una máquina limpia antes de que llegue el primer compañero.

Procesado por IA desde Habr AI; editado por Hamidun News
La configuración de Claude Code funcionaba para una persona, pero falló en manos de sus colegas: 5 pasos para hacerla portable
Fuente: Habr AI. Collage: Hamidun News.
Escuchar artículo
Ficha técnica y cifras clave
ParámetroDatos
Fuente originalHabr AI ↗
Editor jefe
Dato clave #1El ciclo «revisión y corrección» se limita a tres intentos; después se llama a una persona.
Dato clave #2Para las tareas del autor, la suscripción resulta notablemente más barata que los tokens de la API, y no hace falta un servidor.
Dato clave #3Los evals, escenarios de verificación, detectan cuándo una mejora rompe los skills.

Muchos ya han montado alrededor de su agente de IA una configuración personal: han visto vídeos cortos, han acumulado skills, han conectado MCP y así han obtenido un puesto de trabajo «equipado». El arnés, o harness, es todo lo que rodea al modelo: herramientas, instrucciones, base de conocimiento, subagentes y comprobaciones. Mientras el usuario sea uno solo, funciona.

El autor de este análisis, especialista de Directum en la promoción de la plataforma Directum RX, descubrió qué pasa después. Su arnés funcionó sin fallos durante un año, pero en cuanto se lo dio a sus compañeros dejó de funcionar: su parte principal resultó ser el propio autor, y el instalador no puede instalarlo a él. A continuación describe cinco pasos para eliminarse del esquema.

Algunas de las soluciones ya funcionan, otras siguen en desarrollo, y el propio autor define el texto como experiencia personal y no como una guía para construir un equipo de IA.

Qué se estaba transfiriendo

A los autores les llegan los requisitos de los clientes y necesitan mostrar rápidamente en un prototipo cómo implementarlos en la plataforma. El entorno de desarrollo Directum RX (Development Studio) dispone de una API JSON-RPC, que se conectó a Claude Code mediante MCP. El agente crea entidades, propiedades y esqueletos de métodos con el mismo mecanismo que usa el desarrollador en la ventana del entorno, y después añade la lógica de aplicación en C#. Los paquetes para el banco de pruebas los publica la utilidad estándar Deployment Tool, y el resultado se verifica a través de la API y de la interfaz web.

El trabajo se reparte entre subagentes: el product owner prepara los requisitos y los criterios de aceptación, el arquitecto diseña la solución, el desarrollador escribe el código y las pruebas, el tester verifica los escenarios y tres revisores examinan en paralelo el código, la seguridad y la conformidad con la arquitectura. Los artefactos de cada etapa se guardan en la carpeta .pipeline, y un script gestiona las transiciones: comprueba los resultados obligatorios y guarda el estado, de modo que, tras una pausa, el coordinador continúa desde el mismo punto.

Hay dos ciclos de «comprobar y corregir»: uno para el diseño de la solución y otro para el código. Cada uno tiene un límite de tres intentos. Sin límite, los subagentes pueden corregirse unos a otros durante mucho tiempo, consumiendo los límites de la suscripción. Si el tercer intento no tiene éxito, el coordinador llama a una persona y guarda la descripción del error, los resultados de las comprobaciones y el historial de intentos.

Servidor común o instalación local

El autor consideró dos opciones. La primera era un servicio común con sandboxes (por ejemplo, GoClaw u OpenHands): el usuario recibe un entorno preconfigurado con la versión necesaria del producto. Para un solo equipo con un único entorno resulta cómodo. Pero el arnés debía usarlo varios equipos con productos, versiones de la plataforma y conjuntos de soluciones distintos. Un único entorno para todos no sirve, y dar soporte a varias variantes requeriría un equipo aparte.

Por eso se eligió la instalación local: cada persona clona el arnés desde un repositorio independiente en el GitLab interno y trabaja con su propia suscripción. Para las tareas del autor, la suscripción resulta notablemente más barata que pagar los tokens mediante la API, y no hace falta desplegar un servicio común desde el primer día. Los equipos se incorporan poco a poco y comprueban si el arnés les ayuda. El precio de esta elección es que las dependencias, las rutas, los accesos y las versiones de las herramientas difieren de una máquina a otra.

Lo común, lo de cada proyecto y lo personal se guardan por separado. Las reglas generales van al repositorio del arnés, los requisitos del proyecto están junto a su código, y los ajustes y accesos personales permanecen en local y no entran en Git. Mientras el arnés lo usaba un solo autor, los scripts tenían rutas de su máquina codificadas de forma fija. Ahora el arnés busca sus archivos en relación con la raíz del repositorio, y las rutas a Development Studio y Deployment Tool las toma el instalador de la configuración.

Las actualizaciones las entrega un hook de Claude Code, es decir, un script que se ejecuta al iniciar la sesión. Detecta una versión nueva, propone incorporar los cambios, actualiza las dependencias y comprueba que las herramientas arrancan. Los ajustes locales se conservan, los conflictos con las modificaciones propias se muestran y es posible volver a la versión anterior.

Primer arranque en una máquina limpia

El hook no fue lo primero. Antes, el autor preparó una máquina virtual limpia, clonó el repositorio y arrancó el agente. Los errores aparecieron antes de la primera tarea útil: faltaban dependencias que él había instalado hacía tiempo en su equipo y se le habían olvidado. Una herramienta necesitaba Python, otra Node.js y a una tercera le faltaban bibliotecas. Al principio el propio agente ayudaba con la configuración, pero a veces la preparación consumía todo el límite de la ventana de cinco horas de Claude.

Ahora el nuevo participante ejecuta el instalador: comprueba el entorno, instala las dependencias y configura los servidores MCP. Una instalación interrumpida se puede repetir, y los pasos ya completados se omiten. Si un mismo error se repite en varias personas, su solución pasa al instalador, que tiene en cuenta el sistema operativo, el SGBD y la versión de la plataforma.

Por ejemplo, la plataforma funciona tanto con PostgreSQL como con MSSQL, pero las utilidades del autor para psql no están disponibles con MSSQL, y el instalador lo advierte. Las herramientas se comprueban precisamente desde Claude Code, porque trabajar en la terminal y estar disponible para el agente son cosas distintas. Y como Bash, bajo el antivirus de Windows, se ejecutaba de forma inestable, los puntos de entrada de los scripts se pasaron a Node.

js.

Para que las mejoras de los equipos no rompan el comportamiento del agente, se ejecutan los evals, escenarios de verificación con criterios de éxito definidos de antemano. Por ejemplo, si alguien ajusta un skill básico para su proyecto y este deja de ejecutar la comprobación obligatoria antes de cerrar una tarea, ese escenario detectará la regresión. Eso sí, los evals solo cubren los casos que se han descrito en ellos.

Qué hacer en la práctica

Un arnés para una persona y un arnés para un equipo no se diferencian por el conjunto de herramientas, sino por cuánto depende de su autor. Si piensa compartir su arnés de agente, pruebe la instalación en una máquina virtual limpia, elimine las rutas absolutas, separe lo común, lo del proyecto y lo personal, establezca un límite de intentos en los ciclos de corrección y cree evals para los skills clave. Una salvedad: esta es la experiencia de un único ingeniero en una única empresa, y para otras plataformas habrá que encontrar soluciones de nuevo.

Historia

Preguntas frecuentes sobre la noticia

¿Qué se sabe sobre Qué se estaba transfiriendo?

A los autores les llegan los requisitos de los clientes y necesitan mostrar rápidamente en un prototipo cómo implementarlos en la plataforma. El entorno de desarrollo Directum RX (Development Studio) dispone de una API JSON-RPC, que se conectó a Claude Code mediante MCP. El agente crea entidades, propiedades y esqueletos de métodos con el mismo mecanismo que usa el desarrollador en la ventana del entorno, y después añade la lógica de aplicación en C#.

¿Qué se sabe sobre Servidor común o instalación local?

El autor consideró dos opciones. La primera era un servicio común con sandboxes (por ejemplo, GoClaw u OpenHands): el usuario recibe un entorno preconfigurado con la versión necesaria del producto. Para un solo equipo con un único entorno resulta cómodo. Pero el arnés debía usarlo varios equipos con productos, versiones de la plataforma y conjuntos de soluciones distintos. Un único entorno para todos no sirve, y dar soporte a varias variantes requeriría un equipo aparte.

¿Qué se sabe sobre Primer arranque en una máquina limpia?

El hook no fue lo primero. Antes, el autor preparó una máquina virtual limpia, clonó el repositorio y arrancó el agente. Los errores aparecieron antes de la primera tarea útil: faltaban dependencias que él había instalado hacía tiempo en su equipo y se le habían olvidado. Una herramienta necesitaba Python, otra Node.js y a una tercera le faltaban bibliotecas. Al principio el propio agente ayudaba con la configuración, pero a veces la preparación consumía todo el límite de la ventana de cinco horas de Claude.

ZK
Zhemal Khamidun — CPO de Alpina Digital, product manager de AlpinaGPT. Crea productos de IA desde 2019. Hamidun News es un proyecto personal que creció hasta ser un agregador en producción con más de 6.000 lectores.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
¿Qué te parece?
Cargando comentarios…