Communitygithub.com

Hand-Test

Führt einen manuellen Test für sichtbare, hörbare oder fühlbare Änderungen durch: Vorher/Nachher-Video und -Tafel nebeneinander, vom Agenten geprüft und zur Freigabe durch eine Person vorgelegt.

Was ist Hand-Test?

Diese Fertigkeit ermöglicht es einem KI-Agenten, eine Änderung, die ein Mensch sehen, hören oder fühlen kann, systematisch zu testen, indem sie einen Vorher/Nachher-Vergleich in Form eines Videos und einer Tafel erstellt und die Freigabe durch eine Person einholt, bevor die Änderung zusammengeführt wird. Sie ist für die Arbeit mit Claude Code und ähnlichen agentenbasierten Entwicklungswerkzeugen konzipiert, die über ein Terminal ausgeführt werden, und stützt sich auf ein Repository-Projekt, das seine Konventionen in `docs/agents/hand-test.md` definiert. Der Agent klassifiziert die Änderung, plant einen reproduzierbaren Ablauf (über echte UI-Interaktion, nicht Koordinaten), nimmt Rohaufnahmen des Vorher- und Nachher-Zustands auf und verarbeitet sie mit einem speziellen Skript `scripts/handtest.py` (erfordert ffmpeg/ffprobe, kann via uv oder eigenem venv laufen). Daraus werden ein synchronisiertes Dualvideo und eine Bildtafel erstellt. Der Agent prüft die Belege selbst, legt sie dann einer genehmigenden Person vor und dokumentiert den endgültigen Bescheid. Die Fertigkeit erzeugt strukturierte Ausgaben (Verzeichnisse mit README, PACKAGE, REPORT) und stellt sicher, dass die Änderung bis zur Freigabe unmerge bleibt. Sie eignet sich für visuelle/auditive/taktile PR-Überprüfungen, Release-Reports und jede Situation, in der eine Änderung dem Benutzer nachweisen muss, dass sie das beabsichtigte Erlebnis bewirkt.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GhostRoboticsLab/skills/tree/HEAD/skills/engineering/hand-test

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Was macht Hand-Test?

Tests beweisen, was der Code tut. Ein Hand-Test beweist, dass ein Mensch das bekommt, was beabsichtigt war. Für jede Änderung, die ein Mensch sehen, hören oder fühlen kann, erstellst du einen Beleg, den ein Fremder in einer Minute kalt beurteilen kann: ein Video und eine Tafel, VORHER (rotes Abzeichen) neben NACHHER (grünes Abzeichen), am selben Ort und mit derselben Aktion, sodass sich nur die eine Änderung unterscheidet. Die Änderung bleibt ungemergt, bis der Genehmiger OK sagt.

Projektdaten stehen in docs/agents/hand-test.md im Repository des Benutzers: wie man VORHER bekommt, wie man diese Oberfläche bedient und aufnimmt, die Geräteregeln, wohin die Belege gehen, wer genehmigt und was OK und Nicht OK bewirken. Fehlt diese Datei, befolge zuerst SETUP.md.

Das Werkzeug ist scripts/handtest.py. Führe es aus mit uv run <Ordner dieser Fertigkeit>/scripts/handtest.py <Befehl>; --help zu jedem Befehl listet seine Flags. Es benötigt ffmpeg und ffprobe im PATH; uv bringt Pillow mit. Ohne uv erstelle eine virtuelle Umgebung außerhalb des Repositorys (python3 -m venv <verz> && <verz>/bin/pip install pillow) und führe das Werkzeug mit <verz>/bin/python aus.

1. Klassifiziere die Änderung

Füge einen ## Hand-Test-Abschnitt in den PR-Body ein (oder dorthin, wo die Änderung beschrieben wird):

  • ja: <worauf zu achten ist> für alles, was ein Mensch sieht, hört oder fühlt: UI, Verhalten, Timing, Sound, Text, Design.
  • nein: <warum nichts gesehen, gehört oder gefühlt wird> für Tooling, Build, Tests, Dokumentation oder ein Refactoring mit derselben Ausgabe.

