Les agents lisent votre dépôt. Cela couvre la plupart de leurs besoins — mais pas les décisions qui résident dans l'esprit des personnes, dans un wiki ou lors d'une conversation d'il y a deux ans.
Contexte du projet est l'endroit où vous ajoutez le reste.
Ce que Coroid détermine automatiquement
À partir du seul dépôt, les agents peuvent voir :
- les langages, frameworks et bibliothèques utilisés
- la manière dont le projet est construit, testé et exécuté
- les modèles existants — comment les erreurs sont gérées, comment les modules sont structurés, comment les éléments sont nommés
- ce qui dépend de quoi
Vous n'avez pas besoin de documenter tout cela. Le reformuler représente un effort inutile et risque de devenir obsolète par rapport au code, qui constitue de toute façon la source la plus fiable.
Ce qu'ils ne peuvent pas déduire
Le code montre quoi vous avez fait, jamais pourquoi:
- le choix d'une bibliothèque plutôt qu'une autre alternative évidente pour une raison toujours valable
- un modèle qui semble être une duplication mais qui constitue en réalité une séparation délibérée
- un module qu'il ne faut pas modifier sans consulter une équipe spécifique
- les conventions que vous avez convenues mais pas encore appliquées quelque part
- les contraintes externes au code — conformité, contrats, une migration en cours
C'est ce qui doit figurer dans le contexte du projet. Le test est simple : quelqu'un pouvant lire uniquement le dépôt pourrait-il le déduire ? Si oui, ne l'incluez pas. Si non, notez-le.
Ajouter du contexte
Joignez des documents, politiques et références sous la section Contexte du projet. Les notes d'architecture, les comptes-rendus de décision, les guides de style et les contrats API conviennent tous.
Un bon contexte est court et précis. Un guide d'intégration de 40 pages destiné aux humains est principalement constitué de récits ; les trois paragraphes qui énoncent les contraintes réelles sont ceux qui comptent. Extrayez-les.
Contexte par tâche
Le contexte attaché au projet s'applique à tout. Pour ce qui concerne une partie du travail spécifique — un ticket, un document de conception, un rapport client — attachez-le à la tâche plutôt qu'au projet.
Gardez le contexte du projet pour ce qui est durablement vrai. Une note liée à une tâche spécifique dans le contexte du projet devient du bruit pour toutes les tâches futures.
Maintenir l'exactitude
Un contexte obsolète est pire qu'aucun contexte, car les agents le considèrent comme une source faisant autorité. Lorsqu'une convention change, mettez à jour le contexte dans le même changement que celui du code.
Si vous remarquez que vous corrigez sans cesse la même chose dans les commentaires de retravail, c'est le signe qu'il manque quelque chose dans le contexte — ou qu'une information du contexte est erronée.