MonoSpecs Multi-Repository-Verwaltungshandbuch

Übersicht

MonoSpecs ist der Multi-Repository-Verwaltungsansatz von HagiCode. Es verfolgt und verwaltet Unterrepositorys monospecs.yamlund es funktioniert für jedes Projekt, das einen Ort zum Koordinieren mehrerer unabhängiger Repositorys benötigt.

Kernkonzepte

Konfigurationsdatei

monospecs.yaml ist der Kern der gesamten Managementlösung und definiert:

• Liste und Speicherort der Unterrepositorys
• Git-URL für jedes Repository
• Anzeigename und Symbol
• Integrationsverhalten mit OpenSpec

Unterschiede zu regulären Repositories

Funktion	Reguläres Repository	Von MonoSpecs verwaltetes Projekt
OpenSpec-Standort	Stammverzeichnisse openspec/	Stammverzeichnis des Haupt-Repositorys openspec/
Umfang ändern	Beschränkt auf das aktuelle Repository	Kann mehrere Unterrepositorys umfassen
Unterrepository-Reinheit	Spezifikationen gemischt mit Code	Die Spezifikationen sind im Haupt-Repository festgelegt, Unter-Repositorys sind sauberer
Auto-Commit archivieren	Erfordert manuelle Spezifikations-Commits	commit_when_archive: true Überträgt Spezifikationen automatisch an das Haupt-Repository

Warum MonoSpecs verwenden?

• Einheitliche Verwaltung: Verwalten Sie alle Unterrepositorys in einer Konfigurationsdatei
• Automatisierungsunterstützung: Stellt Repository-Metadaten für Skripte und Tools bereit
• KI-Freundlichkeit: Die strukturierte Konfiguration hilft AI Agent, Repository-Beziehungen zu verstehen
• OpenSpec-Integration: Nahtlose Integration in den Change-Management-Workflow
• Sauberere Unterrepositorys: Spezifikationen werden im Hauptrepo gespeichert, Unterrepositorys enthalten nur tatsächlichen Code

Anwendbare Szenarien

Verwenden Sie MonoSpecs zuerst in Szenarien wie diesen:

1. Kollaborative Multi-Repository-Entwicklung Wenn ein Projekt in mehrere unabhängige Repositorys aufgeteilt wird:

• Frontend-Anwendung, Backend-Dienst und Desktop-App werden separat entwickelt
• Versionen und Abhängigkeiten über Repositorys hinweg müssen koordiniert werden
• Dokumentation und Hilfsprojekte getrennt vom Hauptcode

2. Hilfsprojektmanagement Verwenden Sie MonoSpecs, um Folgendes zu verwalten:

• Dokumentationsprojekt
• Offizielle Website
• Erstellen Sie Tools und Skripte
• Jedes Repository unterhält seine eigene Versionskontrolle

3. Entwicklung Repository-übergreifender Funktionen Eine Funktion, die Änderungen über mehrere Repositorys hinweg erfordert:

• Änderungen in welchen Repositorys müssen nachverfolgt werden
• Übertragen Sie Spezifikationen automatisch an das richtige Ziel-Repository
• Koordinieren Sie Versionsaktualisierungen und Abhängigkeiten

Schnellstart

Initialisierung

Befolgen Sie diese Schritte, um die MonoSpecs-Initialisierung abzuschließen:

1. Erstellen Sie ein leeres Git-Repository

Erstellen Sie ein Leerzeichen git Ordner in Ihrem Haupt-Repository (Hinweis: Dies ist git, nicht repos/ - das ist die MonoSpecs-Konvention):

mkdir git
cd git
git init
cd ..

2. Konfigurieren Sie die MonoSpecs-Datei

Erstellen Sie die monospecs.yaml Konfigurationsdatei in Ihrem Haupt-Repository-Stammverzeichnis:

version: "1.0"
commit_when_archive: true

repositories:
  - path: "repos/frontend"
    url: "https://github.com/your-org/frontend.git"
    displayName: "Frontend App"
    icon: "🌐"

  - path: "repos/backend"
    url: "https://github.com/your-org/backend.git"
    displayName: "Backend Service"
    icon: "⚙️"

Konfigurationselemente:

