Aller au contenu principal
CODIR

Ce qu'un projet sait de lui-même n'est écrit nulle part

Rémi Alvado
Rémi AlvadoCTO & CPO Fractional · 20 ans d'expérience
Publié le•7 min de lecture

La mémoire d'un projet vit dans la tête de trois ou quatre personnes et part avec elles. Une poignée de documents versionnés suffit à l'écrire.

Ce qu'un projet sait de lui-même n'est écrit nulle part

Posez-vous la question une seconde, elle est plus dérangeante qu'elle n'en a l'air : ce que votre projet sait de lui-même, c'est écrit où ? Je ne parle pas du code, le code est écrit par définition. Je parle de tout le reste.

Dans la plupart des organisations que je croise, ce qu'un projet sait de lui-même n'est écrit nulle part : ça vit dans la tête de trois ou quatre personnes, et ça part avec elles. Le rendre explicite ne demande pas un outil de plus, mais une poignée de documents versionnés à côté du code, un par question que le projet se pose vraiment.

Faites le test sur votre propre projet, maintenant

Prenez le projet sur lequel vous travaillez, et cherchez où sont écrites les réponses à ces questions. Le paysage concurrentiel : qui est déjà sur ce marché, et où se trouve le trou dans lequel vous vous engouffrez. Les raisons derrière vos choix d'architecture, pas les choix eux-mêmes mais ce qui les a dictés. À quoi ressemble le produit. Ce que vous vendez, et à quel prix. D'où vient l'argent. Qui arrive dans l'équipe, et dans quel ordre. Ce qu'il faut faire quand la production casse à trois heures du matin. Ce qu'il faut répondre quand un prospect dit non. Dans la grande majorité des cas, rien de tout ça n'existe sous forme écrite.

Ce n'est pas un problème d'intelligence artificielle. C'était vrai avant que des agents lisent les dépôts, et ça le restera si l'IA passe de mode. Ce qu'ils ont changé, c'est qu'ils ont rendu le trou mesurable. Un humain comble les blancs sans s'en apercevoir : il était à la réunion, il connaît la personne à qui demander, il sent que la contrainte de départ a disparu. Un agent n'a rien de tout ça, il ne peut utiliser que ce qui est écrit. La première fois que j'en ai lancé un sur un projet documenté normalement, le constat n'a pas porté sur l'agent, mais sur ce que je lui avais donné à lire.

La liste tient sur une page, et le code n'en fait pas partie

Voilà la liste que j'utilise aujourd'hui sur les projets que j'accompagne. Onze fichiers, dont les noms ci-dessous viennent d'un produit fictif qui me sert de fil rouge. Elle n'a rien d'original, et c'est précisément ce qui la rend utilisable : chaque fichier répond à une question qu'on se pose réellement, une seule, et il n'y a qu'un fichier par question. Le nom exact n'a aucune importance, vous les appellerez comme vous voudrez. Ce qui compte est qu'il existe un endroit unique et évident où aller chercher chaque réponse, et surtout où l'écrire le jour où elle change. C'est cette évidence qui sépare une mémoire d'un dossier partagé où chacun dépose sans que personne relise.

FichierCe qu'il répond
docs/vision.mdla phrase qui tient tout le reste
docs/marche/concurrence.mdqui est déjà là, et où est le trou
docs/business/modele.mdce qu'on vend, et à quel prix
docs/equipe/phasing.mdqui arrive, et dans quel ordre
docs/business/financement.mdd'où vient l'argent
docs/tech/architecture.mdcomment c'est branché
docs/tech/choix.mdce qu'on a choisi, et pourquoi
design/maquettes.figà quoi ça ressemble
docs/prd/relances.mdce qu'on construit, précisément
docs/ops/runbooks/relances-bloquees.mdquoi faire quand ça casse, à 3 h du matin
docs/vente/argumentaire.mdquoi répondre quand on nous dit non

Relisez cette liste et regardez ce qu'elle contient vraiment. Un seul de ces fichiers décrit de la plomberie. Tous les autres parlent de marché, d'argent, de personnes, de produit, de ce qu'on répond au téléphone quand un prospect hésite. C'est la première surprise pour les équipes techniques qui s'y mettent : l'essentiel de ce qui manque n'est pas technique. La seconde compte davantage : le code ne figure pas dans la liste. Le code décrit ce que le système fait aujourd'hui, il ne dit jamais ce qu'on a essayé avant, ce qu'on a écarté, ni ce qui rendait une option impossible à l'époque.

Regardez maintenant la ligne des maquettes. Ce fichier n'est ni du Markdown, ni rangé dans docs/, et il répond pourtant à une question qu'aucun texte ne traite correctement : à quoi ça ressemble. Il compte autant que les dix autres, et je le signale parce qu'il désamorce la lecture paresseuse de tout ce qui précède, celle qui traduit « écrire la mémoire du projet » par « rédiger de la documentation ». La mémoire d'un projet montre autant qu'elle raconte. La règle n'est pas le format, c'est la question : un artefact mérite sa place dès qu'il répond seul, sans mode d'emploi, à une question que quelqu'un reposera.

« Et pourquoi » est le mot le plus important de cette liste

Deux lignes du tableau se terminent par « et pourquoi », et ce n'est pas de la coquetterie de rédaction. Un choix d'architecture sans sa raison est strictement inutilisable. Six mois plus tard, quelqu'un ouvre le fichier, lit qu'on a retenu telle base de données ou telle découpe de services, et se retrouve devant deux issues également mauvaises. Soit il conserve le choix par superstition, parce qu'il n'ose pas toucher à une décision dont il ignore les fondations. Soit il le remplace en toute bonne foi, et réintroduit méthodiquement le problème que ce choix réglait, sans comprendre pourquoi les mêmes symptômes reviennent.

