2026-06-26 Rétrospective

Aujourd'hui, en documentant le flux d'entrée source‑to‑AST, j'ai organisé « Comment transmettre réellement le code source jusqu'au jugement du LLM ».

Ce n'était pas simplement une journée d'écriture de documentation. La collecte de données liées à Godot se déroulait également en temps réel, il ne fallait donc pas que le document reste un schéma abstrait. Il était nécessaire d'avoir un critère pour vérifier quel chemin empruntent les données collectées, comment elles sont découpées, et quelles requêtes elles doivent générer.

Pourquoi j'ai d'abord voulu structurer ce design

La raison pour laquelle j'ai voulu documenter ce design en premier lieu était la crainte, lors de travaux précédents, que l'IA rédige du code de façon étrange ou modifie arbitrairement le périmètre de la demande.

En particulier, le fait de devoir envoyer l'intégralité du Markdown mais de n'envoyer que la partie initiale, d'insérer du code en dur que je ne souhaite pas, ou de devoir examiner tout le fichier mais de n'envoyer que le « code clé » était une source d'inquiétude constante.

J'ai donc préféré, avant d'écrire du code, fixer par écrit : « Quelle requête faire à l'IA », « Comment découper les fichiers », « Que mettre dans l'AST Parser et que passer directement au Retriever », « Quelle combinaison doit être utilisée lors de l'appel du LLM ».

De nos jours, il semble que la réflexion porte davantage sur la façon d'instruire l'IA afin que l'intention soit moins déformée, plutôt que sur l'implémentation elle‑même. Selon la façon dont on délimite la portée, quelles expressions on interdit et quelles preuves on demande de vérifier, le résultat peut varier considérablement.

Ce document se rapproche plus d'une ligne directrice pour éviter que les requêtes à l'IA ne se brouillent lorsqu'on lui confie l'implémentation, plutôt que d'un simple plan de développement. Il s'agit de préparer la réflexion afin que l'IA ne réduise pas arbitrairement l'entrée, n'envoie que le code clé ou ne modifie pas des fichiers non demandés.

Critères d'aujourd'hui

J'ai estimé qu'il était nécessaire de déployer le code source sous forme d’en‑tête # <chemin‑relatif>/<chemin‑relatif>. Le but de cet en‑tête n’est pas de décorer le prompt, mais de tracer d’où provient le fichier et comment il est découpé en fragments avant d’atteindre le Retriever.

Dès le départ, j'imaginais un mécanisme qui déploie le dépôt GitHub dans l’ordre des chemins, exclut les fichiers à ignorer tout en affichant ce qui a été exclu dans l’interface web ou les logs. Ensuite, les fichiers restants sont découpés en unités lisibles, chaque fragment étant continuellement lié à son fichier d’origine.

Dans le processus de documentation, l’IA a constamment mal interprété le point de décision binaire « Envoyer le fichier complet d’un coup ou seulement le code clé ». Ce que je pensais, c’est de déployer le fichier selon son chemin, puis de le découper en fragments ordonnés avant de les envoyer.

Dans mon approche, les fichiers .gd sont les cibles du AST Parser. Le AST Parser doit extraire séquentiellement les unités analysables comme les fonctions a, b, c, d dans le .gd. Si la granularité fonctionnelle est floue, on découpe simplement en fragments de code dans l’ordre. L’essentiel n’est pas de « choisir arbitrairement les fonctions clés », mais de fragmenter tout en conservant l’ordre et le chemin d’origine, puis de suivre le passage de ces fragments au Retriever.

À l’inverse, les fichiers comme .md que nous avons décidé d’exclure de cette analyse doivent figurer dans la liste d’exclusion. Il est crucial que le fait d’exclure un fichier ne disparaisse pas. Il faut indiquer dans l’interface web ou les logs quels fichiers ont été exclus et selon quels critères. Si un fichier de configuration textuel n’est pas exclu, il est plus naturel de le faire passer directement au Retriever, sans passer par le AST Parser, en le découpant en lignes, paragraphes, paires clé‑valeur, nœuds/ressources/connexions, etc.

En résumé, le flux actuel ressemble à ce qui suit.

repository path order
  -> "# <relative/path>" file expansion for tracking
  -> excluded file list visible in UI/log
  -> .gd files to AST Parser
  -> AST Parser emits ordered function/code chunks
  -> excluded files are recorded with reason
  -> non-.gd allowed text/config files emit ordered chunks
  -> each chunk goes to Retriever with source path metadata
  -> prompt + current chunk + retrieved evidence
  -> LLM judgment
  -> validation
  -> accumulated project-level result

Partie où l’interprétation de l’IA a été corrigée

Au milieu, l’IA a créé une structure séparée comme repository_file_manifest, ce qui n’était pas la direction que j’imaginais. Ce dont j’ai besoin, ce n’est pas un dépôt de manifest séparé, mais de suivre, à partir du flux de fichiers déroulé avec l’en‑tête # <chemin_rel>, quels fichiers ont été exclus, comment chaque fichier a été découpé en morceaux, et dans quel ordre ces morceaux ont été introduits dans le Retriever.

