Guia de gerenciamento de múltiplos repositórios MonoSpecs

Visão geral

MonoSpecs é a abordagem de gerenciamento de vários repositórios do HagiCode. Ele rastreia e gerencia sub-repositórios por meio de monospecs.yaml, e funciona para qualquer projeto que precise de um local para coordenar vários repositórios independentes.

Conceitos Básicos

Arquivo de configuração

monospecs.yaml é o núcleo de toda a solução de gestão, definindo:

• Lista e localização de sub-repositórios
• URL Git para cada repositório
• Nome de exibição e ícone
• Comportamento de integração com OpenSpec

Diferenças dos repositórios regulares

Recurso	Repositório Regular	Projeto gerenciado por monospecs
Localização OpenSpec	Diretório raiz openspec/	Diretório raiz do repositório principal openspec/
Alterar escopo	Limitado ao repositório atual	Pode envolver vários sub-repositórios
Pureza do sub-repositório	Especificações misturadas com código	Especificações estabelecidas no repositório principal, sub-repositórios são mais limpos
Arquivar confirmação automática	Precisa de commits manuais de especificações	commit_when_archive: true compromete automaticamente as especificações no repositório principal

Por que usar monospecs?

• Gerenciamento unificado: gerencie todos os subrepositórios em um arquivo de configuração
• Suporte de automação: fornece metadados de repositório para scripts e ferramentas
• Otimização para IA: a configuração estruturada ajuda o agente de IA a entender os relacionamentos dos repositórios
• Integração OpenSpec: integração perfeita com o fluxo de trabalho de gerenciamento de mudanças
• Sub-repositórios mais limpos: as especificações são mantidas no repositório principal, os sub-repositórios contêm apenas o código real

Cenários Aplicáveis

Use MonoSpecs primeiro em cenários como estes:

1. Desenvolvimento Colaborativo Multi-Repositório Quando um projeto é dividido em vários repositórios independentes:

• Aplicativo front-end, serviço back-end e aplicativo de desktop desenvolvidos separadamente
• Necessidade de coordenar versões e dependências entre repositórios
• Documentação e projetos auxiliares separados do código principal

2. Gerenciamento Auxiliar de Projetos Use MonoSpecs para gerenciar:

• Projeto de documentação
• Site oficial
• Crie ferramentas e scripts
• Cada repositório mantém seu próprio controle de versão

3. Desenvolvimento de recursos entre repositórios Um recurso que requer alterações em vários repositórios:

• Precisa rastrear alterações em quais repositórios
• Confirmar especificações automaticamente para corrigir o repositório de destino
• Coordenar atualizações e dependências de versão

Início rápido

Inicialização

Siga estas etapas para concluir a inicialização do monospecs:

1. Crie um repositório git vazio

Crie um vazio git pasta em seu repositório principal (nota: este é git, não repos/ - esta é a convenção monospecs):

mkdir git
cd git
git init
cd ..

2. Configurar arquivo monospecs

Crie o monospecs.yaml arquivo de configuração no diretório raiz do repositório principal:

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: "⚙️"

Itens de configuração:

Item de configuração	Tipo	Obrigatório	Descrição
version	corda	Sim	Versão do arquivo de configuração
commit_when_archive	booleano	Não	Se deve confirmar automaticamente as especificações ao arquivar (não confirmar o código do sub-repo)
repositories	matriz	Sim	Lista de configuração do repositório
repositories[].path	corda	Sim	Caminho do repositório (relativo à raiz do projeto)
repositories[].url	corda	Sim	URL do repositório Git
repositories[].displayName	corda	Não	Nome de exibição do repositório
repositories[].icon	corda	Não	Ícone do repositório (emoji)

Adicionar sub-repositórios ao repositório principal

Adicione todos os sub-repositórios ao repos/ diretório. Este diretório deve ser excluído do controle de versão Git do repositório principal para evitar o rastreamento do conteúdo do sub-repositório:

# Exclude all sub-repositories
repos/

3. Adicionar repositório pai ao HagiCode

Se você usa o aplicativo de desktop HagiCode, abra o aplicativo e adicione seu repositório principal como um projeto. Clique no botão “Adicionar Projeto” ou “+” na tela inicial, selecione a pasta do repositório principal e você verá todos os sub-repositórios e suas informações de status.

4. Clonar sub-repositórios

Use o monospecs.yaml configuração para clonar todos os sub-repositórios configurados para o repos/ diretório:

Isso clonará todos os subrepositórios com base nas URLs especificadas no arquivo de configuração.

Estrutura do arquivo de configuração

Configuração de nível raiz

version: "1.0"
commit_when_archive: true

