Lo que Claude recibe en cada interfaz y cómo pedirle un JSON confiable

Un prototipo anda perfecto en claude.ai: formatea lindo y sabe qué día es. Lo pasan a la API con el mismo texto y responde en párrafos planos y con la fecha mal. No cambió el modelo: cambió lo que el modelo recibe. Diseñar una aplicación con Claude empieza por saber qué contexto pone cada interfaz y qué tenés que poner vos.

Cada interfaz arma un contexto distinto

Interfaz	Qué agrega por su cuenta	Qué tenés que hacer vos
claude.ai y las apps de escritorio	Sus propias instrucciones de sistema (system prompt): fecha, hábitos de formato, herramientas	Nada; pero no esperes lo mismo en otro lado
API y SDKs	Nada: el modelo ve solo lo que mandás	Pasar la fecha, describir el formato, el rol y las reglas en tu system prompt
Claude Code	CLAUDE.md, reglas, skills y la configuración del proyecto como contexto	Bloquear lo prohibido con permisos o hooks, no con texto

El caso que más cae en Claude Code: CLAUDE.md dice “nunca corras migraciones en staging” y Claude igual la corre. CLAUDE.md es contexto, no una regla obligatoria. Para que una acción no pase nunca, hace falta una regla de denegación (deny rule) en los permisos o un hook PreToolUse en el .claude/settings.json compartido.

Límites de contenido: qué es instrucción y qué es dato

Los límites de contenido (content boundaries) separan lo que manda tu aplicación de lo que llega de afuera:

• las instrucciones estables van en el system prompt; los datos del pedido, en el mensaje de usuario;
• cada documento va entre etiquetas propias, con su fuente;
• el contenido externo (una página, un mail, un archivo) llega como resultado de herramienta y se trata como dato, nunca como orden.

Esquemas: el formato lo garantiza la API, no el pedido en prosa

Si tu código va a parsear la respuesta, no alcanza con “respondé en JSON”:

1. Definí el objeto como esquema JSON con salidas estructuradas (structured outputs), con los campos obligatorios marcados como requeridos.
2. Antes de parsear, mirá stop_reason. Con max_tokens la respuesta quedó cortada; con refusal el modelo se negó. Ninguna de las dos se trata como un JSON válido.
3. Después de parsear, validá las reglas de negocio: el esquema garantiza la forma, no que los números cierren.

Higiene de sesión y plugins

La higiene de sesión (session hygiene) evita que el contexto viejo contamine lo nuevo. En Claude Code, una sesión de todo el día que mezcla tareas sin relación arrastra código revertido y decisiones viejas. Conviene empezar cada tarea con /clear y dejar en CLAUDE.md solo lo que vale siempre.

Con los plugins pasa algo parecido: si cada uno los instala a mano desde una wiki, terminan con versiones distintas. El marketplace interno se declara en extraKnownMarketplaces y los plugins en enabledPlugins, en el .claude/settings.json versionado.

Las trampas típicas

• Culpar al modelo de una diferencia que viene del system prompt propio de claude.ai.
• Escribir la prohibición en CLAUDE.md con más énfasis, en lugar de una regla deny o un hook.
• Pedir el JSON en prosa, sumar ejemplos o bajar la temperatura en lugar de usar un esquema.
• Parsear sin mirar stop_reason, o sacar las validaciones porque “ya hay esquema”.
• Seguir en la misma sesión eterna y compensar con más instrucciones.

En el examen

Si el escenario compara dos interfaces, preguntate qué contexto pone cada una: la respuesta suele ser explicitar en la API lo que la app daba gratis. Si algo “no se respeta” en Claude Code, buscá permisos o hooks. Si el JSON falla de vez en cuando, buscá salidas estructuradas más el chequeo de stop_reason.