Wie das Erklären von Code funktioniert
Die Karte des Erklärbaren, ein Thema eine Konversation, und Dokumente, die im Projekt bleiben.
Erklären ist die Antwort auf eine Frage, die niemand gut zu stellen weiß: „was ist das für ein Projekt und wie funktioniert es?“ Statt im Chat nachzufragen und die Antwort dann in einer dreihundertzeiligen Konversation zu suchen, bekommst du ein Verzeichnis von Themen und aus jedem ein Dokument, zu dem man zurückkehren kann.
Die Karte des Erklärbaren
Das Erste, was du im Reiter Projekt → Erklärungen siehst, ist die Aufforderung, die Karte zu erstellen. Die Karte ist eine Liste dessen, was in diesem Projekt eine Erklärung wert ist — Schichten, Module, der Datenfluss, einzelne Dateien. Erstellt wird sie vom Agenten, denn nur er weiß, was im Projekt ist.
Das Erstellen läuft im Hintergrund, und das Ergebnis ist keine Nachricht in einer Konversation, sondern eine Datei im Projekt. Du musst nicht dabei sein — die Karte erscheint in der App von selbst, sobald der Agent sie geschrieben hat.
In der Karte stehen die Themen in Gruppen. Die erste Gruppe ist die allgemeine: die Architektur, der Entwurf, der Datenfluss. Das sind Fragen, die man stellen kann, ohne eine einzige Datei zu kennen — deshalb stehen sie zuerst. Die konkreten Teile stehen darunter.
Das Projekt ändert sich, die Karte nicht. „Karte neu erstellen“ ist deshalb die Schaltfläche für den Fall, dass sich das Projekt weiterbewegt hat — nach einem größeren Refactoring verwirrt eine alte Karte mehr, als sie hilft.
Ein Thema, eine Konversation
Mit einem Tippen wählst du ein Thema oder mehrere und drückst dann Erklären. Die Antwort geht nicht in die Haupt-Konversation, sondern in eine eigene, benannt nach dem Thema.
Das ist Absicht, kein Detail. Wer Arbeit erledigt, will den Chat nicht mit einer Darstellung der Architektur geflutet haben; wer das Projekt lernt, will zum Thema zurückkehren und es nicht im Chat angeln. In dieser Konversation kannst du außerdem weiterfragen — und die Fragen bleiben beim Thema, zu dem sie gehören.
In Arbeit und fertig
Über der Karte gibt es zwei Abschnitte. Themen in Arbeit sind die, über die schon eine Konversation läuft. Fertige Erklärungen sind Dateien im Projekt, in docs/explanations/ — ein Thema, eine Datei.
Der Unterschied liegt darin, was überlebt. Eine Konversation gehört dem Server und verschwindet nach einem Projektwechsel oder einem Aufräumen. Eine Datei im Projekt bleibt, geht in git und wird auch von einem Kollegen gelesen, der coden nicht hat.
Was schon erklärt ist, wird in der Karte nicht ein zweites Mal angeboten. Würde es angeboten, wüsstest du nicht, ob du fortsetzt oder von vorn anfängst.
Wofür das gut ist
- Ein neues Projekt. Du erstellst die Karte, lässt dir die allgemeine Gruppe erklären und hast in zwanzig Minuten einen Überblick, den du sonst über zwei Tage zusammenträgst.
- Fremder Code. Genau die Datei, die du anfassen willst, lässt du dir erklären, bevor du in sie schreibst.
- Dokumentation, die als Nebenprodukt entsteht. Die Dateien in
docs/explanations/sind zum Lesen geschrieben, nicht für ein Modell — und sie bleiben im Projekt. - Lesen ohne Verbindung. Fertige Erklärungen liegen im Spiegel der Dokumente, öffnen sich also auch offline.
Ohne Verbindung
Eine Erklärung ohne Verbindung zum Server zu beauftragen geht nicht — auf der anderen Seite muss jemand arbeiten. Die schon gespeicherten liest man aber weiter, und die App sagt das gleich, statt die Schaltfläche einfach nicht zu reagieren zu lassen.
Woanders hängengeblieben als hier beschrieben? Schreib an support@coden-app.com.