Ingeniería de contexto, memoria y planificación
Más contexto no significa automáticamente más calidad. Este módulo enseña a seleccionar lo que cambia una decisión, a mantener concisas las instrucciones del proyecto y a verificar lo que sobrevive entre sesiones.
Qué trabajarás, paso a paso
Cuatro fuentes prácticas del contexto
Cuando trabajas con un agente, el contexto no es un único montón de información. Es el conjunto de lo que el agente puede usar para decidir el siguiente paso. Separar sus tipos te ayuda a entender qué proporcionar, qué verificar y qué conviene dejar fuera.
Aquí usamos cuatro fuentes prácticas, no una lista completa de todo lo que puede entrar en el contexto: la solicitud actual, los archivos y las salidas observadas, las instrucciones persistentes y la memoria. `CLAUDE.md` contiene reglas escritas por ti; la auto memory contiene notas que Claude conserva entre sesiones. Confundirlas produce reglas temporales que se vuelven permanentes o recuerdos antiguos tratados como hechos actuales.
Cada elemento debería responder a una pregunta: ¿sirve para decidir ahora? ¿Seguirá siendo cierto la próxima semana? ¿Se puede verificar en el repositorio? ¿Contiene datos que no deberían compartirse?
Debes mostrar EUR o USD junto al total. El repositorio contiene un modelo Invoice, una función de formateo y una nota antigua que habla solo de euros.
- Escribe la solicitud actual en una frase verificable: «muestra la moneda guardada en la factura, sin cambiar los importes existentes».
- Abre el modelo, las migraciones, el formateador y las pruebas: descubres que el campo currency ya existe y que USD ya está permitido por la base de datos.
- Lee las instrucciones estables: para el dinero el proyecto exige Intl.NumberFormat y prohíbe conversiones implícitas. Trata la nota antigua sobre el euro como memoria que hay que verificar, no como verdad.
- Construye el contexto final con esos archivos, la restricción del formato y dos facturas de prueba; excluye volcados de clientes y claves del servicio de pagos.
Resultado: El agente puede hacer un cambio pequeño y coherente: usa el campo ya disponible, respeta la convención del proyecto y no asume que todas las facturas estén en euros.
Instrucciones de proyecto que de verdad ayudan
Las instrucciones del proyecto son un pequeño manual operativo para quien interviene en el código. No deben contar toda la historia del producto: deben evitar los errores que una simple lectura de los archivos no hace evidentes.
Un buen archivo de instrucciones indica comandos fiables, límites arquitectónicos, convenciones no obvias y Definition of Done. Evita biografías del proyecto, opiniones duplicadas e información que ya es fácil de leer en los archivos.
Escribe reglas positivas y verificables: «ejecuta pytest -q» es más operativo que «ten cuidado con las pruebas». Recuerda, sin embargo, que `CLAUDE.md` guía al modelo, no es un firewall: una regla que debe activarse siempre debe volverse técnica mediante permisos, hooks o pruebas. Añade excepciones solo cuando exista un motivo real y elimina una regla cuando ya no sea verdadera.
En el sitio, algunas personas modifican directamente `messages.generated.json`; en la siguiente build el generador lo sobrescribe todo y la traducción desaparece.
- Confirma a partir de los archivos de build que `messages.generated.json` realmente es generado e identifica `locales/source.it.json` como fuente editable.
- Añade una instrucción positiva: modifica solo el archivo fuente y luego ejecuta `npm run i18n:build`; no te limites a escribir «no toques los archivos equivocados».
- Indica la prueba: `git diff` debe mostrar tanto la fuente como el archivo generado, y `npm run i18n:check` debe terminar sin claves faltantes.
- Prueba la instrucción con una etiqueta nueva y haz que lea el texto una persona que no conoce el generador; si tiene que preguntar qué archivo abrir, la regla sigue estando incompleta.
Resultado: La siguiente modificación sigue un recorrido repetible y deja una prueba. El archivo de instrucciones contiene una convención no obvia, no una copia de la documentación general.
Compactar sin perder el contrato
Compactar significa transformar una conversación larga en un handoff breve. El objetivo no es recordar cada frase: es conservar el contrato operativo necesario para retomar el trabajo sin reinterpretarlo.
Cuando una conversación crece, una síntesis reduce el volumen pero puede eliminar detalles. Antes de la compactación, identifica decisiones, restricciones, archivos modificados, pruebas obtenidas y trabajo restante. Después, comprueba que estos elementos sigan siendo explícitos.
Una nueva sesión debería poder retomar el trabajo a partir del repositorio y de un breve handoff, no de una confianza ciega en la memoria. Después de `/compact`, Claude Code relee el `CLAUDE.md` de la raíz; las instrucciones anidadas y las reglas ligadas a una ruta vuelven cuando reabres los archivos pertinentes. El estado de los archivos sigue siendo, en cualquier caso, la fuente principal de lo que realmente ha cambiado.
Has aislado un doble cargo cuando el usuario pulsa dos veces «Pagar». La sesión es larga y debes interrumpirla antes de la verificación completa.
- Registra el contrato: una sola solicitud de pago por pedido, ningún cambio en el flujo de reembolso y ningún log con datos de la tarjeta.
- Anota la decisión: usar una clave de idempotencia derivada del pedido; señala que el intento de desactivar solo el botón se descartó porque no cubre solicitudes duplicadas desde la red.
- Enumera los archivos realmente modificados y la prueba disponible: la nueva prueba fallaba antes del parche y queda en verde después; la prueba end-to-end todavía no se ha ejecutado.
- Al retomar, compara handoff, `git status` y diff, y después ejecuta la comprobación pendiente en un entorno de prueba antes de declarar terminado el trabajo.
Resultado: La nueva sesión parte del riesgo que sigue abierto, no reconstruye toda la discusión y no confunde una prueba unitaria exitosa con una verificación completa del pago.
Plan antes de la ejecución
No todo trabajo merece un plan enorme. Cambiar una etiqueta puede requerir tres líneas; cambiar datos leídos por dos versiones de la aplicación requiere fases compatibles y una vía de retorno. Un plan útil hace visible precisamente esa diferencia antes de que empiece la parte costosa.
La planificación es útil cuando el cambio atraviesa varios límites, existen alternativas reales o el coste de un error es alto. El plan debe nombrar archivos, dependencias, verificaciones y decisiones abiertas; no debe simular certeza sobre detalles que todavía no se han inspeccionado.
Para un cambio local y reversible puede bastar un plan de tres líneas. La profundidad del razonamiento debe ser proporcional al riesgo: dedicar mucho tiempo a un cambio obvio es tan ineficiente como improvisar una migración compleja.
- Define el resultado, los límites y el riesgo del cambio.
- Identifica los archivos, las instrucciones y las fuentes que pueden cambiar la decisión.
- Escribe pasos pequeños con dependencias y decisiones aún abiertas.
- Asocia a cada paso una prueba observable.
- Aprueba la ejecución solo cuando el plan sea verificable.
Quieres sustituir `customer_name` por `first_name` y `last_name`, pero la antigua aplicación móvil seguirá activa durante el despliegue.
- Mapea los lectores y escritores de la columna y señala la incógnita principal: para algunos clientes solo existe un nombre de empresa, así que la división automática no es fiable.
- Planifica una fase compatible: añade las nuevas columnas nullable, sigue leyendo el campo antiguo y haz que la nueva API escriba ambos formatos.
- Prepara un backfill repetible sobre una copia de los datos, cuenta los registros ambiguos y define una parada segura si el número supera el umbral acordado.
- Elimina la columna antigua solo después de métricas estables, adopción de la nueva aplicación y prueba de rollback; asocia a cada fase consultas de control y pruebas de compatibilidad.
Resultado: El cambio se convierte en una secuencia reversible. Los casos ambiguos no se inventan y la aplicación antigua sigue funcionando durante la transición.
Instrucciones estables en CLAUDE.md
El proyecto tiene un comando de prueba y un límite importante sobre los datos.
# Comandos
- Test: pytest -q
# Restricciones
- No cambies el formato de las tareas sin una migración aprobada.
# Definition of done
- Test y lint en verde; resumir diff y riesgos residuales.