MonoSpecs 다중 저장소 관리 가이드

개요

MonoSpecs는 HagiCode의 다중 저장소 관리 접근 방식입니다. 다음을 통해 하위 저장소를 추적하고 관리합니다. monospecs.yaml, 여러 개의 독립적인 저장소를 조정하기 위해 한 장소가 필요한 모든 프로젝트에 적합합니다.

핵심 개념

구성 파일

monospecs.yaml 전체 관리 솔루션의 핵심으로 다음을 정의합니다.

• 하위 저장소 목록 및 위치
• 각 저장소의 Git URL
• 표시 이름 및 아이콘
• OpenSpec과의 통합 동작

일반 저장소와의 차이점

특징	일반 저장소	MonoSpecs 관리 프로젝트
OpenSpec 위치	루트 디렉토리의 openspec/	기본 저장소 루트 디렉터리 openspec/
범위 변경	현재 저장소로 제한됨	여러 하위 저장소가 포함될 수 있습니다.
하위 저장소 순수성	코드와 혼합된 사양	기본 저장소에 설정된 사양, 하위 저장소가 더 깨끗합니다.
아카이브 자동 커밋	수동 사양 커밋 필요	commit_when_archive: true 자동으로 사양을 기본 저장소에 커밋합니다.

Monospec을 사용하는 이유는 무엇입니까?

• 통합 관리: 하나의 구성 파일로 모든 하위 저장소를 관리합니다.
• 자동화 지원: 스크립트 및 도구에 대한 저장소 메타데이터 제공
• AI 친화성: 구조화된 구성은 AI 에이전트가 저장소 관계를 이해하는 데 도움이 됩니다.
• OpenSpec 통합: 변경 관리 워크플로와의 원활한 통합
• 클리너 하위 저장소: 사양은 기본 저장소에 보관되며 하위 저장소에는 실제 코드만 포함됩니다.

적용 가능한 시나리오

다음과 같은 시나리오에서는 MonoSpecs를 먼저 사용하십시오.

1. 다중 저장소 공동 개발 프로젝트가 여러 개의 독립 저장소로 분할되는 경우:

• 프론트엔드 애플리케이션, 백엔드 서비스, 데스크톱 앱이 별도로 개발됨
• 저장소 전반에 걸쳐 버전과 종속성을 조정해야 합니다.
• 메인 코드와 분리된 문서 및 도우미 프로젝트

2. 보조 프로젝트 관리 MonoSpecs를 사용하여 다음을 관리하세요.

• 문서화 프로젝트
• 공식 홈페이지
• 도구 및 스크립트 빌드
• 각 저장소는 자체 버전 제어를 유지합니다.

3. 교차 저장소 기능 개발 여러 저장소에 걸쳐 변경이 필요한 기능:

• 리포지토리의 변경 사항을 추적해야 합니다.
• 대상 저장소를 수정하기 위해 자동으로 사양을 커밋합니다.
• 버전 업데이트 및 종속성 조정

빠른 시작

초기화

모노스펙 초기화를 완료하려면 다음 단계를 따르세요.

1. 빈 git 저장소 생성

빈 만들기 git 기본 저장소의 폴더(참고: 이 폴더는 git, 아니 repos/ - 이것은 모노스펙 규칙입니다):

mkdir git
cd git
git init
cd ..

2. 모노스펙 파일 구성

생성 monospecs.yaml 기본 저장소 루트 디렉터리의 구성 파일:

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

구성 항목:

구성 항목	유형	필수	설명
version	문자열	예	구성 파일 버전
commit_when_archive	부울	아니요	아카이브 시 사양을 자동 커밋할지 여부(하위 저장소 코드를 커밋하지 않음)
repositories	배열	예	저장소 구성 목록
repositories[].path	문자열	예	저장소 경로(프로젝트 루트 기준)
repositories[].url	문자열	예	힘내 저장소 URL
repositories[].displayName	문자열	아니요	저장소 표시 이름
repositories[].icon	문자열	아니요	저장소 아이콘(이모지)

기본 저장소에 하위 저장소 추가

모든 하위 저장소를 repos/ 디렉토리. 하위 저장소 콘텐츠 추적을 방지하려면 이 디렉터리를 기본 저장소의 Git 버전 제어에서 제외해야 합니다.

# Exclude all sub-repositories
repos/

3. HagiCode에 상위 저장소 추가

HagiCode 데스크톱 애플리케이션을 사용하는 경우 앱을 열고 기본 저장소를 프로젝트로 추가하세요. 홈 화면에서 “프로젝트 추가” 또는 ”+” 버튼을 클릭하고 기본 저장소 폴더를 선택하면 모든 하위 저장소와 해당 상태 정보가 표시됩니다.

4. 하위 저장소 복제

사용 monospecs.yaml 구성된 모든 하위 저장소를 복제하는 구성 repos/ 디렉토리:

그러면 구성 파일에 지정된 URL을 기반으로 모든 하위 저장소가 복제됩니다.

구성 파일 구조

루트 수준 구성

version: "1.0"
commit_when_archive: true

repositories:
  # ... repository configurations

저장소 수준 구성

