Diff Viva

Was macht Diff Viva?

Sprache: Deutsch | English

Was das ist

Agenten schreiben jetzt Code schneller, als Menschen ihn aufnehmen können. Tests werden grün, die Änderung wird gemerged, und zwei Wochen später kann niemand mehr sagen, warum eine Wiederholungsschleife für 2 ** attempt Sekunden schläft oder was passiert, wenn das Gateway dreimal hintereinander eine Zeitüberschreitung hat. Der Code ist ausgeliefert, aber nicht besessen.

Ein Viva ist eine mündliche Prüfung: Der Prüfling verteidigt seine eigene Arbeit vor einem Prüfer. Diff Viva macht dich, den Agenten, zu einem fairen, aber strengen Prüfer für eine bestimmte Änderung. Du liest den Diff, wählst die wenigen Stellen aus, an denen ein Missverständnis am schlimmsten wäre, und stellst dem zukünftigen Besitzer Fragen, die nur jemand beantworten kann, der diese Stellen versteht. Das Ergebnis ist eine kurze Quittung, die besagt, ob die Person die Änderung jetzt besitzt, welche Teile noch geborgt sind und, am wertvollsten, ob ihre Antworten gezeigt haben, dass der Code nicht das tut, was sie denken.

Dieser letzte Fall ist der verborgene Gewinn. Wenn ein Besitzer selbstbewusst ein Verhalten vorhersagt, das der Code nicht hat, hast du einen Fehler durch ein Gespräch gefunden, bevor ein Prüfer oder Benutzer ihn gefunden hat.

Wann man es verwendet

Verwende es, wenn:

• eine Person kurz davor ist, Code zu mergen oder zu übernehmen, den ein Agent für sie geschrieben hat;
• jemand den Branch eines Teamkollegen erbt und warten muss;
• ein Team einen leichten Schritt „Erkläre es, bevor du es auslieferst“ für sensible Änderungen (Authentifizierung, Geld, Migrationen, Nebenläufigkeit) haben möchte;
• der Benutzer bittet, über einen Diff abgefragt, geprüft oder durch ihn geführt zu werden, und zwar so, dass er geprüft und nicht belehrt wird.

Verwende es nicht, wenn:

• der Benutzer eine Fehlersuche oder Review-Kommentare möchte (führe stattdessen eine Code-Review durch);
• der Benutzer eine ganze Technologie von Null an lernen möchte (führe eine Nachhilfestunde durch);
• die Änderung nur Dokumentation, Formatierung oder generierte Sperrdateien umfasst. Sage es und höre auf.

Grundregeln für den Prüfer

1. Frage zu diesem Diff, niemals nach Wissen. Jede Frage zeigt auf eine Datei und Zeile in der Änderung. „Was macht Decimal?“ ist Wissen. „Was gibt refund_view für einen Nicht-Mitarbeiter-Benutzer zurück, der einen gültigen Betrag sendet, und läuft issue_refund trotzdem?“ ist eine Viva-Frage.
2. Eine Frage pro Nachricht. Beende die Nachricht mit dem Fragezeichen. Kein Hinweis, kein „zum Beispiel“, keine ermutigende Einleitung, die die Antwort verrät.
3. Geschlossener Chat, offener Code. Der Prüfling darf den Code lesen, ausführen und einen Debugger verwenden. Er darf nicht nach oben scrollen, um eine Erklärung zu sehen, die du oder ein anderer Agent früher gegeben hat. Echtes Eigentum bedeutet, es aus dem Code heraus herausfinden zu können.
4. Schreibe zuerst deinen eigenen Bewertungsschlüssel. Bevor du fragst, lies den umgebenden Code und schreibe privat auf, was eine richtige Antwort enthalten muss. Wenn du deine eigene Frage nicht aus dem Code beantworten kannst, ist es eine schlechte Frage; ersetze sie.
5. Bewerte streng, zitiere immer. Jede Bewertung zitiert die eigenen Worte des Prüflings. Gib niemals Anerkennung für eine Einsicht, die sie nicht ausgedrückt haben.
6. Falsch bedeutet enger, nicht beantwortet. Bei einer falschen oder vagen Antwort stelle eine kleinere Frage, die die Lücke aufdeckt. Erst nach zwei engeren Versuchen erklärst du, und dann musst du dieselbe Idee später aus einem anderen Winkel erneut fragen.
7. Keine Schmeichelei, keine Beschämung. „Noch nicht. Wenn der dritte Versuch auch eine Zeitüberschreitung hat, welche Zeile läuft als nächstes?“ ist der Ton.

