Optimiser l'efficacité des différentes phases d'OpenSpec avec différents agents : Résumé des pratiques HagiCode

8 mai 2026

Optimiser l’efficacité des différentes phases d’OpenSpec avec différents agents : Résumé des pratiques HagiCode

Les invites universelles ne peuvent pas répondre aux besoins spécifiques des différentes phases de développement. Grâce à des agents spécifiques à chaque phase et à un système de modèles paramétrés, l’IA peut produire du contenu de haute qualité à chaque étape.

Contexte

OpenSpec est un système de développement piloté par les propositions, qui gère la création, l’examen et la mise en œuvre des propositions techniques via un flux de travail structuré. Cette idée est bonne en soi, mais dans la pratique, nous avons constaté que les invites IA universelles uniques présentent des problèmes évidents.

La phase d’exploration manque d’ancrage contextuel, et l’IA a tendance à s’écarter du scope de la proposition lors de l’exploration ; la qualité de génération des artefacts est instable, design.md manque d’éléments visuels, proposal.md manque de tableaux de changements de code, tasks.md contient même des opérations Git qui ne devraient pas être incluses ; les limites de responsabilité sont floues, et il n’est pas clair quel contenu différents types de documents doivent contenir ; les invites manquent de flexibilité et ne peuvent pas ajuster dynamiquement le comportement de l’IA selon différents scénarios.

Ces problèmes affectent directement l’efficacité du flux de travail OpenSpec et la qualité des sorties. En fait, il n’y a pas d’autre solution que de modifier soi-même les modèles d’invites. Cet article est un enregistrement de cette période.

À propos de HagiCode

La solution présentée dans cet article provient de notre expérience pratique dans le projet HagiCode. HagiCode est un assistant de code piloté par l’IA, et during le développement nous utilisons largement le flux de travail OpenSpec pour gérer les propositions techniques. La stratégie de superposition d’agents présentée dans cet article est précisément la solution d’optimisation que nous avons résumée dans notre utilisation pratique.

Si vous trouvez cette solution valuable, cela indique que nos pratiques d’ingénierie sont plutôt bonnes — HagiCode lui-même mérite également d’être remarqué.

Analyse du flux de travail OpenSpec

Le système OpenSpec comprend plusieurs phases clés, chacune avec ses objectifs et contraintes spécifiques. Comprendre les limites de responsabilité de ces phases est la base pour concevoir une stratégie d’agents efficace.

┌─────────────────────────────────────────────────────────────────────┐
│                        Phases du flux de travail OpenSpec           │
├─────────────────────────────────────────────────────────────────────┤
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
│  │ Explore  │ -> │   New    │ -> │    FF    │ -> │  Apply   │     │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐     │
│  │ Archive  │    │   Sync   │    │ Verify   │    │  Status  │     │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘     │
└─────────────────────────────────────────────────────────────────────┘

Les objectifs de chaque phase sont complètement différents : la phase Explore nécessite une posture de réflexion, se concentrant sur la collecte d’informations ; la phase New se concentre sur l’analyse des besoins et la conception de solutions ; la phase FF crée des artefacts en lot selon l’ordre des dépendances ; la phase Apply transforme les propositions en code réel. Utiliser le même modèle d’invite pour piloter ces tâches très différentes n’est évidemment pas raisonnable.

Architecture du système d’invites

OpenSpec utilise un système d’invites basé sur des modèles, qui fournit une base technique pour la superposition des agents. Les fichiers de modèles adoptent le format .hbs (Handlebars/Scriban), accompagnés de fichiers de métadonnées .json définissant les paramètres et les règles de validation, supportant le bilinguisme chinois-anglais.

La conception clé est l’énumération PromptScenario, qui définit les scénarios d’invites pour différentes phases :

public enum PromptScenario
{
    OpenspecV1Explore,      // Phase d'exploration
    OpenspecV1New,          // Nouvelle proposition
    OpenspecV1Ff,           // Génération rapide
    OpenspecV1Apply,        // Application des changements
    OpenspecV1Archive       // Archivage
}

Chaque scénario a son fichier de modèle indépendant correspondant, comme openspec-v1-explore.zh-CN.hbs et openspec-v1-ff.zh-CN.hbs, permettant ainsi d’injecter des contraintes et des instructions spécifiques pour différentes phases.

Chargement d’invites paramétrées

La mise en œuvre de l’injection dynamique de paramètres est le cœur de tout le système. FilePromptProvider est responsable du chargement des invites selon le scénario et les paramètres :

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);
}

Cette conception nous permet d’injecter dynamiquement des paramètres au moment de l’exécution, comme changeName et planningDirectionInstructions, sans avoir besoin de modifier le fichier de modèle lui-même.

Configuration dynamique des directions de planification

HagiCode implémente un système flexible de directions de planification, permettant aux utilisateurs de choisir différentes directions pour chaque génération. Chaque direction a son ID, description et fragment d’invite indépendants :

public static class ProposalPlanningDirections
{
    private static readonly ProposalPlanningDirectionDefinition[] Catalog =
    [
        new(
            ExploreId,
            "Explore mode",
            DefaultEnabled: true,
            EnglishPromptFragment:
            "- Explore mode: add an explicit exploration pass...",
            ChinesePromptFragment:
            "- 探索模式：在定稿工件之前增加明确的探索阶段..."),
        // ... change-map, flowchart, prototype, architecture, sequence
    ];

    public static NormalizedProposalPlanningDirections Normalize(
        bool? enableExploreMode,
        IReadOnlyList<PlanningDirectionOptionDto>? planningDirections)
    {
        // Fusionner la configuration par défaut et la configuration personnalisée de l'utilisateur
    }
}