Konfigurationselement	Typ	Erforderlich	Beschreibung
version	Zeichenfolge	Ja	Version der Konfigurationsdatei
commit_when_archive	Boolescher Wert	Nein	Ob Spezifikationen beim Archivieren automatisch festgeschrieben werden sollen (kein Sub-Repo-Code festschreiben)
repositories	Array	Ja	Repository-Konfigurationsliste
repositories[].path	Zeichenfolge	Ja	Repository-Pfad (relativ zum Projektstamm)
repositories[].url	Zeichenfolge	Ja	Git-Repository-URL
repositories[].displayName	Zeichenfolge	Nein	Anzeigename des Repositorys
repositories[].icon	Zeichenfolge	Nein	Repository-Symbol (Emoji)

Unterrepositorys zum Hauptrepository hinzufügen

Fügen Sie alle Unterrepositorys zum hinzu repos/ Verzeichnis. Dieses Verzeichnis muss von der Git-Versionskontrolle des Haupt-Repositorys ausgeschlossen sein, um die Verfolgung von Unter-Repository-Inhalten zu vermeiden:

# Exclude all sub-repositories
repos/

3. Fügen Sie das übergeordnete Repository zu HagiCode hinzu

Wenn Sie die HagiCode-Desktopanwendung verwenden, öffnen Sie die App und fügen Sie Ihr Haupt-Repository als Projekt hinzu. Klicken Sie auf dem Startbildschirm auf die Schaltfläche „Projekt hinzufügen“ oder „+“, wählen Sie Ihren Haupt-Repository-Ordner aus und Sie sehen alle Unter-Repositorys und deren Statusinformationen.

4. Unterrepositorys klonen

Benutzen Sie die monospecs.yaml Konfiguration, um alle konfigurierten Unterrepositorys in die zu klonen repos/ Verzeichnis:

Dadurch werden alle Unterrepositorys basierend auf den in der Konfigurationsdatei angegebenen URLs geklont.

Struktur der Konfigurationsdatei

Konfiguration auf Root-Ebene

version: "1.0"
commit_when_archive: true

repositories:
  # ... repository configurations

Konfiguration auf Repository-Ebene

Jedes Unter-Repository kann Folgendes haben:

• OpenSpec-Änderungsordner (openspec/)
• Unabhängig .git/ Verzeichnis
• Optional AGENTS.md für die AI Agent-Konfiguration

Repository-Verwaltungsvorgänge

Neues Repository hinzufügen

Beim Hinzufügen eines neuen Unter-Repositorys zum monospecs.yaml repositories Array:

repositories:
  - path: "repos/new-service"
    url: "https://github.com/HagiCode-org/new-service.git"
    displayName: "New Service"
    icon: "🆕"

Repository-Konfiguration aktualisieren

Wenn sich Repository-URLs oder Metadaten ändern:

1. Bearbeiten monospecs.yaml um entsprechende Einträge zu aktualisieren
2. Überprüfen Sie, ob die YAML-Syntax korrekt ist
3. Wenn Sie Änderungen synchronisieren, aktualisieren Sie die lokale Repository-Konfiguration manuell

Unterstützung der AI Agent-Konfiguration

AGENTEN.md

Die AGENTS.md Die Datei enthält Repository-spezifische Anleitungen für den AI Agent:

Technische Stack-Informationen

• Framework und Build-Tools
• Codekonventionen und Benennungspraktiken
• Versionsverwaltung und Bereitstellungskonfiguration

Projektspezifische Verhaltensweisen

• Konfigurationserweiterungen und besondere Anforderungen
• OpenSpec-Integrationsmuster
• Anforderungen an die Repository-übergreifende Koordination

KI-Vorteile

Benutzen AGENTS.md ermöglicht dem KI-Agenten:

• Verstehen Sie Repository-Beziehungen und -Abhängigkeiten
• Generieren Sie Code und Refactoring über mehrere Repositorys hinweg
• Sorgen Sie für Konsistenz bei der Versionskontrolle und den Konfigurationen

OpenSpec-Integration

Wie MonoSpecs mit OpenSpec funktioniert

