Aller au contenu

Selectionner la langue

Langue actuelle: Français

Guide des dépôts MonoSpecs

Présentation

MonoSpecs est la solution de gestion multi-dépôts proposée par HagiCode ; elle suit et gère plusieurs sous-dépôts grâce à .hagicode/monospecs.yaml. Tout projet qui doit gérer de façon unifiée plusieurs dépôts indépendants peut l’utiliser.

Rappel de migration : monospecs.yaml a été déplacé de la racine du projet vers .hagicode/monospecs.yaml. Le fichier monospecs.yaml à la racine n’est plus détecté et aucun repli de compatibilité n’est prévu ; les projets existants doivent créer manuellement le répertoire .hagicode/ et y déplacer le fichier.

💡 Prise en main rapide : consultez le dépôt monospecs-demo pour découvrir la structure complète d’un projet MonoSpecs, avec le fichier de configuration, le script de clonage et la documentation README.

Concepts clés

Fichier de configuration

.hagicode/monospecs.yaml est le cœur de toute la solution de gestion ; ce fichier définit :

  • La liste et l’emplacement des sous-dépôts
  • L’URL Git de chaque dépôt
  • Le nom d’affichage et l’icône
  • Le comportement de l’intégration avec OpenSpec

Différences d’utilisation d’OpenSpec par rapport à un dépôt ordinaire

Qu’il s’agisse d’un projet géré par MonoSpecs ou d’un dépôt unique ordinaire, vous pouvez utiliser le flux OpenSpec de HagiCode pour gérer les changements. Les deux se distinguent ainsi :

CaractéristiqueDépôt ordinaireProjet géré par MonoSpecs
Emplacement d’OpenSpecopenspec/ à la racine du dépôtopenspec/ à la racine du dépôt principal
Portée des changementsLimitée au dépôt courantPeut concerner plusieurs sous-dépôts
Propreté des sous-dépôtsLes specs sont mêlées au codeLes specs sont isolées dans le dépôt principal, les sous-dépôts restent plus propres
Commit automatique à l’archivageLes changements de specs doivent être commités manuellementcommit_when_archive commite automatiquement les specs dans le dépôt principal

En résumé, avec MonoSpecs, les specs sont séparées du code des sous-dépôts, ce qui garde ces derniers propres, tandis que le commit automatique simplifie la gestion des specs.

Pourquoi utiliser MonoSpecs

  • Gestion unifiée : suivez tous les sous-dépôts dans un seul fichier de configuration
  • Prise en charge de l’automatisation : fournit des métadonnées de dépôts aux scripts et aux outils
  • Adapté à l’IA : une configuration structurée aide les Agent IA à comprendre les relations entre les dépôts
  • Intégration avec OpenSpec : s’intègre sans heurt au flux de gestion des changements

Quand utiliser MonoSpecs

Dans les situations suivantes, envisagez MonoSpecs en priorité :

1. Développement collaboratif multi-dépôts

Lorsqu’un projet est réparti en plusieurs dépôts indépendants, il faut les gérer de façon unifiée :

  • L’application front-end, le service back-end et le client de bureau sont développés séparément
  • Des projets annexes, comme la documentation, le site officiel et les outils de construction
  • Les dépôts dépendent les uns des autres, ce qui impose de coordonner les versions et les changements

2. Développement de fonctionnalités transversales

Lorsque vous gérez les changements avec OpenSpec :

  • Un changement fonctionnel peut concerner plusieurs dépôts
  • Il faut suivre dans quels dépôts le changement est mis en œuvre
  • Les changements sont commités automatiquement dans le bon dépôt cible

3. Développement assisté par l’IA

Fournissez aux Agent IA des informations sur la structure du projet :

  • Décrivez la pile technique et les conventions de chaque dépôt dans AGENTS.md
  • L’IA peut comprendre les relations entre les dépôts à partir de la configuration
  • Prise en charge de la génération de code et du refactorisation entre dépôts

4. Intégration et déploiement continus