Im Zweifel ist es ja.

Erledigt wenn: der Abschnitt vorhanden ist. Ein nein beendet die Fertigkeit.

2. Plane die Aufnahme

Benenne den Moment: den einen Schritt, an dem die Änderung sichtbar wird. Wenn die Änderung ab dem ersten Bild auf dem Bildschirm ist (eine Farbe, ein Label, ein Layout), ist der Moment das Eintreffen des Bildschirms oder der erste Schritt danach.

Schreibe die Schritte als Skript, das die echte App bedient, identisch für beide Seiten (Befehle pro Oberfläche in CAPTURE.md):

  • Echte Eingabe über die eigene UI der App: eine Testtastenkombination überspringt den Code, den ein Mensch trifft.
  • Finde Elemente über ihr Label oder ihre Rolle, niemals über Koordinaten: Die Verschiebung des Layouts ist oft die Änderung selbst.
  • Warte auf einen echten Zustand (ein angezeigtes Label, eine abgeschlossene Anfrage) vor dem Moment, niemals auf einen festen Timer. Halte eine feste Zeit danach.
  • Gleiches Gerät, Fenstergröße, Sprache, Daten und Startzustand auf beiden Seiten.
  • Setze alles in einem finally zurück.

VORHER kommt vom echten alten Zustand: dem Build des Basis-Commits oder der zur Laufzeit ausgeschalteten Änderung. Keine gespeicherten Dateiänderungen dafür.

Wenn die Änderung eine Frage von Raum, Zeit oder Gefühl ist, die niemand vor dem Build geklärt hat (wie groß, wie schnell, wie es sich anfühlen soll), stoppe und teile es dem Benutzer mit. Das gehört in einen interaktiven Entwurf vor dem Build; ein Hand-Test prüft eine Entscheidung, er trifft keine.

Erledigt wenn: das Skript trocken (nichts aufgenommen) auf VORHER und auf NACHHER läuft, jedes Element findet (oder jeden Zustand erreicht, wo nur Standbilder möglich sind) und das Gerät sowie den Arbeitsbaum so hinterlässt, wie sie waren, mit identischer Prüfsumme des Baums vorher und nachher.

3. Nimm beide Seiten auf

Nimm VORHER auf, dann NACHHER, mit demselben Skript. Halte dich an die Geräteregeln des Projekts: berühre nur die zu testende App, deinstalliere nichts, ändere keine Systemeinstellung und sende Eingaben nur, während die zu testende App im Vordergrund ist.

Erledigt wenn: zwei Rohaufnahmen existieren, jede zeigt den Moment und die Prüfsumme des Arbeitsbaums stimmt noch.

4. Erstelle den Beleg

  1. init --out "$HANDTEST_ROOT/<gruppe>" --id <N> --topic <kebab-case> --title "<Klartext>" --base <sha> --head <sha> --ok "<...>" --not-ok "<...>". Die Gruppe, OK und Nicht OK stammen aus der Projektdatei. Deine Shell behält HANDTEST_ROOT möglicherweise nicht zwischen Befehlen: setze es im selben Befehl.
  2. find-change <raw> --from <s> --to <s> auf jeder Aufnahme um den Moment herum. Die Synchronzeit ist der Frame, in dem sich das Bild ändert, nicht die protokollierte Zeit eines Schritts.
  3. pair --before <raw> --after <raw> --sync-before <s> --sync-after <s> --title ... --what ... --caption ... --out <ordner>/<id>_<topic>.mp4. Es trägt die Zeiten des Videos in README.md und PACKAGE.md ein und gibt aus, wo der Moment im Video liegt.
  4. Ein Standbild pro Seite, einen Schlag nach dem Moment, aus den Rohaufnahmen: stills <raw> --at <s> --out <scratch>/before, dasselbe für NACHHER. Es gibt jede Datei aus. Dann board --before <png> --after <png> --title ... --caption ... --out <ordner>/<id>_<topic>_VORHER_NACHHER.png.
  5. Fülle jede <füllen Sie ein: ...>-Markierung. Die Regeln für die Wörter und Zahlen stehen in EVIDENCE.md.

