2026-06-26 Rückblick | idea_world

Heute habe ich den Eingabefluss source-to-AST dokumentiert und dabei festgehalten, „wie der Quellcode tatsächlich an die LLM‑Bewertung übergeben wird“.

Es war nicht nur ein Tag, an dem ich Dokumente schrieb. Die Datensammlung zu Godot läuft ebenfalls in Echtzeit, sodass das Dokument nicht nur ein abstraktes Design bleiben durfte. Es musste ein Kriterium geben, um zu prüfen, welchen Weg die gesammelten Daten tatsächlich nehmen, in welche Einheiten sie zerlegt werden und welche Anfragen daraus resultieren.

Warum ich dieses Design zuerst festhalten wollte

Der Grund, warum ich dieses Design zuerst dokumentieren wollte, war die Sorge aus vorherigen Arbeiten, dass die KI Code merkwürdig erzeugen oder den Anforderungsumfang willkürlich ändern könnte.

Insbesondere war ich besorgt, dass man die gesamte Markdown‑Datei senden muss, aber nur einen Teil am Anfang sendet, oder dass unerwünschtes Hard‑Coding eingefügt wird, oder dass man die gesamte Datei sehen muss, aber nur den „Kerncode“ auswählt und sendet.

Deshalb wollte ich nicht sofort Code schreiben, sondern zuerst dokumentieren: „Welche Anfragen an die KI gestellt werden müssen“, „In welchen Einheiten die Dateien aufgeteilt werden“, „Was dem AST‑Parser und was dem Retriever direkt übergeben wird“, „Welche Kombinationen beim LLM‑Aufruf nötig sind“.

Heutzutage denke ich mehr darüber nach, wie man der KI Anweisungen gibt, damit die Intention weniger verzerrt wird, als über die eigentliche Implementierung. Je nachdem, wie man den Umfang festlegt, welche Formulierungen verbietet und welche Beweise überprüft werden sollen, kann das Ergebnis stark variieren.

Dieses Dokument ist weniger ein einfacher Entwicklungsplan, sondern eher eine Leitlinie, damit Anfragen an die KI später nicht verwässert werden. Es soll verhindern, dass die KI Eingaben reduziert, nur den Kerncode auswählt oder Dateien ändert, die nicht angefordert wurden, indem man die Überlegungen im Voraus festhält.

Heutiger Stand

Der Quellcode sollte mit Headern der Form # <relativer Pfad>/<relativer Pfad> ausgeklappt werden. Der Zweck dieses Headers ist nicht, ihn als Dekoration in den Prompt einzufügen, sondern nachzuverfolgen, aus welchem Pfad die Datei stammt und in welche Stücke sie zerlegt wird, bevor sie zum Retriever gelangt.

Von Anfang an dachte ich, das GitHub‑Repository in Pfad‑Reihenfolge auszuklammern, auszuschließende Dateien auszublenden, aber sichtbar zu machen, welche Dateien ausgeschlossen wurden, etwa über eine Web‑UI oder Logs. Die verbleibenden Dateien sollten dann in lesbare Einheiten zerlegt werden, wobei jedes Stück stets seiner Ursprungsdatei zugeordnet bleibt.

Während der Dokumentation stellte die KI immer wieder die binäre Frage „Soll die gesamte Datei auf einmal gesendet werden oder nur der Kerncode?“. Meine Vorstellung war jedoch, die Datei zuerst nach Pfad auszuklammern und dann Stück für Stück in Reihenfolge zu senden.

In meinem Ansatz sind .gd‑Dateien die Eingabe für den AST‑Parser. Der AST‑Parser muss aus einer .gd‑Datei parse‑bare Einheiten wie die Funktionen a, b, c, d nacheinander extrahieren. Wenn Funktionsgrenzen unklar sind, kann man stattdessen Code‑Schnipsel in Reihenfolge senden. Wichtig ist nicht, „nur die Kernfunktionen auszuwählen“, sondern die Originalreihenfolge und Pfade beizubehalten, die Stücke zu fragmentieren und deren Weg zum Retriever nachzuverfolgen.

Im Gegensatz dazu sollten Dateien wie .md, die in dieser Quellcode‑Analyse ausgeschlossen werden, in einer Ausschlussliste landen. Wichtig ist, dass das Ausschließen nicht verschwindet. Es muss in der Web‑UI oder in Logs angezeigt werden, nach welchen Kriterien welche Datei ausgeschlossen wurde. Textbasierte Konfigurationsdateien, die nicht ausgeschlossen werden, sollten ohne den AST‑Parser direkt in Zeilen, Absätze, Schlüssel‑Wert‑Paare, Knoten/Ressourcen/Verbindungen usw. zerlegt und dem Retriever zugeführt werden.

Zusammengefasst sieht der aktuelle Ablauf etwa so aus.

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

Abschnitt, in dem die KI‑Interpretation korrigiert wurde

In der Mitte hat die KI eine separate Struktur wie repository_file_manifest erstellt, was nicht meiner Vorstellung entsprach. Was benötigt wird, ist kein separates Manifest‑Repository, sondern die Nachverfolgung, welche Dateien anhand des mit # <relative Pfad> ausgeklappten Dateiflusses ausgeschlossen wurden, welche Dateien in welche Stücke zerlegt wurden und in welcher Reihenfolge diese Stücke in den Retriever gelangt sind.

