Tres lecciones clave de 400,000 sesiones con Claude Code

Introducción

Anthropic evaluó aproximadamente 400,000 sesiones de Claude Code realizadas por más de 235,000 usuarios y buscó señales claras de éxito: tests que pasan, commits que se integran y usuarios que confirman haber obtenido lo solicitado. Lejos de ser solo una cuestión de gusto, el estudio encontró patrones de comportamiento reproducibles que distinguieron las sesiones eficaces de las que no lo fueron.

Los tres elementos que Anthropic extrajo del análisis de los transcripts fueron:

• Precisión: cuán concretas y completas son las instrucciones.
• Verificación: qué pidió el usuario que Claude revisara antes de aceptar la respuesta.
• Dirección de la corrección: si el humano corregía a Claude o viceversa.

Un punto clave: la “experiencia” aquí es específica a la tarea. Ser un experto en un rol no garantiza pericia en cada problema puntual; lo que importa es cómo se estructura la interacción.

Lección 1: Precisión en la forma de preguntar

La diferencia entre sesiones primerizas y expertas no estuvo en la longitud de la petición, sino en si la instrucción contenía lo que Claude no puede inferir por sí mismo: qué archivo, qué escenario, qué significa terminar y qué patrón seguir.

Anthropic observó que, en promedio, las sesiones novatas generaban ~5 acciones de Claude y ~600 palabras por prompt, mientras que las expertas generaban ~12 acciones y ~3,200 palabras por prompt. No se trata de hablar más, sino de dar lo que falta.

Actualice sus peticiones con estos cuatro elementos:

• Localización: indique el archivo o pegue el fragmento relevante.
• Escenario: describa el caso de uso concreto o la condición que queremos reproducir.
• Criterio de terminado: cómo sabremos que esto está resuelto (por ejemplo, tests que pasan, outputs específicos).
• Patrón a seguir: nombre ejemplos o archivos de referencia para mantener consistencia.

Ejemplos prácticos (versión resumida):

• En lugar de “añade tests para foo.py”, diga: “escribe un test para foo.py que cubra el caso en que el usuario no está autenticado; no usar mocks”.
• En vez de “por qué ExecutionFactory tiene esa API rara?”, pida: “revisa el historial de commits de ExecutionFactory y resume cómo evolucionó su API”.
• Más útil que “añade un widget de calendario”: “usa HotDogWidget.php como patrón; calendar widget con selección de mes y paginación por año; no agregar librerías nuevas”.
• Para un bug de login: “los usuarios reportan fallos tras timeout de sesión. Revisa src/auth/, especialmente token refresh. Escribe un test que reproduzca el fallo y arréglalo”.

Un hábito que acelera todo: en vez de describir dónde está algo, páselo directamente. Pegue el archivo, reenvíe logs o arrastre capturas. Por ejemplo:

• Referencie un archivo inline para que Claude lo lea antes de responder: “Explica la lógica de token refresh en @src/auth/session.ts”.
• Pipee logs: cat error.log | claude -p "agrupa estos errores por causa raíz".
• Pegue imágenes o pantallas para que Claude pueda interpretarlas.

Además, dé a Claude las herramientas correctas. Las CLI (gh, aws, gcloud, sentry-cli) son muy eficientes porque devuelven salidas compactas que Claude entiende rápidamente. Para servicios sin una CLI buena, los MCP servers ayudan a exponer lo necesario.

Finalmente, para tareas mayores a un día de trabajo, deje que Claude lo entreviste. Use una instrucción como: “Quiero construir [breve descripción]. Hazme una entrevista detallada con AskUserQuestion sobre implementación, UI/UX, edge cases y tradeoffs. Sigue hasta cubrir todo y escribe un SPEC.md”. Ese SPEC.md fungirá como contrato claro antes de implementar.

Lección 2: Déle a Claude algo que pueda verificar

El hábito que más retorno da, y que con más frecuencia falta, es pedir checks automáticos. Claude suele detenerse cuando “luce hecho”; si no hay una verificación que pueda ejecutar, el aspecto terminado será la única señal y todo el ciclo de revisión queda en la persona.

Cómo aplicar esto:

• Pida tests que reproduzcan el bug antes de pedir la solución. Un test que falla y luego pasa es una prueba objetiva.
• Defina un chequeo de extremo a extremo: scripts que ejecuten el flujo e indiquen un resultado esperado.
• Solicite salidas canónicas (golden outputs) o snapshots para comparar.
• Integre verificaciones en CI y pida que Claude genere los jobs o scripts necesarios.
• Use linting, análisis estático y pruebas unitarias como criterios de aceptación.

Ejemplo de flujo: “Escribe un test que falle reproduciendo el problema X, implementa la corrección y añade una prueba de regresión. Luego actualiza el pipeline de CI para correr ese test”.

Cuanto más explícito sea el “cómo verificar”, menos dependerá de la revisión manual y menor será el riesgo de errores ocultos.

Lección 3: Quién termina corrigiendo a quién

El estudio también midió la dirección de la corrección: si el humano corregía a Claude o si Claude corregía al humano. Las sesiones exitosas mostraron un balance claro: el usuario dirige la validación y hace correcciones finales cuando es necesario.

Recomendaciones prácticas:

• Mantenga el rol de verificador humano: use a Claude para proponer cambios y pruebas, pero reserve la aprobación final.
• Pida a Claude que explique cada cambio (diff + resumen) y que agregue pruebas que demuestren su corrección.
• Si Claude propone correcciones a decisiones de diseño, solicite justificaciones concretas y una opción que respete la decisión original cuando corresponda.

Un flujo de trabajo que une las tres lecciones

1. Entrevista inicial con Claude para crear SPEC.md.
2. Inicie una sesión nueva para implementar (limpia, con contexto acotado).
3. Entregue archivos relevantes o URLs y permita que Claude los consulte.
4. Pida una propuesta de cambio con tests que reproduzcan el problema.
5. Ejecute o integre los tests en CI; devuelva los resultados para iterar.
6. Exija un checklist final que incluya pruebas automatizadas y una comprobación end-to-end.

Cinco formas comunes en que las sesiones salen mal

• Ambigüedad en la petición: falta de escenario y criterio de terminado.
• Ausencia de artefactos: no proporcionar archivos, logs o URLs relevantes.
• Falta de checks: no hay tests ni scripts para verificar los cambios.
• Herramientas inadecuadas: no usar CLIs o conexiones que faciliten acciones reproducibles.
• Contexto mezclado: mantener una sesión larga con historia irrelevante que confunde al modelo.

Escalando más allá de una sesión

Para características grandes, trabajar en sesiones separadas por etapa (especificación, implementación, revisión) mantiene el contexto ordenado y facilita auditoría. El SPEC.md es el hilo conductor y debería estar en el repositorio como referencia única.

Qué me dejó este análisis (para equipos de América Latina)

La lección más valiosa es que la brecha no estaba en el modelo, sino en el comportamiento humano. Equipos en América Latina que suelen enfrentar restricciones de tiempo, comunicación asíncrona y diversidad de stack pueden beneficiarse mucho adoptando estas prácticas: pedir verificaciones automatizables, dar contexto preciso y usar las herramientas adecuadas reduce retrabajo y acelera entregas.

Si implementan estas tres pautas —precisión, verificabilidad y control humano sobre correcciones— convertirán a Claude en un colaborador consistente, no en una apuesta ocasional.