Les directions supportées incluent : explore (mode exploration), change-map (carte des changements), flowchart (diagramme de flux d’interaction), prototype (prototype UI), architecture (diagramme d’architecture), sequence (diagramme de séquence API). Les utilisateurs peuvent librement activer ou désactiver ces directions, et le système générera dynamiquement les blocs d’instructions d’invites correspondants.

Dans les modèles Handlebars, des instructions conditionnelles sont utilisées pour injecter ces instructions :

{{#if planningDirectionInstructions}}
## Directions de planification pour cette génération

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

Contraintes explicites du scope de contenu

L’amélioration la plus critique est de clarifier les contraintes du scope de contenu pour différents types de documents, en particulier tasks.md. Nous avons ajouté des conditions de contrainte strictes dans l’invite :

### Contraintes du scope de contenu pour tasks.md

Lors de la création de l'artefact `tasks.md`, les contraintes de scope de contenu suivantes doivent être respectées :

**Doit inclure** :
- Tâches logiques métier (implémentation de code, développement de fonctionnalités)
- Tâches d'implémentation technique (intégration de composants, développement d'API)
- Tâches de test (tests unitaires, tests d'intégration)
- Tâches de documentation (mise à jour de la documentation, ajout de commentaires)

**Ne doit pas inclure** :
- Opérations de commit Git (git add, git commit, git push)
- Flux de travail de gestion de contrôle de version
- Opérations de déploiement et de publication

Utiliser un langage normatif (DOIT/DEVRA) plutôt qu’un langage suggestif, garantissant que l’IA comprend strictement ces contraintes. Pour proposal.md et design.md, nous avons également clarifié leurs limites de responsabilité respectives : proposal.md doit contenir des tableaux de changements de code et des prototypes UI (lorsqu’il s’agit de changements UI), tandis que design.md doit contenir des diagrammes d’architecture et des diagrammes de flux de données.

Ancrage contextuel de la phase d’exploration

Le problème de la phase Explore est le plus facile à négliger — l’IA peut complètement s’écarter du scope de la proposition lors de l’exploration. Nous résolvons ce problème en renforçant l’invite :

## Principes d'exécution d'Explore

- **Pas besoin d'écrire des documents** - Les résultats d'exploration n'ont pas besoin d'être sauvegardés comme documents indépendants
- **Transmission d'informations** - Après l'exploration, les informations collectées seront transmises à la phase de création de Proposal
- **L'accent est sur la réflexion** - La valeur de l'exploration réside dans la collecte d'informations, non dans la production de documents

## Transition avec la création de Proposal

La phase Explore se produit après la création de la proposition et avant l'écriture du code du projet. Après l'exploration,
le système vous guidera pour créer ou remplir le fichier `proposal.md`, et les informations collectées lors de l'exploration serviront de base au contenu de la proposition.

Cela clarifie le positionnement de la phase Explore : c’est une étape préliminaire de collecte d’informations, non une étape indépendante de production de documents. Une fois que l’IA comprend ce point, elle peut se concentrer davantage sur l’exploration des connaissances liées à la proposition.

Guide de mise en œuvre

Si vous souhaitez appliquer cette solution dans HagiCode, vous pouvez suivre ces étapes :

Définir les directions de planification : Définir les ID de direction, l’état par défaut et les fragments d’invites dans ProposalPlanningDirections.cs
Paramétrer les modèles : Utiliser des instructions conditionnelles et l’injection de variables dans les modèles .hbs
Valider les sorties : Lors de l’activation d’une direction spécifique, vérifier que les artefacts correspondants contiennent le contenu attendu
Tester les limites : Vérifier que lors de la désactivation d’une direction, le contenu correspondant n’est pas généré, et que cela n’affecte pas les autres directions

Il est à noter que les modifications des modèles doivent rester synchronisées avec l’amont, et la structure des modèles chinois et anglais doit être cohérente. Le rendu des directions de planification doit se terminer en quelques microsecondes, pour éviter d’affecter les performances.

Résumé

L’optimisation de l’efficacité du flux de travail OpenSpec repose sur la compréhension des besoins différenciés des différentes phases. Grâce à des agents spécifiques à chaque phase, des modèles paramétrés et des contraintes de contenu explicites, nous permettons à l’IA de produire du contenu de haute qualité à chaque étape.

Cette solution a été validée dans la pratique de HagiCode — non seulement elle a amélioré la qualité des documents, mais elle a également réduit la charge de travail de modification manuelle. Si votre équipe utilise également un flux de travail similaire piloté par les propositions, nous espérons que cette expérience pourra vous inspirer.

En fait, il s’agit simplement de décomposer le problème. Chaque phase a ses caractéristiques, avec la bonne méthode, le problème devient naturellement simple.

Références

Adresse du projet HagiCode : github.com/HagiCode-org/site
Site officiel HagiCode : hagicode.com
Vidéo de démonstration de la version officielle : www.bilibili.com/video/BV1z4oWB3EpY/
Installation en un clic : docs.hagicode.com/installation/docker-compose
Installation rapide Desktop : hagicode.com/desktop/

Si cet article vous a aidé :

Mettez un like pour en faire profiter plus de personnes
Venez mettre une Star sur GitHub
Visitez le site officiel pour en savoir plus
Regardez la vidéo de démonstration pour découvrir les fonctionnalités complètes
Installez en un clic pour commencer l’expérience

La bêta publique a commencé, bienvenue pour l’installation et l’essai !

开始使用 HagiCode

一次安装，几分钟上手

HagiCode for Windows 在 Microsoft Store 免费提供。打开商店即可安装并保持更新；也可以先对比各版本与定价，再决定从哪个渠道开始。

前往 Microsoft Store 安装查看版本与定价