Me he montado un sistema de actualización de contexto para los proyectos que voy lanzando. 🙂
En este repositorio el sistema CONTEXT.md / AGENTS.md / CLAUDE.md funciona como una capa de instrucciones para humanos y agentes, no como parte de la app web en sí.
AGENTS.md y CLAUDE.md son puntos de entrada para asistentes distintos, y en este proyecto hacen exactamente lo mismo: obligan a leer primero CONTEXT.md y establecen una regla de mantenimiento después de cada commit.
AGENTS.md y CLAUDE.md. Su función es muy simple:
- decir “antes de tocar nada, lee CONTEXT.md”
- decir “después de cada git commit, ejecuta /update-context”
La pieza importante es CONTEXT.md. Ese archivo actúa como “single source of truth” del proyecto. Resume:
- qué hace la aplicación
- stack y punto de entrada
- arquitectura general
- mapa de funciones principales
- flujo de datos
- convenciones y decisiones técnicas
- estado actual y roadmap
En la práctica, la jerarquía aquí es esta:
- CONTEXT.md da el contexto operativo real para trabajar.
- El código fuente real sigue siendo la fuente definitiva del comportamiento, pero CONTEXT.md debería mantenerse alineado con él.
- Resumen corto: AGENTS.md y CLAUDE.md son “gatekeepers” para herramientas de IA; CONTEXT.md es la documentación operativa viva que esas herramientas deben leer antes de trabajar.
¿Qué os parece? Os dejo un prompt para crearlo en un momento.
Quiero que montes en este repositorio un sistema de contexto para agentes basado en tres archivos raíz:
* `CONTEXT.md`
* `AGENTS.md`
* `CLAUDE.md`
Objetivo:
Crear una capa de documentación operativa para humanos y agentes, de forma que cualquier asistente que entre al repo entienda rápidamente la arquitectura, las convenciones y el estado actual del proyecto.
Qué debe hacer cada archivo:
1. `CONTEXT.md`
Debe ser la fuente única de contexto operativo del proyecto.
Tiene que incluir, como mínimo:
* Resumen del proyecto
* Stack tecnológico
* Punto de entrada y estructura general
* Arquitectura o mapa de módulos
* Flujos de datos principales
* Convenciones técnicas y decisiones importantes
* Estado actual del proyecto
* Roadmap o siguientes pasos
* Riesgos, deuda técnica o notas relevantes si aplica
Requisitos:
* Debe escribirse a partir del código real del repositorio, no de suposiciones.
* Debe ser breve pero útil; orientado a trabajo práctico.
* Debe servir tanto para humanos como para agentes.
* Si hay partes inciertas, indícalas explícitamente.
2. `AGENTS.md`
Debe ser un archivo corto, tipo "entry point" para agentes en general.
Debe indicar:
* Que antes de empezar cualquier tarea hay que leer `CONTEXT.md`
* Que `CONTEXT.md` contiene la arquitectura, convenciones y estado actual
* Que después de cada `git commit` hay que actualizar `CONTEXT.md` para mantenerlo sincronizado con el repo
* Debe estar redactado de forma genérica, no ligada a un proveedor específico
3. `CLAUDE.md`
Debe contener el mismo mensaje operativo que `AGENTS.md`, pero pensado como punto de entrada compatible con flujos que busquen específicamente `CLAUDE.md`.
Puede ser igual o casi igual a `AGENTS.md`.
Cómo quiero que trabajes:
* Primero inspecciona el repo y entiende su estructura real
* Luego crea o actualiza estos archivos en la raíz
* No inventes arquitectura que no exista
* Si ya existen, mejóralos sin romper información útil
* Mantén el tono claro, operativo y conciso
Entregable:
* Crea o actualiza `CONTEXT.md`, `AGENTS.md` y `CLAUDE.md`
* Muéstrame un resumen corto de lo que has documentado
* Indica cualquier incertidumbre o zona del repo que haya quedado poco clara