Les pipelines CI/CD ont besoin de :

  • Traiter plusieurs dépôts par lots
  • Construire et déployer automatiquement selon la configuration
  • Suivre les versions et les dépendances de chaque dépôt

Différences entre MonoSpecs et les dépôts ordinaires

CaractéristiqueProjet multi-dépôts ordinaireProjet géré par MonoSpecs
Découverte des dépôtsRecherche et consignation manuellesLecture automatique depuis .hagicode/monospecs.yaml
Opérations par lotsScripts à écrire manuellementScripts unifiés pilotés par la configuration
Prise en charge de l’IARepose sur la documentationConfiguration structurée + AGENTS.md
Métadonnées des dépôtsDispersées un peu partoutGérées de façon centralisée (icône, nom, URL)
Intégration des nouveaux arrivantsIl faut lire plusieurs documentsIl suffit d’exécuter un script

Structure du projet

Avec MonoSpecs, il faut un dépôt principal pour gérer la configuration ; ce dépôt principal est lui-même un dépôt Git, qui sert à :

  • Stocker le fichier de configuration .hagicode/monospecs.yaml
  • Gérer la configuration et les scripts transversaux
  • Suivre les relations de métadonnées des sous-dépôts

Prenons le projet HagiCode Mono en exemple ; la structure typique d’un projet MonoSpecs est la suivante :

  • Répertoireyour-project/ # Dépôt principal (dépôt Git)
    • Répertoire.git/ # Historique Git du dépôt principal
      • …
    • .gitignore # Exclut le répertoire repos/
    • Répertoire.hagicode/ # Répertoire de données du projet HagiCode
      • monospecs.yaml # Fichier de configuration des dépôts
    • Répertoireopenspec/ # Répertoire des changements OpenSpec (facultatif)
      • …
    • Répertoirerepos/ # Répertoire des sous-dépôts (hors de Git)
      • Répertoirefrontend/ # Sous-dépôt (dépôt Git indépendant)
        • …
      • Répertoirebackend/ # Sous-dépôt (dépôt Git indépendant)
        • …
      • … # Autres sous-dépôts

Tous les sous-dépôts doivent être placés dans le répertoire repos/, et ce répertoire doit être exclu du contrôle de version Git du dépôt principal. Pour cela, ajoutez le contenu suivant au fichier .gitignore du dépôt principal :

# 排除所有子仓库
repos/

Ainsi, le dépôt principal ne suit pas le contenu des sous-dépôts, et chaque sous-dépôt gère son propre contrôle de version de manière indépendante.

Démarrage rapide

Cette section vous guide dans la configuration initiale de MonoSpecs, pour que vous puissiez commencer rapidement à utiliser la gestion multi-dépôts.

Initialisation

Suivez les étapes ci-dessous pour terminer la configuration initiale de MonoSpecs :

1. Créer un dossier repos vide

Dans votre dépôt principal, créez un dossier repos vide, qui accueillera tous les sous-dépôts. C’est le répertoire que vous excluez à l’étape 3 (configuration du .gitignore) :

终端窗口
mkdir repos
cd repos
git init
cd ..

2. Configurer le fichier MonoSpecs

À la racine du dépôt principal, créez le fichier de configuration .hagicode/monospecs.yaml et ajoutez les sous-dépôts que vous voulez gérer :

终端窗口
mkdir -p .hagicode
version: "1.0"
commit_when_archive: true
repositories:
- path: "repos/frontend"
url: "https://github.com/your-org/frontend.git"
displayName: "前端应用"
icon: "🌐"
- path: "repos/backend"
url: "https://github.com/your-org/backend.git"
displayName: "后端服务"
icon: "⚙️"

3. Ajouter la configuration .gitignore

Dans le fichier .gitignore du dépôt principal, ajoutez le contenu suivant pour exclure le répertoire des sous-dépôts :

# 排除所有子仓库
repos/

4. Récupérer tous les sous-dépôts (repo)

Utilisez le script de clonage pour récupérer les sous-dépôts configurés.

