Optimierung der OpenSpec-Leistung in verschiedenen Phasen mit verschiedenen Agenten: HagiCode Praxiszusammenfassung

08.05.2026

Optimierung der OpenSpec-Leistung in verschiedenen Phasen mit verschiedenen Agenten: HagiCode Praxiszusammenfassung

Generische Prompts können den spezifischen Anforderungen verschiedener Entwicklungsphasen nicht gerecht werden. Durch phasenspezifische Agenten und ein parametrisiertes Template-System kann die KI in jedem Schritt hochwertige Inhalte liefern.

Hintergrund

OpenSpec ist ein antriebsgesteuertes Entwicklungssystem, das die Erstellung, Prüfung und Implementierung technischer Vorschläge durch einen strukturierten Workflow verwaltet. Die Idee an sich ist gut, aber in der praktischen Anwendung haben wir festgestellt, dass ein einzelner generischer KI-Prompt deutliche Probleme aufweist.

Die Explore-Phase fehlt an Kontextverankerung, die KI-Exploration weicht leicht vom Vorschlagsbereich ab; die Artefakterzeugungsqualität ist instabil, design.md fehlen visuelle Elemente, proposal.md fehlen Codeänderungstabellen, tasks.md enthalten sogar Git-Operationen, die nicht enthalten sein sollten; Verantwortungsgrenzen sind verschwommen, es ist unklar, welche Inhalte verschiedenen Dokumenttypen enthalten sollten; Prompts fehlen Flexibilität und können das KI-Verhalten nicht dynamisch an verschiedene Szenarien anpassen.

Diese Probleme wirken sich direkt auf die Effizienz und Ausgabequalität des OpenSpec-Workflows aus. Eigentlich gibt es keinen anderen Weg, als die Prompt-Templates manuell zu ändern. Dieser Artikel ist eine Aufzeichnung aus dieser Zeit.

Über HagiCode

Die in diesem Artikel vorgestellte Lösung stammt aus unserer praktischen Erfahrung im HagiCode-Projekt. HagiCode ist ein KI-gesteuerter Code-Assistent, und während der Entwicklung nutzen wir extensiv den OpenSpec-Workflow zur Verwaltung technischer Vorschläge. Die in diesem Artikel vorgestellte Agent-Schichtungsstrategie ist genau die Optimierungslösung, die wir aus der praktischen Nutzung abgeleitet haben.

Wenn Sie diese Lösung als wertvoll empfinden, bedeutet das, dass unsere technische Praxis recht gut ist – HagiCode selbst verdient ebenfalls Beachtung.

OpenSpec-Workflow-Analyse

Das OpenSpec-System umfasst mehrere Kernphasen, jede mit spezifischen Zielen und Randbedingungen. Das Verständnis der Verantwortungsgrenzen dieser Phasen ist die Grundlage für die Entwicklung einer effektiven Agent-Strategie.

┌─────────────────────────────────────────────────────────────────────┐
│                        OpenSpec-Workflow-Phasen                     │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
│  │ Explore  │ -> │   New    │ -> │    FF    │ -> │  Apply   │     │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
│  │ Archive  │    │   Sync   │    │ Verify   │    │  Status  │     │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
└─────────────────────────────────────────────────────────────────────┘

Die Ziele jeder Phase unterscheiden sich vollständig: Die Explore-Phase erfordert eine Denkhaltung, konzentriert auf die Informationssammlung; die New-Phase soll auf die Bedarfsanalyse und Lösungsentwicklung fokussieren; die FF-Phase erstellt Artefakte massenhaft in Abhängigkeitsreihenfolge; die Apply-Phase verwandelt Vorschläge in tatsächlichen Code. Dieselbe Prompt-Vorlage für diese sehr unterschiedlichen Aufgaben einzusetzen, ist offensichtlich nicht angemessen.

Prompt-Systemarchitektur

OpenSpec nutzt ein templatbasiertes Prompt-System, was die technische Grundlage für die Agent-Schichtung bietet. Die Template-Dateien verwenden das .hbs-Format (Handlebars/Scriban), zusammen mit .json-Metadatendateien zur Definition von Parametern und Validierungsregeln, und unterstützen zweisprachigen Chinesisch-Englisch-Betrieb.

Die zentrale Entwurfsentscheidung ist die PromptScenario-Enumeration, die verschiedene Phasen-definierte Prompt-Szenarien festlegt:

public enum PromptScenario
{
    OpenspecV1Explore,      // Erkundungsphase
    OpenspecV1New,          // Neuer Vorschlag
    OpenspecV1Ff,           // Schnelle Generierung
    OpenspecV1Apply,        // Änderungen anwenden
    OpenspecV1Archive       // Archivieren
}