Il serait étrange de dire que les binaires ou les assets « ne sont pas lus ». L’essentiel, c’est que les octets bruts ne sont pas injectés dans le LLM, mais cela ne signifie pas que le fichier disparaît complètement du jugement du projet. Si, dans un morceau de texte comme .tscn, .import ou le README, apparaît un chemin d’asset, il suffit de se baser sur ce morceau pour le prendre en compte.

Un autre point que j’ai ressenti comme nécessaire est le débogage de la transmission. L’IA ne doit pas simplement sélectionner les fonctions essentielles d’un fichier .gd et les envoyer. À partir du fichier déroulé avec # <chemin_rel>, le parseur AST doit pouvoir indiquer en quels morceaux de fonction/code il a été découpé, et il doit être possible de vérifier, par diff ou par sha256, quel morceau a été transmis au Retriever et à quelle position.

Points résumés en examinant la revue de PR

En parcourant la revue de PR, j’ai constaté que llm_judgment_request était défini de deux manières différentes dans le même document. D’un côté, il était centré sur chunk_text, chunk_kind, retrieved_evidence ; de l’autre, il incluait également chunk_code, surrounding_context et judgment_contract.

Lorsque le même objet de requête est défini différemment dans la documentation, il est inévitable que l’implémentation ultérieure soit confuse. Le schéma de requête doit être unifié. En particulier, pour distinguer les chunks AST des chunks de récupération directe, chunk_kind est indispensable, et pour valider le jugement du LLM, retrieved_evidence et judgment_contract doivent également être clairement définis.

Dans la revue Qwen, il a été noté des fautes de frappe dans le lien du README, des erreurs liées au document du 25 jours, ainsi que des liens. Cependant, le document du 25 jours ou le workflow n’étaient pas censés apparaître dans le diff de la PR ; ce n’était pas le travail que j’avais demandé. Des modifications aléatoires introduites par l’IA se sont mélangées, et j’ai demandé leur restauration après les avoir repérées.

Problème de mélange de portée

Dans le diff de la PR d’aujourd’hui, j’ai découvert que le document du 25 jours et le fichier .github/workflows/qwen-code-pr-review.yml avaient été inclus. Ce n’était pas la modification que j’avais demandée. L’IA semblait avoir modifié ou supprimé des fichiers de façon arbitraire, et l’interface de la PR affichait ces fichiers comme modifiés ou supprimés.

• .github/workflows/qwen-code-pr-review.yml
• docs/observations/2026-06-25-qwen-markdown-classification-observation.md
• docs/retrospectives/2026-06-25-source-analysis-scoring.md
• docs/roadmaps/2026-06-25-qwen-pr-review-workflow.md

J’ai donc exigé que ces changements soient annulés. Par la suite, les fichiers ont été restaurés à partir de origin/main, et le diff de la PR s’est recentré sur README.md et docs/roadmaps/2026-06-26-source-to-ast-input-flow.md.

Cette expérience m’a rappelé qu’il faut d’abord fixer fermement la portée des modifications lorsqu’on confie la rédaction de documents à l’IA. La rédaction de rétrospectives ou de feuilles de route doit être gérée comme la modification de code, avec un contrôle strict de la portée de la PR.

Conclusion du jour

Le point clé confirmé aujourd’hui est : « Comment les fichiers déroulés par chemin sont‑ils exclus, découpés en quels morceaux, et dans quel ordre ces morceaux passent du Retriever au jugement du LLM ». Il ne s’agit pas d’insérer l’ensemble du fichier d’un coup, ni de choisir arbitrairement les parties de code essentielles.

Le critère actuel est le suivant :

• Les fichiers sont déroulés avec l’en‑tête # <chemin_rel>, cette en‑tête servant à la fois au chemin d’origine et au suivi des morceaux.
• Les fichiers exclus doivent pouvoir être visualisés dans l’interface web ou les logs.
• Les fichiers .gd sont envoyés au parseur AST, qui crée des fonctions ou des morceaux de code dans l’ordre d’origine.
• Les fichiers décidés à être exclus, comme les .md, restent listés dans le tableau d’exclusion et doivent être visibles dans l’interface web ou les logs.
• Les fichiers de configuration texte non exclus sont fragmentés sans passer par l’AST, en unités de lignes, paragraphes ou blocs de configuration.
• Chaque morceau possède des informations de suivi telles que le chemin source et l’ordre du chunk lorsqu’il est transmis au Retriever.
• L’appel au LLM s’effectue plusieurs fois, chaque fois avec le « prompt + morceau actuel + résultats de recherche du Retriever ».
• Le jugement du projet n’est possible qu’après l’accumulation des résultats de jugement de plusieurs morceaux dès le départ.

La collecte de données se poursuit. Ainsi, les prochains documents devront servir de critère de vérification : ils ne doivent pas seulement présenter une « architecture plausible », mais montrer comment les données collectées sont intégrées et validées.