Teil 14. Eigener Prozess durch Qwen Code Skills

Wenn Sie eine Anfrage zur Feature-Spezifikation mehrmals wiederholt haben, ist es an der Zeit, sie zu automatisieren. In Qwen Code eignen sich dafür Agent-Skills. Ein Skill ist ein Verzeichnis mit SKILL.md, in dem beschrieben ist, wann und wie der Agent einen bestimmten Prozess anwenden soll. Ein Skill kann persönlich oder projektspezifisch sein.

Persönlicher Skill:

~/.qwen/skills/feature-spec/SKILL.md

Projektspezifischer Skill:

.qwen/skills/feature-spec/SKILL.md

Für ein Team ist der projektspezifische Skill besser: Er landet in Git und wird Teil des Engineering-Prozesses.

Wenn Ihr Projekt parallel von mehreren verschiedenen Agenten genutzt wird, können Sie die Skills um eine Datei AGENTS.md im Repository-Root ergänzen – das ist ein interagentiver Standard für Regeln, den nicht nur Qwen Code, sondern auch andere kompatible Tools lesen. Mehr zur Rolle von AGENTS.md neben QWEN.md – in Teil 15.

Erstellen eines Skills

mkdir -p .qwen/skills/feature-spec

SKILL.md:

---
name: feature-spec

description: Erstellt eine neue SDD-Feature-Spezifikation aus der nächsten unvollendeten Phase der Roadmap. Vor Beginn des nächsten Features, dem Schreiben einer Spezifikation oder der Vorbereitung einer neuen Phase vor der Implementierung verwenden.
---

# Feature-Spezifikation

## Prozess

1. specs/roadmap.md lesen.
2. Die erste unvollendete Phase finden.
3. Einen Branch mit dem Namen phase-N-kebab-name erstellen.
4. Vor dem Schreiben von Dateien dem Menschen genau drei Gruppen von Fragen stellen:
   - Grenzen;
   - Entscheidungen;
   - Kontext.
5. specs/mission.md und specs/tech-stack.md lesen.
6. specs/YYYY-MM-DD-feature-name/ erstellen.
7. Schreiben:
   - requirements.md
   - plan.md
   - validation.md
8. Keinen Code implementieren.

## Datei requirements.md

Grenzen, was außerhalb der Grenzen bleibt, Entscheidungen, Kontext und offene Fragen einschließen.

## Datei plan.md

Nummerierte Aufgabengruppen verwenden. Jede Gruppe muss separat überprüfbar sein.

## Datei validation.md

Automatische Prüfungen, manueller Durchlauf, Abweichungsprüfung und Fertigstellungskriterien einschließen.

## Einschränkungen

- specs/tech-stack.md einhalten.
- Keine Abhängigkeiten ohne ausdrückliche Genehmigung hinzufügen.
- Die Phase eigenständig lieferbar lassen.
- Keine unzusammenhängenden Dateien bearbeiten.

Skill überprüfen

Qwen Code starten:

qwen

Die Liste ansehen:

/skills

Explizit anfordern:

Nutze den Skill feature-spec, um das nächste Feature aus der Roadmap zu starten.
Implementiere keinen Code.

Wenn der Skill nicht funktioniert, prüfen Sie:

• die Datei liegt in .qwen/skills/feature-spec/SKILL.md;
• YAML-Kopf beginnt und endet mit ---;
• name ohne Leerzeichen;
• description sagt konkret, wann der Skill anzuwenden ist;
• Qwen Code wurde nach der Skill-Erstellung neu gestartet.

Skill gegen Slash-Befehl

Ein Skill wird vom Modell oder über /skills aufgerufen; er beschreibt eine Fähigkeit. Ein Slash-Befehl wird vom Benutzer explizit aufgerufen. Für die Feature-Spezifikation in SDD ist der Skill bequemer: Der Agent kann selbst erkennen, dass er benötigt wird, wenn der Benutzer schreibt „starte das nächste Feature".

Wenn Ihr Team eine starre Schnittstelle braucht, können Sie zusätzlich einen benutzerdefinierten Befehl erstellen, aber für den Anfang reicht der Skill.

Hilfsdateien

Wenn der Prozess wächst, lagern Sie Vorlagen aus:

.qwen/skills/feature-spec/
  SKILL.md
  templates/
    requirements.md
    plan.md
    validation.md

In SKILL.md:

Nutze templates/requirements.md als Ausgangsstruktur.

Kopiere keine Kommentare der Vorlage in die endgültigen Spezifikationen.

Skill für Änderungsprotokoll

Ein zweiter nützlicher Skill:

.qwen/skills/changelog/SKILL.md

Beispiel:

---
name: changelog
description: Aktualisiert CHANGELOG.md basierend auf der Git-Historie und den Änderungen des aktuellen Branches vor dem Merge des Feature-Branches.
---

# Änderungsprotokoll

