Modelo fijado, prompts versionados y dependencias de plugins

Cuatro servicios leen el modelo de una misma variable de entorno, CLAUDE_MODEL. Alguien la actualiza al modelo más nuevo para aprovecharlo en uno de ellos, y dos de los otros tres se rompen esa misma tarde. Al mismo tiempo, soporte pregunta qué texto tenía el prompt de onboarding hace tres semanas, y nadie lo sabe. Los dos problemas tienen el mismo nombre: gestión de configuración (configuration management).

Qué es configuración en un sistema con Claude

Todo lo que cambia el comportamiento sin cambiar el código de la aplicación:

• el ID del modelo y sus parámetros (max_tokens, esfuerzo, herramientas habilitadas);
• los prompts y sus plantillas;
• en Claude Code, CLAUDE.md, .claude/settings.json, skills, agentes y plugins (dónde va cada uno está en la lección de Claude Code);
• las claves, que no son configuración versionada: van en un gestor de secretos, nunca en el repo.

La regla general: lo que define el comportamiento vive en archivos versionados, cambia por pull request y queda registrado qué versión corrió en cada momento.

Fijar la versión del modelo

Cada ID de modelo de la API es una versión fija (snapshot): no cambia de comportamiento por su cuenta. Fijar la versión del modelo (model version pinning) significa que cada servicio declara su ID explícito en su configuración versionada y lo cambia como cualquier otro cambio:

1. Se prueba el modelo nuevo contra las evaluaciones de ese servicio.
2. Si pasa, se actualiza el ID en esa configuración, por pull request.
3. Se despliega de a poco, con forma de volver atrás.

Una variable compartida entre servicios mete el mismo cambio en todos a la vez, sin pruebas. Cada servicio tiene sus propias evaluaciones y su propio ritmo.

Versionar los prompts

El versionado de prompts (prompt versioning) trata el prompt como código:

• vive en el control de versiones, no en un panel que cualquiera edita en caliente;
• se despliega con el mismo pipeline que el resto, con sus pruebas de regresión;
• cada llamada registra qué versión del prompt usó (y qué ID de modelo), junto con el ID de la solicitud.

Así se puede responder qué texto estaba en producción para cualquier conversación, comparar versiones con datos y revertir una que empeoró.

Plugins y sus dependencias

En Claude Code, los plugins empaquetan skills, agentes, hooks y servidores MCP. Para que todo el equipo tenga los mismos:

• el marketplace interno se declara en extraKnownMarketplaces y los plugins en enabledPlugins, dentro del .claude/settings.json del proyecto;
• el manifiesto del plugin (plugin manifest (plugin.json)) tiene un campo version; si está, los usuarios quedan en esa versión hasta que el autor la cambie;
• si un plugin necesita otro para funcionar, se declara en sus dependencias (dependencies), en el mismo plugin.json, con nombre y, si hace falta, versión compatible. Así, instalar el plugin trae también el que necesita.

Pedirle a cada uno que instale a mano lo que dice un anuncio termina en máquinas con plugins faltantes y versiones mezcladas.

Las trampas típicas

• Usar una variable compartida o “el último modelo” en producción, sin evaluaciones por servicio.
• Editar prompts en caliente sin control de versiones ni registro de qué versión corrió.
• Poner claves en el mismo archivo de configuración que se commitea.
• Resolver dependencias entre plugins con un mensaje en el chat del equipo.
• Pensar que fijar el modelo es para siempre: los modelos se retiran y hay que planear la migración.

En el examen

Si un servicio se rompió porque cambió el modelo “solo”, buscá el ID explícito por servicio en configuración versionada, cambiado después de pasar evaluaciones. Si nadie sabe qué prompt corría, buscá prompts en control de versiones con la versión registrada en cada llamada. Si un plugin falla porque falta otro, buscá dependencies en su plugin.json.