Il clonera tous les sous-dépôts dans le répertoire repos/ selon la configuration de .hagicode/monospecs.yaml.

5. Ajouter le dépôt principal à HagiCode

Si vous utilisez l’application de bureau HagiCode, ouvrez-la, puis ajoutez le dépôt principal comme projet depuis l’interface. Cliquez sur « Ajouter un projet » ou sur le bouton « + », puis sélectionnez le dossier de votre dépôt principal.

Si tout est correctement configuré, vous verrez la liste de tous les sous-dépôts et leurs informations d’état.

Configuration de .hagicode/monospecs.yaml

Emplacement du fichier de configuration

Le fichier de configuration se trouve à la racine du projet :

  • Répertoireyour-project/
    • Répertoire.hagicode/
      • monospecs.yaml

Description des options de configuration

# 版本号
version: "1.0"
# 归档时自动提交(OpenSpec 使用)
commit_when_archive: true
# 仓库列表
repositories:
# 仓库路径(相对于项目根目录)
- path: "repos/frontend"
# Git 仓库 URL
url: "https://github.com/your-org/frontend.git"
# 显示名称
displayName: "前端应用"
# 图标(emoji)
icon: "🌐"
OptionTypeObligatoireDescription
versionstringOuiVersion du fichier de configuration
commit_when_archivebooleanNonIndique s’il faut commiter automatiquement les specs dans le dépôt principal à l’archivage (le code des sous-dépôts n’est pas validé)
repositoriesarrayOuiListe de configuration des dépôts
repositories[].pathstringOuiChemin relatif du dépôt
repositories[].urlstringOuiURL du dépôt Git
repositories[].displayNamestringOuiNom d’affichage du dépôt
repositories[].iconstringNonIcône du dépôt (emoji)

Opérations de gestion des dépôts

Ajouter un nouveau dépôt

Ajoutez une nouvelle entrée au tableau repositories de .hagicode/monospecs.yaml :

repositories:
# ... 现有仓库
- path: "repos/new-service"
url: "https://github.com/HagiCode-org/new-service.git"
displayName: "新服务"
icon: "🆕"

Mettre à jour la configuration d’un dépôt

Lorsque l’URL ou les métadonnées d’un dépôt changent :

  1. Modifiez .hagicode/monospecs.yaml pour mettre à jour l’entrée correspondante
  2. Vérifiez que la syntaxe YAML est correcte
  3. Si vous devez synchroniser le changement, mettez à jour manuellement la configuration du dépôt local

Fonctionnalités clés

Cette section présente les principales fonctionnalités visuelles offertes par l’intégration de MonoSpecs avec OpenSpec, afin de vous aider à les comprendre et à les utiliser plus intuitivement.

Remarque : les captures d’écran ci-dessous montrent le résultat une fois MonoSpecs activé.

Sélection des sous-dépôts

Lors de la création d’une nouvelle proposition, vous pouvez choisir les sous-dépôts cibles à consulter et à modifier. Le système détecte automatiquement les sous-dépôts disponibles et en affiche la liste.

Sélection des sous-dépôts lors de la création d'une proposition

Lors de la création d’un changement, OpenSpec lit la configuration .hagicode/monospecs.yaml et liste tous les sous-dépôts disponibles pour que vous puissiez choisir. Vous pouvez sélectionner les sous-dépôts à modifier, et le système suit automatiquement la portée du changement.

Aperçu des détails d’un dépôt

Dans le panneau du projet, lorsque vous survolez un dépôt avec la souris, une fenêtre s’affiche avec les informations détaillées de ce dépôt et des actions rapides.

Survol pour afficher les détails d'un dépôt

Grâce à cet aperçu interactif, vous pouvez connaître rapidement :

  • Le nom du dépôt, son chemin et sa branche actuelle
  • L’état actuel du dépôt (présence de modifications non commitées, et nombre de commits d’avance ou de retard par rapport au dépôt distant)
  • Les actions rapides propres à ce dépôt : ouvrir Code Server, ouvrir la gestion Git, Super Commit, gérer DESIGN.md, accéder au dépôt