Jedes Szenario verfügt über eine entsprechende unabhängige Template-Datei, wie beispielsweise openspec-v1-explore.zh-CN.hbs und openspec-v1-ff.zh-CN.hbs, die es ermöglicht, phasenspezifische Randbedingungen und Anleitungen einzufügen.

Parametrisiertes Prompt-Laden

Die Implementierung der dynamischen Parameterinjektion ist der Kern des gesamten Systems. Der FilePromptProvider ist verantwortlich für das Laden von Prompts basierend auf Szenarien und Parametern:

public async Task<string> GetOpenspecV1FfPromptAsync(
    string changeName,
    string changeDescription,
    string locale = "en-US",
    string? planningDirectionInstructions = null,
    CancellationToken cancellationToken = default)
{
    var parameters = new Dictionary<string, object>
    {
        { "planningDirectionInstructions",
          ResolvePlanningDirectionInstructions(locale, planningDirectionInstructions) }
    };

    if (!string.IsNullOrWhiteSpace(changeName))
    {
        parameters["changeName"] = changeName;
    }

    return await GetPromptWithParametersAsync(
        PromptScenario.OpenspecV1Ff,
        locale,
        cancellationToken,
        parameters);
}

Dieser Ansatz ermöglicht es uns, zur Laufzeit dynamisch Parameter wie changeName und planningDirectionInstructions zu injizieren, ohne die Template-Datei selbst ändern zu müssen.

Dynamische Konfiguration der Planungsrichtung

HagiCode implementiert ein flexibles Planungsrichtungssystem, das es den Benutzern ermöglicht, für jede Generierung eine andere Richtung zu wählen. Jede Richtung verfügt über eine unabhängige ID, Beschreibung und Prompt-Fragment:

public static class ProposalPlanningDirections
{
    private static readonly ProposalPlanningDirectionDefinition[] Catalog =
    [
        new(
            ExploreId,
            "Erkundungsmodus",
            DefaultEnabled: true,
            EnglishPromptFragment:
            "- Erkundungsmodus: Füge eine explizite Erkundungsrunde hinzu...",
            ChinesePromptFragment:
            "- 探索模式：在定稿工件之前增加明确的探索阶段..."),
        // ... change-map, flowchart, prototype, architecture, sequence
    ];

    public static NormalizedProposalPlanningDirections Normalize(
        bool? enableExploreMode,
        IReadOnlyList<PlanningDirectionOptionDto>? planningDirections)
    {
        // Standardkonfiguration und benutzerdefinierte Konfiguration zusammenführen
    }
}

Unterstützte Richtungen umfassen: explore (Erkundungsmodus), change-map (Änderungskarte), flowchart (Interaktionsflussdiagramm), prototype (UI-Prototyp), architecture (Architekturdiagramm), sequence (API-Sequenzdiagramm). Benutzer können diese Richtungen nach Belieben aktivieren oder deaktivieren, und das System generiert dynamisch entsprechende Prompt-Anweisungsblöcke.

In Handlebars-Templates werden bedingte Anweisungen verwendet, um diese Anweisungen einzufügen:

