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.yamla été déplacé de la racine du projet vers.hagicode/monospecs.yaml. Le fichiermonospecs.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éristique | Dépôt ordinaire | Projet géré par MonoSpecs |
|---|---|---|
| Emplacement d’OpenSpec | openspec/ à la racine du dépôt | openspec/ à la racine du dépôt principal |
| Portée des changements | Limitée au dépôt courant | Peut concerner plusieurs sous-dépôts |
| Propreté des sous-dépôts | Les specs sont mêlées au code | Les specs sont isolées dans le dépôt principal, les sous-dépôts restent plus propres |
| Commit automatique à l’archivage | Les changements de specs doivent être commités manuellement | commit_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éristique | Projet multi-dépôts ordinaire | Projet géré par MonoSpecs |
|---|---|---|
| Découverte des dépôts | Recherche et consignation manuelles | Lecture automatique depuis .hagicode/monospecs.yaml |
| Opérations par lots | Scripts à écrire manuellement | Scripts unifiés pilotés par la configuration |
| Prise en charge de l’IA | Repose sur la documentation | Configuration structurée + AGENTS.md |
| Métadonnées des dépôts | Dispersées un peu partout | Gérées de façon centralisée (icône, nom, URL) |
| Intégration des nouveaux arrivants | Il faut lire plusieurs documents | Il 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 reposcd reposgit initcd ..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 .hagicodeversion: "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: "🌐"| Option | Type | Obligatoire | Description |
|---|---|---|---|
version | string | Oui | Version du fichier de configuration |
commit_when_archive | boolean | Non | Indique 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é) |
repositories | array | Oui | Liste de configuration des dépôts |
repositories[].path | string | Oui | Chemin relatif du dépôt |
repositories[].url | string | Oui | URL du dépôt Git |
repositories[].displayName | string | Oui | Nom d’affichage du dépôt |
repositories[].icon | string | Non | Icô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 :
- Modifiez
.hagicode/monospecs.yamlpour mettre à jour l’entrée correspondante - Vérifiez que la syntaxe YAML est correcte
- 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.

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.

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.

La fonctionnalité Super Commit :
- Lit la configuration
.hagicode/monospecs.yaml - Analyse le contenu de vos changements
- Vous suggère les sous-dépôts dans lesquels commiter
- 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.yamlpour 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 :
- Créez le changement
openspec/changes/add-user-auth/ - Terminez la conception et les tâches, puis implémentez la fonctionnalité dans le code
- Lancez l’opération d’archivage
- OpenSpec commite automatiquement les specs dans le dépôt principal
- 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.mdLorsque ce changement concerne la modification de repos/frontend/src/components/Login.tsx :
- OpenSpec lit
.hagicode/monospecs.yaml - Il identifie la configuration du dépôt correspondant à
repos/frontend - Le développeur implémente les changements de code
- À l’archivage, OpenSpec commite automatiquement les specs dans le dépôt principal
- 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 :
- Comprendre les conventions globales du dépôt principal
- Repérer les exigences particulières de chaque dépôt
- 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
- Synchroniser la configuration et l’état réel : assurez-vous régulièrement que
.hagicode/monospecs.yamlreflè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 .hagicodemv monospecs.yaml .hagicode/monospecs.yamlgit add .hagicode/monospecs.yamlgit rm monospecs.yamlgit 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.
- 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
Partager HagiCode
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.
© 2026 HagiCode | Powered By hagilight-starlight@0.21.0 | Branch: main | Commit: 752f8bc | Built:

