Contexto, memoria e instrucciones

El contexto es la memoria operativa del arnés. Sin contexto estable, cada sesión depende demasiado de lo que se escriba en el chat y de lo que el modelo infiera.

Archivos clave

`AGENTS.md`

Describe cómo debe comportarse la IA dentro del repositorio. Puede incluir:

Comandos de build, test y análisis.
Convenciones de edición.
Restricciones del proyecto.
Flujo de trabajo esperado.
Criterios para pedir aclaración.
Reglas sobre ramas, commits o PRs.

`docs/Architecture.md`

Explica la arquitectura del sistema:

Módulos.
Responsabilidades.
Patrones.
Límites entre capas.
Puntos compartidos.
Riesgos conocidos.

`docs/CodeConventions.md`

Recoge convenciones de implementación:

Estilo de nombres.
Patrones de componentes.
Gestión de estado.
Tratamiento de errores.
Testing.
Organización de archivos.

`docs/Commands.md`

Define cómo lanzar, compilar, testear y validar el proyecto.

`specs/README.md`

Define cómo se organizan las specs por necesidad o tarea:

specs/
  PROY-123/
    spec.md
    design.md
    tasks.md

Cómo debe ser buen contexto

Buen contexto no significa documentación enorme. Significa documentación útil, actualizada y accionable.

Debe ser:

Clara para una persona nueva.
Concreta para una IA.
Mantenible por el equipo.
Cercana al código.
Revisable mediante PR.

Memoria y aprendizaje continuo

Cuando una tarea revela una regla, excepción o fallo recurrente, decide dónde debe quedar:

Contexto de proyecto.
Skill.
Guardarraíl.
Troubleshooting.
Spec o decisión técnica.

El aprendizaje que no vuelve al repositorio se pierde.

Errores habituales

Documentar principios genéricos sin decisiones reales.
Duplicar información contradictoria.
No actualizar el contexto cuando cambia la arquitectura.
Escribir instrucciones largas que nadie revisa.
Usar el contexto para preferencias que no se aplican en el código.

Default recomendado

Si una misma aclaración se repite tres veces durante tareas distintas, debe convertirse en contexto, memoria o regla explícita.