Sélection des sous-dépôts avec Super Commit

Lorsque vous utilisez Super Commit pour commiter des changements, vous pouvez choisir des sous-dépôts précis comme cibles.

Sélection des sous-dépôts avec Super Commit

La fonctionnalité Super Commit :

  1. Lit la configuration .hagicode/monospecs.yaml
  2. Analyse le contenu de vos changements
  3. Vous suggère les sous-dépôts dans lesquels commiter
  4. Vous pouvez accepter la suggestion ou désigner manuellement les dépôts cibles

Intégration avec OpenSpec

Qu’il s’agisse d’un projet géré par MonoSpecs ou d’un dépôt ordinaire, vous pouvez utiliser le flux OpenSpec de HagiCode. La principale différence réside dans l’emplacement du dossier OpenSpec et dans la façon dont les changements sont distribués.

Emplacement du dossier OpenSpec

Dépôt ordinaire :

my-repo/
- openspec/ # OpenSpec 变更目录(与代码混在一起)
- src/

Projet géré par MonoSpecs :

your-project/ # 主仓库
- openspec/ # OpenSpec 变更目录(独立管理)
- .hagicode/
- monospecs.yaml
- repos/
- frontend/ # 子仓库(更干净,无 openspec/)
- backend/ # 子仓库(更干净,无 openspec/)

Avantage : les specs sont isolées dans le dépôt principal, et les sous-dépôts restent propres, ne contenant que le code réel, sans documents de spécification mêlés.

Mécanisme de distribution des changements

Dépôt ordinaire :

  • Les changements s’appliquent uniquement au dépôt courant
  • Les specs et le code se trouvent dans le même dépôt
  • Après l’archivage, les changements liés aux specs doivent être commités manuellement

Projet géré par MonoSpecs :

  • OpenSpec lit .hagicode/monospecs.yaml pour identifier la portée des dépôts
  • Le dépôt cible est déterminé automatiquement d’après le chemin des fichiers modifiés
  • Avec commit_when_archive: true, l’archivage commite automatiquement les specs dans le dépôt principal, sans intervention manuelle
  • Les changements de code réels des sous-dépôts doivent être commités manuellement

Description de commit_when_archive

Lorsque commit_when_archive: true est défini :

version: "1.0"
commit_when_archive: true # 归档时自动提交 specs 到主仓库

Comportement à l’archivage :

  • OpenSpec commite automatiquement les changements de specs (proposal, design, tasks, etc.) dans le dépôt principal
  • Les changements de code réels des sous-dépôts ne sont pas commités (le code doit être commité manuellement)
  • Vous n’avez plus à gérer manuellement le contrôle de version des specs

Exemple de flux :

  1. Créez le changement openspec/changes/add-user-auth/
  2. Terminez la conception et les tâches, puis implémentez la fonctionnalité dans le code
  3. Lancez l’opération d’archivage
  4. OpenSpec commite automatiquement les specs dans le dépôt principal
  5. Commitez manuellement les changements de code des sous-dépôts

Exemple

Dans un projet géré par MonoSpecs, créez un changement :

openspec/changes/add-user-auth/
- proposal.md
- design.md
- tasks.md

Lorsque ce changement concerne la modification de repos/frontend/src/components/Login.tsx :

  1. OpenSpec lit .hagicode/monospecs.yaml
  2. Il identifie la configuration du dépôt correspondant à repos/frontend
  3. Le développeur implémente les changements de code
  4. À l’archivage, OpenSpec commite automatiquement les specs dans le dépôt principal
  5. Le développeur commite manuellement les changements de code du sous-dépôt frontend

Prise en charge de la configuration des Agent IA

Les projets qui utilisent MonoSpecs peuvent fournir des consignes propres au projet aux Agent IA via AGENTS.md :

  • Répertoireyour-project/
    • AGENTS.md # Configuration d’Agent au niveau du dépôt principal
    • Répertoirerepos/
      • Répertoirefrontend/
        • AGENTS.md # Configuration d’Agent propre au dépôt (hérite de la configuration principale)
      • Répertoirebackend/
        • AGENTS.md # Configuration d’Agent du dépôt back-end