1. git log und git diff gegenüber main ansehen.
2. CHANGELOG.md erstellen oder aktualisieren.
3. Überschriften mit Datumsangaben verwenden.
4. Kurze Punkte schreiben, die für Stakeholder verständlich sind.
5. Keine lautstarken internen Details einschließen.

Eskalationsregeln: Wann der Agent anhalten muss

Ein guter Agent unterscheidet sich von einem schlechten nicht dadurch, dass er klüger ist, sondern dadurch, dass er weiß, wann er anhalten und fragen soll. Standardmäßig streben die meisten CLI-Agenten danach, die Aufgabe um jeden Preis zu erledigen: Wenn der Kontext nicht ausreicht, raten sie. Das ist für kurze Aufgaben eine nützliche Eigenschaft und für die Arbeit nach SDD eine schlechte.

Damit der Agent nicht rät, ist es bequem, in QWEN.md (oder im Skill) explizite Eskalationsregeln auszulagern:

Halte an und frage den Menschen, handle nicht, in folgenden Fällen:

- wenn in der Feature-Spezifikation unterschiedliche Interpretationen einer Anforderung verbleiben;

- wenn du eine Datei außerhalb der Grenzen der aktuellen Spezifikation bearbeiten willst;
- wenn du eine neue Abhängigkeit hinzufügen willst, die nicht in tech-stack.md angegeben ist;
- wenn du tech-stack.md, mission.md oder roadmap.md bearbeiten willst;
- wenn eine Migration, drop, delete oder rm mit nicht-trivialem Radius erforderlich ist;
- wenn du eine Datei nicht gefunden hast, auf die der Benutzer verweist;
- wenn das Ergebnis nicht mit einer Tatsache aus validation.md übereinstimmt und die Tatsache nicht als „verschoben" markiert ist;
- wenn die Anfrage des Benutzers zuvor akzeptierten Regeln aus QWEN.md widerspricht.

Gib in jedem solchen Fall eine kurze Erklärung, was genau mehrdeutig ist,
und schlage 2–3 konkrete Optionen zur Auswahl vor. Wähle nicht für den Menschen.

Das ist keine „Höflichkeit". Das ist ein Vertrag: Der Agent ist verpflichtet, die Kontrolle an den Menschen zurückzugeben, sobald er auf eine Bedingung aus der Liste trifft. Dieselben Regeln können zusätzlich durch einen Stop-Hook gestützt werden (siehe Teil 17), der verhindert, dass der Agent abschließt, solange er stillschweigend eine umstrittene Entscheidung getroffen hat.

Kontexthygiene und Kosten

Jede lange Sitzung hat einen Preis in zweierlei Hinsicht: Tokens und Qualität. Je länger die Sitzung dauert, desto mehr alten Kontext hat der Agent und desto leichter kann er versehentlich Lösungen aus einer benachbarten Aufgabe in die aktuelle ziehen. Bei langen Sitzungen ist ein Phänomen zu beobachten, das in Forschungsarbeiten als „Kontextdegradation" (context rot) bezeichnet wird: Ein fokussierter kurzer Input liefert ein besseres Ergebnis als ein großer irrelevanter. Dasselbe Prinzip gilt auch für das verwaltete Gedächtnis des Agenten – mehr dazu in Teil 19.

Einige einfache Hygieneregeln:

• /clear zwischen Rollen ausführen (Interview → Implementierung → Prüfung → Neuplanung);
• eine Sitzung zeitlich begrenzt halten; wenn eine Sitzung länger als eine Stunde dauert, ist es höchstwahrscheinlich an der Zeit, sie zu schließen und eine saubere zu beginnen;
• dem Agenten nicht ganze Ordner unterjubeln, wenn einzelne Dateien möglich sind;
• für lange Aufgaben @file explizit verwenden, nicht „er findet es selbst";
• bei Verdacht auf Verwirrung – /clear, QWEN.md und aktive Spezifikation von Grund auf lesen.

Wenn in Qwen Code die Option zur automatischen Kontextkomprimierung aktiviert ist, hilft sie, ersetzt aber nicht /clear. Komprimierung behält eine Zusammenfassung der Historie – das ist für eine lange ununterbrochene Aufgabe nützlich, aber genau diese Zusammenfassung wird oft zur Quelle falscher Hinweise in der nächsten Aufgabe. /clear garantiert, dass der Agent in einer neuen Rolle nur mit dem arbeitet, was im Repository festgehalten ist.

Praxis

1. Erstellen Sie .qwen/skills/feature-spec/SKILL.md.
2. Starten Sie Qwen Code neu.
3. Rufen Sie /skills auf.
4. Erstellen Sie eine neue Feature-Spezifikation über den Skill.
5. Erstellen Sie einen Skill für das Änderungsprotokoll.
6. Verwenden Sie vor dem Merge den Skill für das Änderungsprotokoll.

Kontrollfragen

1. Wann sollte eine wiederholbare Anfrage zu einem Skill werden?
2. Warum ist der projektspezifische Skill für den Teamprozess besser als der persönliche?
3. Was muss in description stehen, damit der Agent den Skill richtig findet?