각 하위 저장소에는 다음이 포함될 수 있습니다.

• OpenSpec 변경 폴더(openspec/)
• 독립 .git/ 디렉토리
• 선택사항 AGENTS.md AI 에이전트 구성용

저장소 관리 작업

새 저장소 추가

새로운 하위 저장소를 추가할 때 monospecs.yaml repositories 배열:

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

리포지토리 구성 업데이트

저장소 URL 또는 메타데이터가 변경되는 경우:

1. 편집 monospecs.yaml 해당 항목을 업데이트하려면
2. YAML 구문이 올바른지 확인하세요.
3. 변경 사항을 동기화하는 경우 로컬 저장소 구성을 수동으로 업데이트하세요.

AI 에이전트 구성 지원

AGENTS.md

는 AGENTS.md 파일은 AI Agent에 대한 저장소별 지침을 제공합니다.

기술 스택 정보

• 프레임워크 및 빌드 도구
• 코드 규칙 및 명명 방법
• 버전 관리 및 배포 구성

프로젝트별 동작

• 구성 확장 및 특별 요구 사항
• OpenSpec 통합 패턴
• 저장소 간 조정 요구 사항

AI 혜택

사용 AGENTS.md AI 에이전트는 다음을 수행할 수 있습니다.

• 저장소 관계 및 종속성 이해
• 여러 저장소에 걸쳐 코드 생성 및 리팩터링
• 버전 제어 및 구성의 일관성 유지

OpenSpec 통합

MonoSpecs가 OpenSpec과 함께 작동하는 방식

모노스펙 관리 프로젝트를 관리하든 일반 저장소를 관리하든 HagiCode의 OpenSpec 워크플로를 사용할 수 있습니다.

일반 저장소:

• 루트의 OpenSpec openspec/ 디렉토리
• 변경사항은 현재 저장소에만 영향을 미칩니다.

MonoSpecs 관리 프로젝트:

• OpenSpec 읽기 monospecs.yaml 구성
• 하위 저장소로 추적되는 변경 사항
• 사양은 올바른 대상에 자동으로 커밋됩니다.

아카이브 동작

언제 commit_when_archive: true:

• 사양은 기본 저장소에 자동으로 커밋됩니다.
• 하위 저장소의 코드는 커밋되지 않습니다(별도 유지)
• 사양 관리 단순화 - 하위 저장소에 대한 수동 사양 커밋이 필요하지 않습니다.

수동 하위 저장소 커밋

하위 저장소는 독립적인 버전 제어를 유지합니다.

• 실제 코드 변경 사항을 자체 저장소에 커밋
• 사양은 별도로 커밋됩니다(보관 시 기본 저장소에서).

모범 사례

저장소 명명 규칙

• 저장소 경로에 kebab-case(소문자 및 하이픈)를 사용하십시오.
• 중국어로 간단하고 설명이 포함된 표시 이름을 사용하세요.
• 관련 이모티콘을 아이콘으로 사용

표시 이름 지침

• 간결하고 설명적으로 작성하세요.
• 유사한 저장소 전체에서 일관된 이름 지정 사용
• 저장소의 목적을 나타내는 아이콘을 선택하세요.

구성 유지 관리

실제 상태와 구성 동기화

• 정기적으로 확인 monospecs.yaml 실제 저장소 구조를 반영합니다.
• 저장소가 추가되거나 제거될 때 항목 업데이트 또는 제거
• 구성 유효성을 확인하기 위해 변경 사항을 테스트합니다.

구성을 위한 버전 제어

• git을 사용하여 구성 파일 변경 사항 추적
• 주요 구성 변경에 대한 이유를 문서화하세요.
• 간편한 롤백을 위해 구성 파일 버전에 태그 지정

문제 해결

구성 파일을 찾을 수 없습니다

만약 monospecs.yaml 프로젝트 루트에서 파일을 찾을 수 없습니다:

1. 파일이 올바른 위치에 있는지 확인하십시오.
2. 올바른 작업 디렉터리에 있는지 확인하세요.
3. 구성 파일 이름에 오타가 있는지 확인하세요.

YAML 구문 오류

일반적인 YAML 구문 문제:

• 잘못된 들여쓰기(탭이 아닌 공백 사용)
• 문자열 주위에 따옴표가 없거나 추가로 있음
• 잘못된 데이터 유형(문자열에는 따옴표가 필요하고 숫자에는 따옴표가 필요하지 않음)
• 필수 입력란이 누락되었습니다(예: path 또는 url)

저장소가 감지되지 않음

새로 추가된 저장소가 표시되지 않는 경우:

1. 확인해보세요 path 에서 정확하다 monospecs.yaml
2. 저장소가 성공적으로 복제되었는지 확인
3. 예상 위치에 저장소가 있는지 확인하십시오.

클론 실패

저장소 복제가 실패하는 경우:

1. 네트워크 연결 확인
2. Git 저장소 URL이 올바른지 확인하세요.
3. 인증 문제 확인
4. Docker 컨테이너 상태 검토
5. 디스크 공간 가용성 확인

---

자세한 내용은 monospecs 문서를 참조하고 HagiCode 저장소에서 구성 예를 확인하세요.