Le fichier AGENTS.md de chaque dépôt peut contenir :

  • Description de la pile technique : frameworks, outils de construction, gestion d’état, etc.
  • Conventions de code : conventions de nommage, structure des fichiers, bonnes pratiques
  • Comportements propres au projet : extensions ou différences par rapport à la configuration du dépôt principal
  • Intégration avec OpenSpec : comment participer au flux de gestion des changements

Cette configuration hiérarchique permet aux Agent IA de :

  1. Comprendre les conventions globales du dépôt principal
  2. Repérer les exigences particulières de chaque dépôt
  3. Rester cohérents lors des opérations entre plusieurs dépôts

Bonnes pratiques

Conventions de nommage

  • Chemin des dépôts : utilisez le préfixe repos/ pour rester cohérent
  • Nom des dépôts : utilisez le kebab-case (lettres minuscules et traits d’union)
  • Nom d’affichage : utilisez un nom court en chinois
  • Choix de l’icône : utilisez un emoji lié à la fonction du dépôt

Maintenance de la configuration

  1. Synchroniser la configuration et l’état réel : assurez-vous régulièrement que .hagicode/monospecs.yaml reflète la structure réelle des dépôts

Migration depuis monospecs.yaml à la racine

Si le projet utilise encore monospecs.yaml à la racine, migrez-le manuellement vers le nouveau répertoire de données de projet HagiCode :

终端窗口
mkdir -p .hagicode
mv monospecs.yaml .hagicode/monospecs.yaml
git add .hagicode/monospecs.yaml
git rm monospecs.yaml
git commit -m "Move MonoSpecs config to .hagicode"

Après la migration, HagiCode ne lit plus que .hagicode/monospecs.yaml. Si seul le fichier monospecs.yaml à la racine subsiste, le projet est considéré comme n’ayant pas configuré MonoSpecs, et les scripts associés ne le liront pas comme chemin de compatibilité. 2. Contrôle de version : tous les changements de configuration doivent être commités dans le contrôle de version 3. Mise à jour de la documentation : mettez à jour la documentation concernée lorsque vous ajoutez ou supprimez un dépôt

Méthodes de vérification

  • Vérifiez que les chemins des dépôts ne contiennent pas de caractères spéciaux
  • Vérifiez que la syntaxe YAML est correcte

HagiCode

HagiCode est un espace de développement agentique. Des interactions d’interface riches et pratiques rendent la planification, l’exécution des agents et le travail sur les projets accessibles et faciles à suivre, pour une expérience de développement engageante.

Une expérience de développement engageante grâce à des interactions d’interface riches et pratiques.

Visiter HagiCodeLire la documentation
  • IntelligentLes workflows OpenSpec transforment une intention en parcours exécutable, de la proposition à la livraison en passant par la conception et les tâches.
  • EfficaceL’exécution multi-agent fait avancer recherche, réalisation et revue en parallèle, sur plusieurs dépôts et avec les Agent CLI que vous utilisez déjà.
  • IntéressantDes interactions d’interface riches et pratiques rendent la planification, l’exécution des agents et le travail sur les projets accessibles et faciles à suivre.

Télécharger pour Windows

Obtenir sur le Microsoft StoreTous les téléchargements

Transformez vos idées en logiciels livrés.

HagiCode est un espace de développement agentique : les workflows OpenSpec planifient le changement, l’exécution multi-agent le réalise et Hero Scenario rend le long parcours visible, pour transformer vos idées en logiciels livrés.

Intelligent
Les workflows OpenSpec transforment une intention en parcours, de la proposition à la livraison.
Efficace
L’exécution multi-agent mène recherche, réalisation et revue en parallèle.
Ludique
Les interactions d’interface facilitent la planification, l’exécution des agents et les projets.