Es wäre ungenau zu sagen, dass Binärdateien oder Assets „nicht gelesen werden“. Der Kernpunkt ist, dass die ursprünglichen Bytes nicht in das LLM eingespeist werden, nicht dass die Datei im Projekt vollständig verschwindet. Wenn in Textstücken wie .tscn, .import oder README ein Asset‑Pfad auftaucht, kann man anhand dieses Stücks entscheiden.

Ein weiterer notwendiger Aspekt ist das Übertragungs‑Debugging. Es darf nicht passieren, dass die KI aus einer .gd‑Datei nur die Kernfunktionen auswählt und sendet. Das mit # <relative Pfad> ausgeklappte File muss im AST‑Parser in Funktionen/Code‑Stücke zerlegt werden, und man muss nachvollziehen können, welches Stück in welcher Reihenfolge an den Retriever übergeben wurde – etwa mittels Diff‑ oder sha256‑Verfahren.

Beim Durchsehen des PRs festgestellte Punkte

Beim Durchsehen des PR‑Reviews fiel auf, dass llm_judgment_request im Dokument an zwei Stellen unterschiedlich definiert war. Die eine Version konzentrierte sich auf chunk_text, chunk_kind, retrieved_evidence, während die andere zusätzlich chunk_code, surrounding_context und judgment_contract enthielt.

Wenn dieselbe Anforderungs‑Objekt im Dokument unterschiedlich definiert wird, führt das später bei der Implementierung zu Verwirrungen. Das Anforderungsschema muss einheitlich sein. Insbesondere zur Unterscheidung von AST‑Chunks und Direct‑Retrieval‑Chunks ist chunk_kind nötig, und zur Validierung der LLM‑Entscheidung müssen retrieved_evidence und judgment_contract ebenfalls klar definiert sein.

Im Qwen‑Review wurden auch Anmerkungen zu README‑Links, Tippfehlern im 25‑Tage‑Dokument und ähnlichen Hinweisen gemacht. Allerdings waren das 25‑Tage‑Dokument und der Workflow nicht Teil der von mir beabsichtigten Änderungen im PR‑Diff. Es gab ungewollte Änderungen, die die KI eingefügt hatte, und ich habe nach deren Entdeckung die Wiederherstellung gefordert.

Gemischte Bereiche im Problem

Heute habe ich im PR-Diff entdeckt, dass das Dokument vom 25. Tag und .github/workflows/qwen-code-pr-review.yml enthalten waren. Das war nicht die von mir angeforderte Änderung. Es sah so aus, als hätte die KI Dateien willkürlich geändert oder gelöscht, und im PR‑Bildschirm schienen die folgenden Dateien geändert oder gelöscht zu sein.

.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

Deshalb habe ich gefordert, die Änderungen rückgängig zu machen. Anschließend wurden die betreffenden Dateien auf den Stand von origin/main zurückgesetzt, und der PR‑Diff konzentrierte sich auf README.md und docs/roadmaps/2026-06-26-source-to-ast-input-flow.md.

Während dieses Prozesses wurde mir klar, dass man beim Übertragen von Dokumentationsaufgaben an die KI den Änderungsbereich von Anfang an streng festlegen muss. Auch das Schreiben von Rückblick‑ oder Roadmap‑Dokumenten sollte, wie bei Code‑Änderungen, im PR‑Umfang verwaltet werden.

Heute’s Fazit

Heute erneut bestätigtes Kernprinzip war: „Wie werden Dateien je nach Pfad nach welchen Kriterien ausgeschlossen, in welche Stücke zerlegt und in welcher Reihenfolge gelangen diese Stücke zum Retriever und zur LLM‑Entscheidung?“ Es geht weder darum, die gesamten Dateien auf einmal einzuspeisen, noch darum, willkürlich nur den Kerncode auszuwählen.

Der aktuelle Stand wird wie folgt festgelegt.

Dateien werden mit einer # <relativer Pfad>‑Überschrift ausgeklappt; diese Überschrift dient zur Nachverfolgung des Originalpfads und der Stücke.
Ausgeschlossene Dateien müssen in der Web‑UI oder im Log einsehbar sein.
.gd‑Dateien werden an den AST‑Parser gesendet, der Funktionen oder Code‑Stücke in Originalreihenfolge erzeugt.
Dateien, die wie .md ausgeschlossen werden sollen, bleiben in der Ausschlussliste und müssen in der Web‑UI oder im Log sichtbar sein.
Textbasierte Konfigurationsdateien, die nicht ausgeschlossen werden, werden ohne AST‑Durchlauf in Einheiten wie Zeilen, Absätze oder Konfigurationsblöcke zerlegt.
Jedes Stück trägt Nachverfolgungsinformationen wie Quellpfad und Chunk‑Reihenfolge und wird an den Retriever übergeben.
LLM‑Aufrufe erfolgen mehrfach im Format Prompt + aktuelles Stück + Retriever‑Suchergebnis.
Projektentscheidungen können erst getroffen werden, nachdem die Ergebnisse mehrerer Stücke von Anfang an akkumuliert wurden.

Die Datensammlung läuft weiterhin. Daher muss die zukünftige Dokumentation nicht nur ein „plausibles Architektur‑Konzept“ sein, sondern ein Kriterium, das zeigt, wie reale gesammelte Daten eingebracht und verifiziert werden.