Un choix sans sa raison n'est pas une décision, c'est une habitude dont plus personne n'ose discuter.

ce que je répète devant une documentation technique impeccable et inutilisable

C'est exactement ce qui sépare une documentation d'une mémoire. Une documentation décrit un état : voilà ce qui est. Une mémoire explique comment on y est arrivé, et c'est ce qui permet d'en sortir, parce qu'elle rend la décision discutable à nouveau. Pour un agent, la différence est encore plus nette. Donnez-lui l'état sans la raison, et il optimisera consciencieusement contre une contrainte que vous aviez acceptée exprès. Donnez-lui la raison, et il vous signalera de lui-même qu'elle a disparu, ce qui est précisément ce qu'on attend d'un bon collaborateur. Écrire la raison coûte deux phrases au moment de la décision, ne pas l'écrire se paye des années plus tard.

Pourquoi ça vit dans le dépôt, et pas dans un outil de documentation

Trois propriétés, et aucune ne tient à la technique. La première : c'est versionné. Vous voyez quand une décision a changé, par qui et dans quel mouvement, parce que le document est modifié dans le même commit que le code qui l'applique. La deuxième : c'est relu en revue, comme du code. Une phrase fausse se discute en commentaire de pull request, devant témoins, au moment où elle est écrite. La troisième est la plus importante : le document vieillit au même rythme que ce qu'il décrit. Si une modification change le comportement sans toucher au document, le relecteur le voit passer. Une page de wiki, elle, vieillit toute seule, en silence.

L'objection arrive toujours au même endroit : et les gens qui ne savent pas se servir de git ? Elle est légitime, et elle se traite. J'ai écrit comment je donne accès à cette mémoire à un fondateur non développeur, sans compte GitHub et sans rien lui demander d'apprendre, et comment le dépôt devient la mémoire vivante du projet pour les humains comme pour les agents. L'accès est un problème d'outillage, qui se résout en quelques heures. L'endroit où vit la vérité, lui, est un problème d'organisation, et aucun abonnement ne le règle. La question n'est jamais l'outil, elle est de savoir où se corrige la réponse.

Le bénéfice qu'on sous-estime n'est pas celui qu'on croit

Oui, tout ça sert aux agents, et c'est ce qui décide beaucoup d'équipes à s'y mettre. Mais ce n'est pas le bénéfice principal, et le contresens coûte cher. Le bénéfice principal, c'est la personne qui arrive. Aujourd'hui, intégrer un arrivant consiste à interrompre pendant des semaines les quelques personnes qui savent, en espérant poser les bonnes questions. Ces documents transforment cette dépendance en lecture. C'est aussi le seul argument qui tiendrait debout si l'IA disparaissait demain, et le meilleur test d'honnêteté : rédigez pour la personne qui arrivera dans six mois et n'était à aucune de vos réunions. L'agent, lui, s'en sortira très bien avec ça. L'inverse n'est pas vrai.

Par où commencer quand vous n'avez rien

Deux fichiers d'abord, et dans cet ordre : la vision, puis les choix techniques. La vision parce qu'elle arbitre tout le reste, et parce qu'une équipe qui n'arrive pas à l'écrire en une page découvre souvent, à cette occasion, qu'elle n'est pas d'accord avec elle-même. C'est inconfortable, et c'est exactement le but. Les choix techniques ensuite, parce que c'est la connaissance qui se périme le plus vite dans les têtes, et de loin la plus coûteuse à reconstituer : les raisons d'un arbitrage s'oublient en quelques mois, alors que leurs conséquences vous accompagnent des années. Tout le reste peut attendre quelques semaines sans dommage.

Le reste vient par le travail, pas par un chantier dédié. Vous écrivez le document sur la concurrence le jour où vous regardez la concurrence, le runbook le lendemain de l'incident, les maquettes quand vous dessinez. Bloquer un trimestre pour « faire la documentation » ne fonctionne jamais : ça produit un corpus mort que personne ne relira, et qui décrédibilise l'exercice pour longtemps. Écrit au fil de l'eau, chaque document coûte vingt minutes. Si vous voulez le cadre complet dans lequel cette mémoire s'inscrit, le guide de l'IA agentique le détaille, et l'accompagnement que je propose commence presque toujours par là, avant de parler d'outils.

Rien de ce que je décris ici n'est nouveau, et c'est bien ce qui me gêne. Ces questions auraient dû être écrites depuis longtemps, et les équipes qui l'ont fait n'ont pas attendu les agents. Ce qui a changé, c'est le coût de ne pas le faire. Une organisation dont la mémoire tient dans trois têtes a toujours été fragile ; elle est désormais lente, parce qu'elle ne peut déléguer ni à un arrivant ni à une machine. Je ne connais aucun projet où cette liste soit complète, le mien compris. Ce n'est pas le but. Le but est qu'il existe un endroit évident où écrire la réponse, le jour où quelqu'un pose enfin la question.

Et maintenant ?

Où en êtes-vous ?

Choisissez la situation qui vous ressemble. Pour chacune : ce que je vous conseille de lire, et ce que je peux faire avec vous.

  1. Je veux mettre mes équipes à l'IA agentique

    Par où commencer, dans quel ordre, et avec quels garde-fous.

  2. Personne en interne ne sait arbitrer la technique

    Les choix se prennent sans vous, et vous en découvrez les effets après coup.

  3. Mon équipe grandit et l'organisation ne suit plus

    Ce qui marchait à cinq ne marche plus à quinze.

Prendre RDV