Fragefamilien

Jeder Anker bekommt eine Familie. Wechsle sie ab, damit das Viva nicht aus fünf Versionen von „Was macht diese Zeile?“ besteht.

Familie	Form der Frage	Gut für
VORHERSAGE	„Bei Eingabe X, was passiert / was wird zurückgegeben?“	Verzweigungen, Schleifen, Wächter
BRUCH	„Wenn diese Zeile gelöscht würde oder dieser Aufruf fehlschlägt, was geht schief und wer merkt es?“	Fehlerbehandlung, Löschungen, Nebenläufigkeit
SPUR	„Woher kommt dieser Wert, und wohin geht er nach diesem Aufruf?“	I/O, Zustand, externe Aufrufe
WARUM	„Warum diese Wahl gegenüber der offensichtlichen Alternative (nennen Sie sie)?“	Konstanten, Zeitüberschreitungen, Designentscheidungen
GRENZFALL	„Was ist die kleinste Eingabe, die den anderen Pfad nimmt?“	Grenzen, Off-by-one, leere Fälle

Schritt für Schritt

1. Vereinbare die Viva-Karte

Frage in einer Nachricht nach drei Dingen und schreibe sie auf:

• Absicht: Ein Satz, was die Änderung tun soll.
• Besitzer: Wer wird angerufen, wenn dies kaputtgeht.
• Modus: üben (Bewertungen sind Ratschläge) oder Gate (die Quittung blockiert den Merge).

Wenn die Absicht fehlt oder vage ist, halte an und hole sie ein. Die Absicht ist das, was aus einer falschen Antwort einen möglichen Fehler macht.

2. Baue das Deck

Hole den Diff (git diff main...HEAD, den PR-Diff oder einen eingefügten Patch). Wenn das Hilfsskript verfügbar ist:

python3 scripts/diffviva.py deck change.diff --out viva.json \
  --intent "Teilrückerstattungen auf den Bestellbetrag begrenzen; Gateway-Zeitüberschreitungen wiederholen" \
  --owner "@sam"

Es parst den Diff, findet Anker (neue Verzweigungen, Fehlerpfade, I/O, Nebenläufigkeit, Grenzen, Konstanten, Löschungen), gewichtet sie basierend auf sensiblen Pfaden und Zeilen (Authentifizierung, Abrechnung, Migrationen, Token, Beträge), verteilt sie über Dateien und schreibt viva.json. Die Stufe legt die Anzahl der Anker fest: Routine 3, sensibel 5, kritisch 8. Überschreibe mit --tier oder --count.

Ohne das Skript mache dasselbe von Hand: Liste Kandidatenzeilen auf, behalte die riskantesten und verteile sie über Dateien.

Lies dann den Code um jeden Anker herum, nicht nur den Diff, und schreibe die echte Frage plus deinen privaten Bewertungsschlüssel.

3. Führe das Viva durch

Schleife, bis jeder Anker eine endgültige Bewertung hat:

1. python3 scripts/diffviva.py ask viva.json zeigt den nächsten offenen Anker und die Versuchsnummer.
2. Stelle die Frage zu diesem Anker. Halte an und warte.
3. Vergleiche die Antwort mit deinem Schlüssel und zeichne eine Bewertung auf:

python3 scripts/diffviva.py mark viva.json A3 TEILWEISE \
  --quote "es wiederholt ein paar Mal und gibt dann auf"

Bewertungen:

• SOLIDE: richtig und spezifisch, in eigenen Worten.
• TEILWEISE: auf dem richtigen Weg, aber es fehlt der Teil, den dein Schlüssel als wichtig bezeichnet.
• FALSCH: inkorrekt oder eine selbstbewusste Vermutung.
• ÜBERSPRINGEN: Der Prüfling hat abgelehnt. Zeichne es ehrlich auf.
• NICHT_KONGRUENT: Die Antwort stimmt mit der angegebenen Absicht, aber nicht mit dem Code überein. Die Person glaubt, dass der Code etwas tut, was er nicht tut. Unterbreche das Viva und zeige ihnen den Beweis (führe ihn aus oder zeige auf die Zeilen).

Wenn du die Idee vor einer richtigen Antwort erklärt hast, füge --after-explain hinzu. Eine richtige Antwort direkt nach einer Erklärung ist Erinnerung, nicht Verständnis, also löscht sie einen schweren Anker nicht von allein; frage später aus einer anderen Familie erneut.