Unabhängig davon, ob Sie ein von MonoSpecs verwaltetes Projekt oder ein reguläres Repository verwalten, können Sie den OpenSpec-Workflow von HagiCode verwenden:

Reguläres Repository:

• OpenSpec im Root openspec/ Verzeichnis
• Änderungen wirken sich nur auf das aktuelle Repository aus

MonoSpecs verwaltetes Projekt:

• OpenSpec liest monospecs.yaml Konfiguration
• Nach Sub-Repository verfolgte Änderungen
• Spezifikationen werden automatisch auf korrekte Ziele festgelegt

Archivverhalten

Wann commit_when_archive: true:

• Spezifikationen werden automatisch in das Haupt-Repository übertragen
• Der Code der Unterrepositorys wird nicht festgeschrieben (bleibt separat)
• Vereinfacht die Spezifikationsverwaltung – für Unterrepositorys sind keine manuellen Spezifikations-Commits erforderlich

Manuelle Sub-Repository-Commits

Unterrepositorys behalten eine unabhängige Versionskontrolle bei:

• Übertragen Sie tatsächliche Codeänderungen in ihre eigenen Repositorys
• Spezifikationen werden separat festgeschrieben (vom Haupt-Repository bei der Archivierung).

Best Practices

Repository-Benennungskonventionen

• Verwenden Sie Kebab-Case (Kleinbuchstaben und Bindestriche) für Repository-Pfade
• Verwenden Sie einfache, beschreibende Anzeigenamen auf Chinesisch
• Verwenden Sie relevante Emojis als Symbole

Richtlinien für Anzeigenamen

• Halten Sie es prägnant und beschreibend
• Verwenden Sie für ähnliche Repositorys eine einheitliche Benennung
• Wählen Sie Symbole aus, die den Zweck des Repositorys darstellen

Konfigurationswartung

Konfiguration mit tatsächlichem Status synchronisieren

• Überprüfen Sie regelmäßig monospecs.yaml spiegelt die tatsächliche Repository-Struktur wider
• Aktualisieren oder entfernen Sie Einträge, wenn Repositorys hinzugefügt oder entfernt werden
• Testen Sie Änderungen, um die Gültigkeit der Konfiguration sicherzustellen

Versionskontrolle für die Konfiguration

• Verfolgen Sie Änderungen an Konfigurationsdateien mit Git
• Dokumentieren Sie die Gründe für größere Konfigurationsänderungen
• Markieren Sie Konfigurationsdateiversionen für ein einfaches Rollback

Fehlerbehebung

Konfigurationsdatei nicht gefunden

Wenn die monospecs.yaml Datei wurde nicht im Projektstammverzeichnis gefunden:

1. Überprüfen Sie, ob die Datei am richtigen Speicherort vorhanden ist
2. Stellen Sie sicher, dass Sie sich im richtigen Arbeitsverzeichnis befinden
3. Überprüfen Sie den Namen der Konfigurationsdatei auf Tippfehler

YAML-Syntaxfehler

Häufige Probleme mit der YAML-Syntax:

• Falsche Einrückung (Leerzeichen verwenden, keine Tabulatoren)
• Fehlende oder zusätzliche Anführungszeichen um Zeichenfolgen
• Ungültige Datentypen (Strings benötigen Anführungszeichen, Zahlen nicht)
• Fehlende Pflichtfelder (z.B path oder url)

Repository nicht erkannt

Wenn ein neu hinzugefügtes Repository nicht angezeigt wird:

1. Überprüfen Sie die path ist richtig in monospecs.yaml
2. Stellen Sie sicher, dass das Repository erfolgreich geklont wurde
3. Überprüfen Sie, ob das Repository am erwarteten Speicherort vorhanden ist

Klonfehler

Wenn das Klonen des Repositorys fehlschlägt:

1. Überprüfen Sie die Netzwerkverbindung
2. Überprüfen Sie, ob die Git-Repository-URL korrekt ist
3. Suchen Sie nach Authentifizierungsproblemen
4. Überprüfen Sie den Status des Docker-Containers
5. Überprüfen Sie die Verfügbarkeit von Speicherplatz

---

Ausführlichere Informationen finden Sie in der MonoSpecs-Dokumentation und im HagiCode-Repository nach Konfigurationsbeispielen.