Von der Anforderung zum Code – genau hier scheitert die Agenten-Einführung leise. Der Agent hat keinen schlechten Code geschrieben. Das Problem ist, dass sechs Wochen später niemand mehr zeigen kann, aus welcher Anforderung eine Änderung stammt, wer den Umfang freigegeben hat oder welche Belege die prüfende Person gesehen hat, bevor sie zugestimmt hat. Der Code war schnell da. Der Nachweis nicht.
Dieses Tutorial baut den Nachweis bewusst auf: eine durchgängige Kette von der schriftlichen Anforderung bis zum gemergten Pull Request, bei der sich jede Station öffnen lässt. GitHubs Spec Kit löst dieselbe Lücke mit Dateien im Repository. Dieser Leitfaden löst sie mit einem Arbeitssystem und nutzt dafür Sharkly, weil dort die gesamte Kette an einem Task hängt – das Muster lässt sich jedoch auf jedes Trackingsystem übertragen, das dieselben Verknüpfungen abbilden kann. Wenn du zuerst den operativen Ablauf kennenlernen willst, beginne mit unserem Leitfaden zum KI-Agenten-Projektmanagement.
TL;DR
Ein nachvollziehbarer Workflow von der Anforderung zum Code ist dadurch gekennzeichnet, dass jedes Artefakt auf das Artefakt verweist, das es hervorgebracht hat: Anforderung, Task, Sub-Tasks, Runs, Pull Request, Abnahme. In Sharkly wird aus der Anforderung ein Task, ein Agent schlägt im Plan mode den Breakdown vor und eine Person bestätigt ihn, jeder Sub-Task läuft in einem isolierten Worktree mit einem Execution Log, der Pull Request verlinkt sich über die Task-ID zurück, und eine Person nimmt das Ergebnis anhand der zu Beginn formulierten Abnahmekriterien ab. Agenten recherchieren, führen aus, testen und berichten. Menschen geben die Richtung vor, erteilen Befugnisse und nehmen das Ergebnis ab.
Was Nachvollziehbarkeit bedeuten muss
Nachvollziehbarkeit ist kein Bericht, den man am Ende erzeugt. Sie ist eine Eigenschaft der Kette: Jedes Glied existiert aufgrund des vorhergehenden, und man kann sie in beide Richtungen durchlaufen. Sechs Stationen genügen für ein Feature.
| Station | Wo sie liegt | Wodurch sie mit der vorherigen Station verknüpft ist |
|---|---|---|
| Anforderung | Task-Beschreibung, Typ Requirement oder User Story | Die Person, die sie geschrieben hat |
| Breakdown | Sub-Tasks unter dem übergeordneten Task | Bestätigter Vorschlag aus dem Plan mode |
| Ausführung | Task-Runs und Execution Log | Zuweisung plus ein für die Ausführung freigegebener Status |
| Belege | Agenten-Kommentar mit Prüfungen und Ergebnissen | Der Run, der sie hervorgebracht hat |
| Änderung | Pull Request | Task-ID in Branch, Titel oder Beschreibung |
| Abnahme | Statusänderung durch eine namentlich bekannte Person | Prüfung gegen die Abnahmekriterien |
Fehlt eine Station, ist die Kette reine Dekoration. Die häufigste Lücke ist die letzte: ein gemergter Pull Request, der als Abnahme gilt, obwohl niemand die Änderung mit der Anforderung verglichen hat.
Schritt 1: Die Anforderung als Task schreiben
Ein Task ist die Basiseinheit getrackter Arbeit in Sharkly, und ein für Softwareentwicklung eingerichteter Space startet mit den Task-Typen Requirement, Bug, Task und User Story. Für den übergeordneten Task verwendest du Requirement oder User Story. Der Typ entscheidet, welche benutzerdefinierten Felder und welche Workflow-Status gelten. So kann ein Requirement einen eigenen Review-Status führen, ohne den Bug-Workflow zu verwässern.
Die Beschreibung trägt die Hauptlast. Schreibe sie für jemanden, der die Konversation nie gesehen hat: warum die Arbeit wichtig ist, was zum Umfang gehört und was nicht, die relevanten Dateien oder das beobachtete Verhalten, die bereits getroffenen Entscheidungen und wie die Fertigstellung geprüft wird. Diese letzte Angabe sind die Abnahmekriterien – der Anker für Station sechs. Wenn du sie noch nicht schreiben kannst, ist die Anforderung nicht bereit, und genau dafür gibt es den Backlog: Ein einem Agenten zugewiesener Task startet nicht, solange er dort liegt.
Binde die Repositories auf Space-Ebene ein, damit jeder Sub-Task sie erbt. Ein Agent ohne Repository-Bindings greift auf die Git-Repositories des Space zurück – genau das willst du bei einem Feature mit mehreren Tasks.
Schritt 2: Den Agenten den Breakdown entwerfen lassen und ihn dann bestätigen
Öffne den Agenten-Chat des Tasks und schalte die Sitzung in den Plan mode. Im Plan mode kann der Agent Aktionen zur Prüfung vorschlagen, und Sharkly erstellt die geplanten Tasks und Sub-Tasks erst, nachdem du den Vorschlag bestätigt hast. Du kannst bestätigen, ohne zu starten, oder bestätigen und die Arbeit starten.
Diese Station lassen die meisten Teams aus – und genau sie macht den Breakdown nachvollziehbar statt improvisiert. Der Vorschlag ist sichtbar, bevor daraus Arbeit wird: Entferne den Sub-Task, der den Umfang ausweitet, ergänze den Migrationsschritt, den der Agent übersehen hat. Sub-Tasks bleiben im selben Space wie ihr übergeordneter Task, und Sharkly lehnt Selbst-Verknüpfung und Zyklen ab, sodass die Hierarchie ein Baum bleibt.
Nutze einen einzelnen Agenten für eine Anforderung, die eine einzige Rolle abdecken kann. Nutze eine Crew, wenn der Leader das Ziel interpretieren, weitere Agenten-Mitglieder wie einen Test-Autor einbeziehen und deren Ergebnisse in einem Task zusammenführen muss. Bei einer Änderung an drei Dateien bringt die Crew zusätzliche bewegliche Teile, aber keine zusätzliche Nachvollziehbarkeit. Unser Leitfaden zu Sharkly Crews behandelt das Leader-first-Modell.
Übertrage alles, was im Chat entschieden wurde, in die Task-Beschreibung. Der Chat an einem Task ist kein Kommentar und erscheint nicht in der Activity. Eine Entscheidung, die nur dort existiert, ist für die Kette unsichtbar.
Schritt 3: In Isolation ausführen – mit Nachweis
Weise jeden Sub-Task über das Assignee-Element einem Agenten zu und verschiebe ihn anschließend aus dem Backlog heraus. Sharkly prüft die Statuskategorie und die Ausführungsbereitschaft, reiht den Run in die Warteschlange ein und schickt ihn an den ausgewählten Computer, wo der lokale Dienst ein isoliertes Task-Verzeichnis vorbereitet und die Runtime startet.
Zwei Details halten diese Station ehrlich. Der Run enthält Task-Titel und -Beschreibung, die letzten Kommentare sowie den Workflow des Task-Typs mit seinen zulässigen Status. So arbeitet der Agent von der Anforderung aus und nicht von einer Paraphrase. Und jeder Repository-gestützte Run bekommt im Temporary mode seinen eigenen Worktree, sodass parallele Sub-Tasks sich nicht gegenseitig überschreiben können. Unser Beitrag zum parallelen Ausführen von Agenten ohne Merge-Konflikte erklärt, warum Isolation das Fan-out erst sicher macht.
Fortschritt, Trace-Events und das Ergebnis fließen zurück in den Task. Das Execution Log hält fest, warum der Run in die Warteschlange kam, wann er begonnen und geendet hat, Tool-Aufrufe und Runtime-Events, die Auslösequelle und Fehlerdetails. Dieses Log ist Station vier.
Schritt 4: Den Pull Request über die ID verknüpfen
Verbinde die GitHub-Organisation einmal und setze dann die Task-ID in den Titel des Pull Requests, in die Beschreibung oder in den Namen des Quell-Branches. Ein einfaches SH-312 und Fixes SH-312 erzeugen beide die Verknüpfung. Linkbacks hinterlassen die Task-URL als Kommentar am Pull Request – bei privaten Repositories standardmäßig aktiviert.
Nun die Grenze, denn sie ist für die Nachvollziehbarkeit entscheidend: Wörter wie fixes und closes haben keine zusätzliche Bedeutung, und das Mergen eines Pull Requests ändert den Task-Status nicht. Sharkly verknüpft die Änderung mit dem Task; es entscheidet nicht, dass der Task erledigt ist. Der Status bleibt eine menschliche Entscheidung – genau darum geht es bei Station sechs. Unsere Anleitung zum Zuweisen eines Jira-Tickets an einen KI-Agenten mit PR als Ergebnis zeigt dieselbe Verknüpfung aus Sicht des Trackers.
Schritt 5: Gegen die Anforderung prüfen und dann abnehmen
Ein Agent kann einen Task im Status „Warten auf menschliche Prüfung" hinterlassen, und dieses Signal landet in der Inbox der verantwortlichen Person unter Primary. Lies drei Dinge in dieser Reihenfolge: die Abnahmekriterien aus Schritt eins, den Kommentar des Agenten mit den durchgeführten Prüfungen und den verbleibenden Unsicherheiten sowie das Execution Log. Erst danach den Diff.
Wenn ein separater Test-Task die Änderung verifiziert, halte diese Beziehung explizit fest. Organization Owners und Admins können benutzerdefinierte Link-Typen anlegen, und das Beispiel aus der Dokumentation selbst – validates / is validated by – ist die Nachvollziehbarkeitskante für diese Station. Beziehungen ändern den Status nicht von selbst, die Abnahme muss also weiterhin eine Statusänderung durch eine Person sein.
Eine Kategorie-Regel schützt dich hier: Einen Task nach Completed zu verschieben markiert ihn als abgeschlossen, bricht aber keinen bereits aktiven Run ab. Wenn der Agent noch arbeitet, brich zuerst ab und entscheide dann.
Wo die Kette bricht
Der obige Workflow hat drei bekannte Bruchstellen, und die sollte man klar benennen.
Schlussfolgerungen, die im Chat bleiben. Eigenständige Agent-Chat-Sitzungen gehören der Person, die sie erstellt hat. Wenn das Design dort geklärt wurde, weiß der Task nichts davon.
Runs, die außerhalb eines Tasks gestartet wurden. Die Aktion Run Agent eines Automatisierungs-Workflows erstellt keinen Task; der Run wird am Agenten erfasst. Für einen nächtlichen Check in Ordnung, für Feature-Arbeit falsch.
Dateien statt eines Nachweises. Spec Kits spec.md, plan.md und tasks.md sind eine starke Kette für einen Entwickler, der in einem einzigen Repository arbeitet. Nutze sie, wenn das Team nur aus dir besteht. Nutze ein gemeinsames Arbeitssystem, wenn eine zweite Person prüfen, abnehmen oder nachfragen muss, was passiert ist, ohne deinen Checkout zu öffnen. Sharkly ist kein Ersatz für Claude Code, Codex oder andere Ausführungstools; es ist die Ebene, die die Kette rund um sie sichtbar hält. Die Dokumentation behandelt jedes Konzept ausführlicher unter docs.sharkly.ai.
FAQ
Bedeutet „von der Anforderung zum Code", dass der Agent die Anforderung schreibt? Nein. Eine Person schreibt die Anforderung und ihre Abnahmekriterien. Ein Agent kann die Codebasis recherchieren und im Plan mode einen Breakdown vorschlagen, aber aus dem Vorschlag werden erst Tasks, wenn eine Person ihn bestätigt.
Kann ich die Anforderung in Jira behalten und trotzdem den Nachweis bekommen? Ja. Jira-Import und -Synchronisierung erhalten den Tracker, den deine Organisation liest, während Sharkly den Ausführungsnachweis führt. Unsere Jira-Alternativen für Mensch-Agenten-Teams behandeln den Fall, dass der Tracker selbst ersetzt werden soll.
Was passiert, wenn der Pull Request vor der Prüfung gemergt wird? Der Task-Status ändert sich nicht, die Kette zeigt also einen nicht abgenommenen Task mit einer gemergten Änderung. Das ist das richtige Signal: Eine Person schuldet noch eine Entscheidung.
Wie klein sollte das erste nachvollziehbare Feature sein? Eine Anforderung, zwei oder drei Sub-Tasks, ein Agent. Unsere Anleitung zum Claude-Code-Projektmanagement durchläuft den Zyklus an einem einzigen Task von Anfang bis Ende.