{{#if planningDirectionInstructions}}
## Planungsrichtung für diese Generierung

{{{planningDirectionInstructions}}}
{{/if}}

Klare Inhaltsbereichsbeschränkungen

Die wichtigste Verbesserung ist die Klarstellung der Inhaltsbereichsbeschränkungen für verschiedene Dokumenttypen, insbesondere tasks.md. Wir haben strenge Randbedingungen in den Prompt aufgenommen:

### tasks.md Inhaltsbereichsbeschränkungen

Bei der Erstellung von `tasks.md`-Artefakten müssen die folgenden Inhaltsbereichsbeschränkungen beachtet werden:

**Muss enthalten**:
- Geschäftslogikaufgaben (Code-Implementierung, Funktionsentwicklung)
- Technische Implementierungsaufgaben (Komponentenintegration, API-Entwicklung)
- Testaufgaben (Unit-Tests, Integrationstests)
- Dokumentationsaufgaben (Dokumentation aktualisieren, Kommentare hinzufügen)

**Darf nicht enthalten**:
- Git-Commit-Operationen (git add, git commit, git push)
- Versionskontrollverwaltungsworkflows
- Bereitstellungs- und Veröffentlichungsoperationen

Die Verwendung von normativer Sprache (MUST/SHALL) statt empfehlender Sprache stellt sicher, dass die KI diese Randbedingungen strikt versteht. Für proposal.md und design.md haben wir ebenfalls ihre jeweiligen Verantwortungsgrenzen geklärt: proposal.md muss Codeänderungstabellen und UI-Prototypdiagramme enthalten (wenn UI-Änderungen betroffen sind), während design.md Architekturdiagramme und Datenflussdiagramme enthalten muss.

Kontextverankerung in der Erkundungsphase

Das Problem der Explore-Phase wird am leichtesten übersehen – die KI-Erkundung könnte vollständig vom Vorschlagsbereich abweichen. Wir haben dies durch Prompt-Verbesserungen gelöst:

## Explore-Ausführungsprinzipien

- **Keine Dokumentation erforderlich** - Erkundungsergebnisse müssen nicht als unabhängiges Dokument gespeichert werden
- **Informationsübermittlung** - Nach Abschluss der Erkundung werden die gesammelten Informationen an die Proposal-Erstellungsphase übermittelt
- **Fokus auf Nachdenken** - Der Wert der Erkundung liegt in der Informationssammlung, nicht in der Dokumentproduktion

## Verbindung mit Proposal-Erstellung

Die Explore-Phase findet statt, nachdem der Vorschlag erstellt wurde, aber bevor der Projektcode geschrieben wurde. Nach Abschluss der Erkundung
wird das System Sie zur Erstellung oder Auffüllung der Datei `proposal.md` leiten, und die durch Erkundung gesammelten Informationen dienen als Grundlage für den Vorschlagsinhalt.

Dies klärt die Positionierung der Explore-Phase: Sie ist ein vorbereitender Informationssammlungsschritt, kein unabhängiger Dokumentproduktionsabschnitt. Nachdem die KI dies versteht, kann sie sich stärker auf vorschlagsbezogene Wissenserkundung konzentrieren.

Implementierungsleitfaden

Wenn Sie diese Lösung in HagiCode anwenden möchten, können Sie die folgenden Schritte durchführen:

1. Planungsrichtungen definieren: Definieren Sie Richtungs-ID, Standardstatus und Prompt-Fragmente in ProposalPlanningDirections.cs
2. Template-Parameterisierung: Verwenden Sie bedingte Anweisungen und Variableninjektion in .hbs-Templates
3. Ausgabe validieren: Überprüfen Sie, ob entsprechende Artefakte die erwarteten Inhalte enthalten, wenn bestimmte Richtungen aktiviert sind
4. Grenzen testen: Validieren Sie, dass bei deaktivierten Richtungen keine entsprechenden Inhalte generiert werden und andere Richtungen nicht beeinträchtigt werden

Beachten Sie, dass Template-Änderungen mit Upstream synchron gehalten werden sollten und die Struktur der chinesischen und englischen Templates konsistent sein sollte. Das Rendern der Planungsrichtungen sollte im Mikrosekundenbereich abgeschlossen werden, um Auswirkungen auf die Leistung zu vermeiden.

Zusammenfassung

Die Leistungsoptimierung des OpenSpec-Workflows liegt im Verständnis der differenzierten Anforderungen verschiedener Phasen. Durch phasenspezifische Agenten, parametrisierte Templates und klare Inhaltsrandbedingungen ermöglichen wir der KI, in jedem Schritt hochwertige Inhalte zu liefern.

Diese Lösung wurde in der Praxis von HagiCode validiert – sie verbesserte nicht nur die Dokumentqualität, sondern reduzierte auch den Aufwand für manuelle Änderungen. Wenn Ihr Team einen ähnlichen vorschlagsgetriebenen Workflow verwendet, hoffe ich, dass diese Erfahrungen für Sie inspirierend sind.

Am Ende ist es nur das Zerlegen von Problemen. Jede Phase hat ihre eigenen Besonderheiten, wenn die richtige Methode angewendet wird, werden Probleme natürlich einfacher.

Referenzmaterialien

• HagiCode-Projektadresse: github.com/HagiCode-org/site
• HagiCode-Website: hagicode.com
• Demo-Video der offiziellen Version: www.bilibili.com/video/BV1z4oWB3EpY/
• Ein-Klick-Installation zum Erleben: docs.hagicode.com/installation/docker-compose
• Desktop-Client schnelle Installation: hagicode.com/desktop/

---

Wenn dieser Artikel für Sie hilfreich ist:

• Geben Sie ein Like, damit mehr Personen es sehen
• Kommen Sie zu GitHub und geben Sie einen Star
• Besuchen Sie die Website für weitere Informationen
• Schauen Sie sich das Demo-Video an, um die vollständigen Funktionen zu verstehen
• Ein-Klick-Installation starten, um zu erleben

Die öffentliche Beta hat begonnen, willkommen zur Installation und zum Erleben!

Tags:

• OpenSpec
• AI
• Agent
• Prompt Engineering
• HagiCode
• Workflow-Optimierung

So integrieren und verwenden Sie impeccable

Anpassung der OpenSpec-Schritte zur Verbesserung der KI-Generierungsergebnisse