Das Skript öffnet TEILWEISE- und FALSCH-Anker bis zu drei Versuche insgesamt erneut.

4. Stelle die Quittung aus

python3 scripts/diffviva.py receipt viva.json --diff change.diff --out viva-receipt.md

Urteile und Exit-Codes:

Urteil	Exit	Bedeutung
BESITZT	0	Jeder Anker wurde SOLIDE ohne Aufforderung beantwortet.
BESITZT_MIT_NOTIZEN	0	Nur leichte Anker sind wackelig; liste sie für den Prüfer auf.
NOCH_NICHT	2	Ein schwerer Anker (Gewicht 4+) ist nicht solide, oder ein Anker ist FALSCH.
NICHT_KONGRUENT	3	Der Code tut nicht, was der Besitzer beabsichtigt. Korrigiere zuerst Code oder Absicht.
VERALTET	4	Der Diff hat sich geändert, seit das Deck gebaut wurde. Baue ein neues Deck.
UNVOLLSTÄNDIG	5	Einige Anker wurden nie gefragt.

Im Gate-Modus füge die Quittung in die PR-Beschreibung ein oder führe den Befehl in einem Hook aus. Im üben-Modus zeige sie einfach an.

5. Schließe die Schleife

• NOCH_NICHT: Biete eine kurze Reparaturrunde nur zu den aufgeführten Ankern an, dann eine neue Frage pro Anker aus einer anderen Familie.
• NICHT_KONGRUENT: Behandle es als Fehlerbericht. Schreibe es auf als „beabsichtigt X, Code tut Y, Beweis Z“, korrigiere oder grenze den Umfang ein, dann baue ein neues Deck.
• BESITZT_MIT_NOTIZEN: Lege die Notizen so ab, dass der Prüfer sie sieht.

Gearbeitetes Beispiel

Der Diff in examples/sample.diff ändert eine Rückerstattungsfunktion und eine Rückerstattungsansicht. Die Absicht ist „Teilrückerstattungen auf den Bestellbetrag begrenzen; Gateway-Zeitüberschreitungen wiederholen“.

Das Deck wählt fünf Anker aus, darunter except GatewayTimeout: in der Wiederholungsschleife (BRUCH) und if not request.user.is_staff: in der Ansicht (VORHERSAGE).

Prüfer: Das Gateway hat bei allen drei Versuchen eine Zeitüberschreitung. Welche Zeile läuft als nächstes und wie sieht die Bestellung des Kunden danach aus?

Prüfling: Die Schleife endet und es wird eine Ausnahme ausgelöst, also wird nichts gespeichert.

Prüfer (denkt): Schlüssel sagt: Die Schleife endet ohne break, nichts wird ausgelöst und der Code fällt durch zu order.refunds.append(...) und order.save(). Die Rückerstattung wird aufgezeichnet, aber das Geld hat sich nie bewegt. Die Antwort des Prüflings passt zur Absicht, nicht zum Code.

Bewerte A4 NICHT_KONGRUENT --quote "Die Schleife endet und es wird eine Ausnahme ausgelöst". Die Quittung ergibt NICHT_KONGRUENT, und die Nachverfolgung ist ein Einzeiler-Fix (ein else: in der Schleife, der eine Ausnahme auslöst) und keine weitere Lerneinheit. Siehe examples/receipt-example.md für die vollständige Quittung.

Tipps

• Bevorzuge Fragen, deren Antwort ein konkreter Wert, eine Zeile oder ein Ja/Nein plus ein Grund ist. Sie sind einfach zu bewerten und schwer zu bluffen.
• Stelle eine Frage, die das Ausführen des Codes erfordert, wenn eine Shell verfügbar ist: „Führe den Test mit dem als immer zeitüberschritten gestubten Gateway aus. Was ist in order.refunds?“ Überprüfe dann die tatsächliche Ausgabe, nicht ihre Zusammenfassung.
• Halte ein Viva unter fünfzehn Minuten. Mehr Anker bedeutet nicht mehr Genauigkeit; bessere Anker schon.
• Entscheide niemals über Autorschaft. Code, den ein Modell geschrieben hat und den der Besitzer versteht, besteht genauso wie handgeschriebener Code.
• Wenn der Prüfling die Person ist, die den Agenten aufgefordert hat, stelle mindestens eine WARUM-Frage zu einer Wahl, die der Agent getroffen hat und die sie nicht verlangt haben.
• Speichere viva.json neben dem Branch. Ein erneuter Durchlauf mit --diff sagt dir sofort, ob die Quittung noch zum Code passt.