gui-gitea-operation/guide-repository-naming.md

실용적 Repository 명명 규칙 가이드

본 가이드는 연구 조직의 디지털 자산을 체계적으로 관리하기 위한 Repository 명명 규칙을 정의합니다. 프로젝트 성격에 따라 **모노레포(Monorepo)**와 독립 Repository로 나누어 설명합니다.

---

1. 핵심 원칙

모든 Repository는 다음 세 가지 공통 원칙을 따릅니다.

1. 형식: 소문자와 하이픈(-)만 사용합니다. (예: my-project)
2. 언어: 글로벌 협업을 위해 영문으로 작성합니다.
3. 명확성: 이름만으로 목적을 쉽게 파악할 수 있도록 명확하고 직관적으로 작성합니다.

---

2. 모노레포 vs. 독립 Repository

새로운 작업을 시작하기 전, 아래 표를 참고하여 프로젝트에 가장 적합한 Repository 구조를 선택하세요.

구분	모노레포 (Monorepo)	독립 Repository
핵심 개념	하나의 큰 프로젝트에 속한 모든 코드를 단일 Repository에서 관리	각 Repository가 명확하고 독립적인 목적을 가짐
이름 규칙	프로젝트명 (접두사/접미사 없음)	xxx-핵심주제 (3글자 접두사 기반)
사용 시점	웹, API, 문서 등 여러 컴포넌트가 긴밀하게 연결된 단일 제품/프로젝트	조직 공용 도구, 특정 목적의 분석, 논문, 가이드, 템플릿 등
장점	코드 재사용 용이, 일관된 버전 관리, 리팩토링 편리	명확한 소유권, 독립적인 빌드/배포, 가볍고 빠른 클론 속도
예시	research-portal	gui-git-workflow, anl-user-retention-2024, tpl-python-service

---

3. 독립 Repository 명명 규칙

독립 Repository는 xxx-핵심주제 구조를 따릅니다. 이 규칙은 Repository의 성격을 명확히 하고 검색을 용이하게 합니다.

접두사 요약

접두사 (Prefix)	의미 (Meaning)	사용 사례 (Use Case)
tpl-	Template	새로운 프로젝트를 시작하기 위한 표준 구조/코드
anl-	Analysis	특정 시점의 데이터 분석 결과 및 코드
res-	Research	독립적인 연구 코드
ppr-	Paper	논문 재현을 위한 코드
tst-	Test	신기술, 라이브러리의 독립적 테스트
poc-	Proof of Concept	특정 기술에 대한 개념 검증
tol-	Tool	조직 전반에서 사용하는 공용 개발/운영 도구
inf-	Infrastructure	공용 인프라 관리 코드 (IaC)
doc-	Documentation	조직 전체의 공식 기술/정책 문서
gui-	Guide	특정 절차나 워크플로우에 대한 가이드
lib-	Library	여러 프로젝트에서 공용으로 사용하는 라이브러리
dat-	Data	조직에서 관리하는 공용 데이터셋

접두사별 상세 가이드

템플릿 (tpl-)

새로운 프로젝트의 보일러플레이트로 사용될 표준 구조 및 코드 템플릿입니다.

• 구조: tpl-{기술스택-또는-프로젝트유형}
• 예시:
  • tpl-python-service: Python 기반 마이크로서비스 프로젝트 템플릿
  • tpl-react-web-app: React 기반 웹 애플리케이션 표준 템플릿
  • tpl-monorepo-turborepo: Turborepo를 사용한 모노레포 기본 구조

📊 데이터 분석 (anl-)

일회성이거나 특정 시점의 데이터 분석 결과 및 코드를 저장합니다.

• 구조: anl-{분석내용}-{연도/분기}
• 예시:
  • anl-user-retention-2024-q2: 2024년 2분기 사용자 리텐션 분석
  • anl-market-research-gen-ai: 생성형 AI 시장 조사 분석

🔬 연구 및 논문 (res-, ppr-)

독립적인 순수 연구나 논문 재현을 위한 코드입니다.

• 구조: res-{연구주제} 또는 ppr-{논문제목-키워드}-{연도}
• 예시:
  • res-protein-folding-simulation: 단백질 폴딩 시뮬레이션 연구
  • ppr-attention-is-all-you-need-2017: "Attention Is All You Need" 논문 재현

🧪 테스트 및 개념 검증 (tst-, poc-)

신기술, 라이브러리를 독립적으로 테스트하거나 아이디어의 실현 가능성을 검증합니다.

• 구조: tst-{테스트대상} 또는 poc-{검증개념}
• 예시:
  • tst-pytorch-vs-tensorflow: PyTorch와 TensorFlow 성능 비교 테스트
  • poc-vector-db-search: 벡터 DB를 활용한 시맨틱 검색 PoC

🛠️ 도구 및 인프라 (tol-, inf-)

조직 전반에서 공용으로 사용되는 개발 도구나 인프라 관리 코드(IaC)입니다.

• 구조: tol-{도구목적} 또는 inf-{관리대상}
• 예시:
  • tol-data-anonymization: 데이터 익명화 처리 스크립트
  • inf-kubernetes-cluster: 공용 쿠버네티스 클러스터 설정 (Terraform)

📜 문서 및 가이드 (doc-, gui-)

특정 프로젝트에 종속되지 않는 조직의 공식 문서나 프로세스 가이드입니다.

• 구조: doc-{문서성격} 또는 gui-{가이드주제}
• 예시:
  • doc-api-style-guide: 조직의 API 스타일 가이드 문서
  • gui-onboarding-for-engineers: 신규 엔지니어 온보딩 가이드

📚 기타 (lib-, dat-)

• lib-{패키지명}: 여러 프로젝트에서 공용으로 사용하는 라이브러리
  • 예: lib-react-ui-kit
• dat-{데이터설명}: 조직에서 관리하는 공용 데이터셋
  • 예: dat-korean-sentiment-corpus

---

4. 모노레포 시작 가이드

모노레포 Repository 이름은 접두사 없이 프로젝트명을 그대로 사용합니다. (예: research-portal)

중요: 모노레포는 처음부터 만들지 마세요.

일관성을 유지하고 초기 설정 시간을 줄이기 위해, 모든 모노레포 프로젝트는 반드시 사전에 정의된 **템플릿 Repository(tpl-)**에서 시작해야 합니다.

시작 절차

1. GitHub에서 승인된 tpl-monorepo-* 템플릿 Repository로 이동합니다.
2. Use this template 버튼을 클릭하여 새로운 Repository를 생성합니다.
3. 새 Repository의 이름을 최종 프로젝트명으로 지정합니다. (예: research-portal)

예시: research-portal

• Repository 이름: research-portal
• 내부 폴더 구조 (템플릿 제공):

  research-portal/
  ├── .github/
  ├── apps/             # 애플리케이션 (웹, 문서 등)
  │   ├── web/
  │   └── docs-site/
  ├── packages/         # 공유 패키지 (UI 컴포넌트, 로거 등)
  │   ├── ui-kit/
  │   └── logger/
  └── README.md