Erledigt wenn: check <ordner> „bereit für eine Person“ ausgibt.

5. Prüferdurchlauf

Bevor eine Person es sieht, überprüfe es selbst wie ein Fremder. Ziehe Standbilder aus dem Video zweimal: stills <video> --every 1 --out <scratch>, dann stills <video> --at <t-0.5> <t> <t+0.5> --out <scratch>, wobei t die Zeit des Moments im Video ist, nicht in einer Rohaufnahme (pair hat sie ausgegeben; handtest.json enthält sie als video.change_at). Sieh dir jedes Standbild und die Tafel an.

  • Jedes muss zeigen, worauf die Bildunterschrift hinweist. Verdeckt, leer, falscher Zustand, falsche Sprache, ein Overlay über der Änderung: archive den Ordner und nimm ab Schritt 3 erneut auf. Nimm lieber neu auf, als ein schlechtes Bild in der README wegzuerklären.
  • Eine Zahl muss mit dem Bild übereinstimmen. Bei Unstimmigkeit ist die Zahl falsch: finde heraus, warum.
  • Ein grüner Test mit einem falschen Bild ist ein Befund. Melde es dem Benutzer als Fehler.

Erledigt wenn: jedes Standbild und die Tafel zeigen, was die Bildunterschriften behaupten, und jede Zahl in der README mit dem Bild übereinstimmt.

6. Übergabe

Lege den Ordner dort ab, wo die Belege des Projekts hingehen. Veröffentliche PACKAGE.md dort, wo die Projektdatei es angibt, und nenne nur den relativen Pfad des Ordners, niemals einen Account oder einen absoluten Pfad. Vervollständige die ja-Zeile des PRs mit diesem Pfad und wem es zur Prüfung vorliegt (das Formular steht unter „Der PR-Abschnitt“ in EVIDENCE.md). Frage den Genehmiger. Die Änderung bleibt ungemergt (ein Entwurf-PR, wo es PRs gibt), solange der Hand-Test offen ist.

Erledigt wenn: das Paket veröffentlicht ist, die PR-Zeile den Ordner nennt, der Genehmiger gefragt wurde und nichts von der Änderung gemergt wurde.

7. Protokolliere das Urteil

Das Urteil ist das des Genehmigers. Protokolliere niemals ein OK, das sie nicht gegeben haben.

  • OK: verdict <ordner> --ok --by "<wer>" (es lehnt einen Ordner ab, der check nicht besteht), dann tue, was die Projektdatei für OK vorsieht (normalerweise: den PR bereit machen).
  • Nicht OK: verdict <ordner> --not-ok --by "<wer>" --note "<was sie gesagt haben>". Behebe es auf demselben Branch, archive den Ordner und gehe zurück zu Schritt 3. Die Wiederholung erzeugt dieselben Dateinamen erneut; die alte Aufnahme wandert nach previous/. Wenn init die frische README.md geschrieben hat, kopiere die Zeilen, die noch gelten, aus previous/<stempel>_README.md; pair überschreibt die Zeiten.

Erledigt wenn: handtest.json das Urteil der Person enthält und der Tracker damit übereinstimmt.

Ein Release

Behalte jeden Hand-Test-Ordner unter einem Gruppenordner pro Release, führe dann report <gruppe> --title "<release>" aus. Es schreibt REPORT.md und eine eigenständige index.html, ausstehende Hand-Tests zuerst. Siehe EVIDENCE.md.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Verwandte Skills