# 실용적 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 기반 웹 애플리케이션 표준 템플릿

#### 📊 데이터 분석 (`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.  **`gui-gitea-operation` 저장소**의 `Issues` 탭에서 새로운 이슈를 생성합니다.
2.  **제목**은 `tpl-{템플릿 이름}`과 같이 제안하는 템플릿의 이름을 명시합니다.
3.  **본문**에는 템플릿의 필요성, 기대 효과, 포함될 기술 스택 및 디렉토리 구조 등을 상세히 기입합니다.
4.  이슈에 **`Propose new gitea template` 레이블**을 추가하여 제안을 제출합니다.

담당자는 제안된 내용을 검토하여 템플릿 생성 여부를 결정합니다.

### 시작 절차

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

#### 예시: `research-portal`
- **Repository 이름**: `research-portal`
- **내부 폴더 구조 (템플릿 제공)**:
  ```plaintext
  research-portal/
  ├── .github/
  ├── apps/             # 애플리케이션 (웹, 문서 등)
  │   ├── web/
  │   └── docs-site/
  ├── packages/         # 공유 패키지 (UI 컴포넌트, 로거 등)
  │   ├── ui-kit/
  │   └── logger/
  └── README.md
  ```