repositories:
  # ... repository configurations

Configuração em nível de repositório

Cada sub-repositório pode ter:

• Pasta de alteração do OpenSpec (openspec/)
• Independente .git/ diretório
• Opcional AGENTS.md para configuração do AI Agent

Operações de gerenciamento de repositório

Adicionar novo repositório

Ao adicionar um novo sub-repositório ao monospecs.yaml repositories matriz:

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

Atualizar configuração do repositório

Quando os URLs ou metadados do repositório mudam:

1. Editar monospecs.yaml para atualizar as entradas correspondentes
2. Verifique se a sintaxe YAML está correta
3. Se a sincronização for alterada, atualize manualmente a configuração do repositório local

Suporte à configuração do agente AI

AGENTES.md

O AGENTS.md fornece orientação específica do repositório para o agente de IA:

Informações técnicas da pilha

• Ferramentas de estrutura e construção
• Convenções de código e práticas de nomenclatura
• Gerenciamento de versão e configuração de implantação

Comportamentos Específicos do Projeto

• Extensões de configuração e requisitos especiais
• Padrões de integração OpenSpec
• Necessidades de coordenação entre repositórios

Benefícios de IA

Usando AGENTS.md permite que o Agente de IA:

• Entenda os relacionamentos e dependências do repositório
• Gere código e refatore em vários repositórios
• Mantenha a consistência no controle de versão e nas configurações

Integração OpenSpec

Como funciona o MonoSpecs com o OpenSpec

Seja gerenciando um projeto gerenciado por monospecs ou um repositório regular, você pode usar o fluxo de trabalho OpenSpec do HagiCode:

Repositório regular:

• OpenSpec na raiz openspec/ diretório
• As alterações afetam apenas o repositório atual

Projeto gerenciado por monospecs:

• Leituras OpenSpec monospecs.yaml configuração
• Mudanças rastreadas por subrepositório
• Especificações automaticamente comprometidas com alvos corretos

Comportamento de arquivamento

Quando commit_when_archive: true:

• As especificações são automaticamente confirmadas no repositório principal
• O código dos sub-repositórios não foi confirmado (permanece separado)
• Simplifica o gerenciamento de especificações - não são necessários commits manuais de especificações para sub-repositórios

Confirmações manuais de sub-repositório

Os sub-repositórios mantêm controle de versão independente:

• Confirmar alterações reais de código em seus próprios repositórios
• As especificações são confirmadas separadamente (do repositório principal durante o arquivamento)

Melhores práticas

Convenções de nomenclatura de repositório

• Use kebab-case (letras minúsculas e hífens) para caminhos de repositório
• Use nomes de exibição simples e descritivos em chinês
• Use emojis relevantes como ícones

Diretrizes para nomes de exibição

• Seja conciso e descritivo
• Use nomenclatura consistente em repositórios semelhantes
• Selecione ícones que representem a finalidade do repositório

Manutenção de configuração

Configuração de sincronização com status real

• Verifique regularmente monospecs.yaml reflete a estrutura real do repositório
• Atualizar ou remover entradas quando repositórios forem adicionados ou removidos
• Teste as alterações para garantir a validade da configuração

Controle de versão para configuração

• Rastreie alterações no arquivo de configuração com git
• Documente os motivos das principais alterações de configuração
• Identifique versões do arquivo de configuração para facilitar a reversão

Solução de problemas

Arquivo de configuração não encontrado

Se o monospecs.yaml arquivo não foi encontrado na raiz do projeto:

1. Verifique se o arquivo existe no local correto
2. Verifique se você está no diretório de trabalho correto
3. Verifique se há erros de digitação no nome do arquivo de configuração

Erros de sintaxe YAML

Problemas comuns de sintaxe YAML:

• Recuo incorreto (use espaços, não tabulações)
• Aspas ausentes ou extras em torno de strings
• Tipos de dados inválidos (strings precisam de aspas, números não)
• Campos obrigatórios ausentes (como path ou url)

Repositório não detectado

Se um repositório recém-adicionado não estiver aparecendo:

1. Verifique o path está correto em monospecs.yaml
2. Verifique se o repositório foi clonado com sucesso
3. Verifique se o repositório existe no local esperado

Falhas na clonagem

Se a clonagem do repositório falhar:

1. Verifique a conexão de rede
2. Verifique se o URL do repositório Git está correto
3. Verifique se há problemas de autenticação
4. Revise o status do contêiner Docker
5. Verifique a disponibilidade de espaço em disco

---

Para informações mais detalhadas, consulte a documentação monospecs e verifique o repositório HagiCode para exemplos de configuração.