Los agentes leen tu repositorio. Eso cubre la mayor parte de lo que necesitan, pero no las decisiones que residen en la mente de las personas, en un wiki o en una conversación de hace dos años.
Contexto del proyecto Es donde incluyes el resto.
Lo que Coroid determina por sí solo
Solo con el repositorio, los agentes pueden ver:
- los lenguajes, frameworks y librerías en uso
- cómo se construye, prueba y ejecuta el proyecto
- patrones existentes: cómo se gestionan los errores, cómo se estructuran los módulos y cómo se nombran las cosas
- qué depende de qué
No necesitas documentar nada de esto. Reiterarlo supone un esfuerzo inútil y corre el riesgo de quedar obsoleto frente al código, que es la fuente más fiable.
Lo que no puede deducir
El código muestra qué hiciste, nunca por qué:
- una librería elegida en lugar de una alternativa evidente por una razón que sigue siendo válida
- un patrón que parece duplicado pero es una separación deliberada
- un módulo con el que nadie debe trabajar sin consultar a un equipo específico
- convenciones que han acordado pero que aún no se han aplicado en ningún sitio
- restricciones externas al código: cumplimiento normativo, contratos o una migración en curso
Esto es lo que debe incluirse en el contexto del proyecto. La prueba es sencilla: ¿podría alguien que solo leyera el repositorio averiguarlo? Si la respuesta es sí, déjalo fuera. Si es no, escríbelo.
Añadir contexto
Adjunta documentos, políticas y referencias en la sección de Contexto del proyecto. Las notas de arquitectura, los registros de decisiones, las guías de estilo y los contratos de API son válidos.
Un buen contexto es breve y específico. Una guía de incorporación de 40 páginas escrita para humanos contiene mayormente narrativa; los tres párrafos que indican restricciones reales son los que importan. Extrae esos.
Contexto por tarea
El contexto adjunto al proyecto se aplica a todo. Para algo relevante para una sola tarea —una incidencia, un documento de diseño o un informe de cliente— adjúntalo a la tarea en lugar de al proyecto.
Mantén el contexto del proyecto para lo que sea permanentemente cierto. Una nota específica de una tarea en el contexto del proyecto se convierte en ruido en todas las tareas futuras.
Mantenerlo actualizado
Un contexto desactualizado es peor que no tener contexto, porque los agentes lo tratan como autoritativo. Cuando cambia una convención, actualiza el contexto en la misma modificación que altera el código.
Si te encuentras corrigiendo repetidamente lo mismo en los comentarios de re trabajo, eso indica que falta algo en el contexto o que algo en él es incorrecto.