Paul.Kim/gui-gitea-operation
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: Git 브랜치 및 커밋 메시지 작성 가이드 추가

Browse Source
This commit is contained in:
Paul.Kim
2025-07-14 17:09:01 +09:00
parent 79fe2476a2
commit 041771c6d6
15 changed files with 1124 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
.gitmessage Normal file
View File

@ -0,0 +1,32 @@
<타입>: <설명> (50자 이내)
타입과 설명은 콜론(:)으로 구분하고, 한 칸 띄웁니다.
예: feat: add user authentication system
본문 (선택 사항):
제목으로 표현하기 어려운 상세한 변경 내용을 72자 단위로 줄바꿈하여 작성합니다.
# "무엇을", "왜" 변경했는지 설명합니다.
바닥글 (선택 사항):
Breaking Change나 Closes, See also 등 특정 이슈를 참조할 때 작성합니다.
예: Closes: #123
예: BREAKING CHANGE: User.name 필드가 User.fullName으로 변경되었습니다.
# --- 커밋 타입 목록 ---
# feat: 새로운 기능 추가
# fix: 버그 수정
# docs: 문서 수정
# style: 코드 포맷팅, 세미콜론 누락 등 (기능 변경 없음)
# refactor: 코드 리팩토링
# test: 테스트 코드 추가/수정
# chore: 빌드 프로세스, 패키지 매니저 설정 등
#
# --- 연구개발 특화 타입 ---
# experiment: 실험적인 기능 또는 아이디어 구현
# research: 연구 관련 자료, 논문, 코드 추가
# data: 데이터셋 추가/수정, 전처리 스크립트 변경
# model: 머신러닝/AI 모델 구조 변경
# config: 설정 파일 추가 또는 변경
# --------------------

68
README.md
View File

@ -0,0 +1,68 @@
# Gitea 운영 및 개발 워크플로우 가이드
`gui-gitea-operation` 저장소는 우리 조직의 Gitea를 활용한 프로젝트 관리, 개발 워크플로우, 코드 작성 표준에 대한 모든 가이드를 중앙에서 관리합니다. 일관성 있고 효율적인 개발 문화를 정착시키는 것을 목표로 합니다.
---
### 1. 문서 개요 (Documentation Overview)
- **문서의 목적 (Purpose)**: 이 저장소는 조직의 모든 구성원이 따라야 할 표준화된 개발 및 운영 절차를 안내하는 공식 문서입니다. Gitea를 중심으로 저장소 생성부터 코드 작성, 배포에 이르는 전 과정을 다룹니다.
- **대상 독자 (Target Audience)**: 조직에 소속된 모든 개발자, 연구원, 엔지니어 및 프로젝트 관리자.
---
### 2. 목차: 주요 가이드 링크 (Table of Contents: Key Guides)
이 저장소의 핵심 가이드 목록입니다. 필요한 내용을 빠르게 찾아보세요.
#### 🚀 **시작하기: 기본 원칙**
- **[Repository 명명 규칙](./guide-repository-naming.md)**: 프로젝트 성격에 맞는 저장소 이름을 만드는 방법을 안내합니다.
- **[Git 커밋 메시지 컨벤션](./guide-commit-convention.md)**: Conventional Commits 기반의 표준 커밋 메시지 작성법을 설명합니다.
- **[Git 브랜치 전략](./guide-branch-convention.md)**: 개인 작업부터 팀 협업, AI 기반 병렬 개발까지 상황별 브랜치 전략을 제시합니다.
- (해당 가이드는 현재 디벨롭 중이며 추후 템플릿 레포지토리 개발 후 더 변경 될 수 있습니다.)
#### 📖 **README 작성 가이드**
- **[공통 가이드](./guide-readme/common.md)**: 모든 README에 포함되어야 할 필수 구성 요소를 안내합니다.
- **유형별 상세 가이드**:
- [모노레포 (Monorepo)](./guide-readme/monorepo.md)
- [템플릿 (`tpl-*`)](./guide-readme/tpl.md)
- [데이터 분석 (`anl-*`)](./guide-readme/anl.md)
- [연구/논문 (`res-*`, `ppr-*`)](./guide-readme/research.md)
- [테스트/PoC (`tst-*`, `poc-*`)](./guide-readme/test-poc.md)
- [공용 도구/인프라 (`tol-*`, `inf-*`)](./guide-readme/tool-infra.md)
- [문서/가이드 (`doc-*`, `gui-*`)](./guide-readme/docs-guide.md)
- [라이브러리 (`lib-*`)](./guide-readme/library.md)
- [데이터셋 (`dat-*`)](./guide-readme/dataset.md)
#### 🛠️ **개발 도구 및 설정**
- **[Git 커밋 템플릿](./.gitmessage)**: 표준 커밋 메시지 작성을 돕는 템플릿입니다. (`git config commit.template .gitmessage` 명령어로 설정)
---
### 3. 문서 구조 (Repository Structure)
```plaintext
/
├── guide-readme/ # 각 Repository 유형별 README 작성 가이드 모음
├── guide-branch-convention.md
├── guide-commit-convention.md
├── guide-repository-naming.md
├── .gitmessage # Git 커밋 메시지 템플릿
└── README.md # 현재 보고 있는 이 문서
```
---
### 4. 문서 업데이트 및 기여 방법 (Contributing to the Docs)
이 가이드는 살아있는 문서입니다. 언제든지 내용 추가, 수정, 개선을 제안할 수 있습니다.
- **기여 절차**:
1. [브랜치 전략](./guide-branch-convention.md)에 따라 `docs/주제` 형식의 브랜치를 생성합니다.
2. 내용을 수정하거나 새로운 가이드 문서를 추가합니다.
3. [커밋 컨벤션](./guide-commit-convention.md)에 맞게 커밋 메시지를 작성합니다.
4. Pull Request(PR)를 생성하여 리뷰를 요청합니다.
- **수정 제안**: 오타 수정이나 내용 보강 등 모든 변경은 Pull Request를 통해 제안해주세요.
---
### 5. 검색 팁 (Search Tips)
Gitea의 검색 기능을 활용하면 원하는 정보를 쉽게 찾을 수 있습니다. 예를 들어, 이 저장소 내에서 '모노레포' 관련 내용을 찾고 싶다면, 검색창에 `monorepo`를 입력하여 검색 범위를 이 저장소로 한정하면 됩니다.

125
guide-branch-convention.md Normal file
View File

@ -0,0 +1,125 @@
# Git 브랜치 전략 가이드
## 1. 개요
본 문서는 프로젝트의 규모와 팀 구성에 따라 유연하게 적용할 수 있는 Git 브랜치 관리 전략을 정의합니다. 일관된 브랜치 전략은 코드의 안정성을 보장하고, 협업 효율성을 높이며, 배포 프로세스를 체계적으로 관리하는 데 필수적입니다.
이 가이드에서는 혼자 개발할 때의 단순한 모델부터 팀 단위 협업 전략, 그리고 AI 에이전트를 활용한 고급 병렬 개발 워크플로우까지 다룹니다.
## 2. 브랜치 전략의 핵심: 분리
브랜치를 사용하는 핵심 이유는 **독립적인 작업 공간을 확보**하는 것입니다. 메인 코드(주로 `main` 또는 `master` 브랜치)의 안정성을 해치지 않으면서 새로운 기능을 개발하거나, 버그를 수정하고, 다양한 아이디어를 실험할 수 있습니다.
---
## 3. 프로젝트 규모별 브랜치 전략
### 3.1. 혼자 작업할 때 (Solo-developer)
혼자 개발하더라도 브랜치를 사용하는 것은 매우 유용합니다. 복잡한 전략 대신, 간단한 규칙으로도 안정적인 코드 관리가 가능합니다.
- **주요 브랜치**:
- `main` (or `master`): 항상 배포 가능한 안정적인 상태를 유지하는 브랜치.
- `feature/<기능명>`: 새로운 기능 개발, 버그 수정 등 특정 작업을 위한 임시 브랜치.
- **워크플로우**:
1. `main` 브랜치에서 새로운 작업 브랜치를 생성합니다. (`git checkout -b feature/login-page`)
2. 해당 브랜치에서 기능을 개발하고 커밋합니다.
3. 작업이 완료되면 `main` 브랜치로 돌아와 작업 브랜치를 병합(merge)합니다. (`git merge feature/login-page`)
4. 불필요해진 작업 브랜치는 삭제합니다. (`git branch -d feature/login-page`)
- **장점**:
- 실험적인 기능을 `main`과 분리하여 안전하게 개발할 수 있습니다.
- 작업 단위별로 커밋 히스토리가 관리되어 추적이 용이합니다.
- 실수로 인한 문제를 `main` 브랜치에 직접 반영하는 것을 방지합니다.
### 3.2. 두 사람 이상 팀으로 작업할 때
팀 단위 협업에서는 충돌을 방지하고 코드 품질을 유지하기 위해 더 체계적인 브랜치 전략이 필요합니다. **Git Flow**나 **GitHub Flow**가 대표적입니다.
- **주요 브랜치**:
- `main` (or `master`): 최종 배포 버전의 소스 코드를 관리하는 브랜치.
- `develop`: 다음 버전 배포를 위해 개발된 기능들이 통합되는 브랜치.
- `feature/<기능명>`: `develop` 브랜치에서 파생되어 개별 기능 개발을 진행.
- `release/<버전>`: 배포를 준비하기 위해 `develop` 브랜치에서 파생. QA 및 버그 수정을 진행.
- `hotfix/<수정내용>`: `main` 브랜치에 발생한 긴급 버그를 수정하기 위해 파생.
- **워크플로우**:
1. 모든 기능 개발은 `develop` 브랜치에서 시작합니다.
2. 개발자는 `feature` 브랜치를 생성하여 독립적으로 작업합니다.
3. 개발 완료 후, `develop` 브랜치로 **Pull Request(PR)** 또는 **Merge Request(MR)**를 보냅니다.
4. **코드 리뷰**와 **자동화된 테스트(CI)**를 통과한 코드만 `develop` 브랜치에 병합됩니다.
5. 배포 시점이 되면 `develop` 브랜치의 코드를 `release` 브랜치로 옮겨 QA를 진행하고, 최종적으로 `main`과 `develop`에 병합합니다.
6. 배포된 `main` 브랜치에서 긴급한 버그 발생 시, `hotfix` 브랜치에서 수정 후 `main`과 `develop`에 즉시 반영합니다.
- **핵심 차이점**:
| 구분 | 혼자 작업할 때 | 팀 작업할 때 |
| :--- | :--- | :--- |
| **규칙** | 비교적 자유로움 | 명확한 네이밍, 병합 규칙 필수 |
| **병합** | 본인 판단 하에 직접 병합 | Pull Request와 코드 리뷰를 통한 병합 |
| **충돌** | 거의 발생하지 않음 | 빈번하며, 적극적인 소통과 관리 필요 |
---
## 4. AI 기반 병렬 개발 워크플로우 (고급)
LLM(거대 언어 모델) AI 에이전트의 비결정적 특성을 활용하여 여러 구현 방안을 동시에 탐색하고 최상의 결과물을 선택하는 고급 워크플로우입니다. **Git Worktrees**를 사용해 물리적으로 분리된 작업 디렉토리에서 여러 AI 세션을 동시에 실행하는 것이 핵심입니다.
### 4.1. Git Worktrees란?
하나의 Git 저장소에 대해 여러 개의 워킹 디렉토리(working tree)를 생성하는 기능입니다. 동일한 `.git` 디렉토리를 공유하면서 각 디렉토리에서는 다른 브랜치를 체크아웃하여 작업할 수 있어, 브랜치 전환 없이 여러 작업을 병렬로 수행할 수 있습니다.
### 4.2. 워크플로우 제안
1. **작업별 워크트리 생성**: 각 기능이나 실험마다 별도의 워크트리를 생성합니다.
```bash
# 'feature/A' 브랜치를 만들고 ../gui-gitea-operation-feature-A 디렉토리에 워크트리 생성
git worktree add ../gui-gitea-operation-feature-A -b feature/A
# 'feature/B' 브랜치를 만들고 ../gui-gitea-operation-feature-B 디렉토리에 워크트리 생성
git worktree add ../gui-gitea-operation-feature-B -b feature/B
```
2. **독립적인 AI 세션 실행**: 각 워크트리 디렉토리로 이동하여 독립적인 AI 코딩 세션을 실행합니다.
```bash
# A 작업용 터미널
cd ../gui-gitea-operation-feature-A && code . # 또는 claude, cursor 등 AI 에이전트 실행
# B 작업용 터미널
cd ../gui-gitea-operation-feature-B && code . # 또는 claude, cursor 등 AI 에이전트 실행
```
이제 각 AI 에이전트는 서로 영향을 주지 않고 지정된 브랜치에서 코드를 생성하고 수정합니다.
3. **결과 비교 및 선택**:
- 각 워크트리에서 작업이 완료되면 커밋 후 원격 저장소에 푸시합니다.
- 각 브랜치에 대해 Pull Request(PR)를 생성합니다.
- PR에서 코드 리뷰, CI 테스트, 성능 비교 등을 통해 가장 우수한 결과물을 선택합니다.
- 선택된 PR을 메인 개발 브랜치(`develop` 또는 `main`)에 병합합니다.
4. **정리**: 작업이 완료된 워크트리는 리소스를 절약하기 위해 제거합니다.
```bash
git worktree remove ../gui-gitea-operation-feature-A
git worktree remove ../gui-gitea-operation-feature-B
```
### 4.3. 병렬 워크플로우 최적화 팁
| 항목 | 권장 사항 |
| :--- | :--- |
| **네이밍** | `feature/기능명`, `experiment/실험명` 등 목적을 명확히 하는 네이밍 규칙 사용 |
| **초기화** | 각 워크트리 진입 시 의존성 설치 등 환경 초기화 스크립트 실행 |
| **리소스 관리** | `git worktree list`로 현재 워크트리를 확인하고 불필요한 것은 즉시 제거 |
| **비교/선택** | PR의 CI 결과, 코드 커버리지, 성능 지표 등 객관적 데이터로 최종 결과물 선택 |
| **비용 관리** | AI 에이전트 사용 비용을 고려하여, 동시에 실행하는 워크트리 수를 2~3개로 제한 |
---
## 5. 결론
브랜치 전략은 "정답"이 있는 것이 아니라, 프로젝트의 상황에 맞춰 선택하는 것입니다.
- **혼자서는** `main` + `feature`의 단순한 모델로도 충분합니다.
- **팀에서는** `Git Flow`와 같이 역할이 명확히 구분된 체계적인 전략과 PR 기반의 협업 문화가 필수적입니다.
- **복잡한 문제 해결이나 R&D**에서는 `Git Worktrees`를 활용한 병렬 AI 개발이 생산성과 코드 품질을 극대화하는 강력한 무기가 될 수 있습니다.
상황에 맞는 전략을 선택하고 팀원 모두가 일관되게 규칙을 따르는 것이 성공적인 프로젝트 관리의 핵심입니다.

134
guide-commit-convention.md Normal file
View File

@ -0,0 +1,134 @@
# Git 커밋 메시지 컨벤션 가이드
## 1. 개요
본 문서는 효과적인 협업과 코드 품질 관리를 위해 **Conventional Commits**를 기반으로 한 Git 커밋 메시지 작성 규칙을 정의합니다. 일관된 커밋 히스토리는 프로젝트의 변경 사항을 쉽게 추적하고, 버전 관리를 자동화하며, 팀원 간의 소통을 원활하게 만듭니다.
특히 연구개발조직의 특성을 반영한 확장 타입을 포함하여 실용성을 높였습니다.
## 2. 커밋 메시지 구조
모든 커밋 메시지는 다음의 세 부분으로 구성됩니다.
```
<type>: <subject>
[optional body]
[optional footer]
```
| 요소 | 설명 | 필수 여부 |
| :--- | :--- | :--- |
| **type** | 커밋의 성격을 나타내는 타입 | **필수** |
| **subject** | 커밋에 대한 50자 이내의 간결한 요약 | **필수** |
| **body** | 변경 이유, 이전 동작과의 차이점 등 상세 설명 | 선택 |
| **footer** | 이슈 번호, Breaking Change 등 추가 정보 | 선택 |
---
## 3. 타입 (Type)
커밋의 성격을 나타내는 타입은 아래 목록 중에서 선택합니다.
### 주요 타입
| 타입 | 설명 |
| :--- | :--- |
| **feat** | 새로운 기능 추가 |
| **fix** | 버그 수정 |
| **docs** | 문서 수정 (README.md, API 문서 등) |
| **style**| 코드 포맷팅, 세미콜론 누락 등 기능 변경이 없는 스타일 수정 |
| **refactor** | 코드 리팩토링 (기능 변경 없이 내부 구조 개선) |
| **test** | 테스트 코드 추가, 수정, 삭제 |
| **chore** | 빌드 프로세스, 패키지 매니저 설정 등 기타 변경사항 |
### 연구개발 특화 타입
| 타입 | 설명 |
| :--- | :--- |
| **experiment** | 실험적인 기능 또는 아이디어 구현 |
| **research** | 연구 관련 자료, 논문, 코드 추가 |
| **data** | 데이터셋 추가/수정, 전처리 스크립트 변경 |
| **model** | 머신러닝/AI 모델 구조 변경, 가중치 파일 추가 |
| **config** | 설정 파일 추가 또는 변경 |
---
## 4. 작성 규칙
### 제목 (Subject)
- **명령형, 현재 시제**로 작성합니다. (예: `add`, `fix`, `change` not `added`, `fixed`, `changed`)
- **첫 글자는 소문자**로 시작합니다.
- 문장 끝에 **마침표(.)를 붙이지 않습니다.**
- **50자 이내**로 간결하게 작성합니다.
### 본문 (Body)
- **제목과 본문 사이에는 한 줄을 비워** 명확히 구분합니다.
- 본문이 필요한 경우, **"무엇을"** 그리고 **"왜"** 변경했는지 상세히 설명합니다.
- 각 줄은 **72자 이내**로 작성하여 가독성을 높입니다.
### 바닥글 (Footer)
- **본문과 바닥글 사이에는 한 줄을 비워** 구분합니다.
- **Breaking Change**가 있는 경우, `BREAKING CHANGE:`로 시작하는 문단에 변경점, 마이그레이션 방법 등을 설명합니다.
- **특정 이슈를 종료**할 때 `Closes #이슈번호` 형식으로 작성합니다.
---
## 5. 커밋 예시
### 예시 1: 간단한 기능 추가
```
feat: add user logout function
```
### 예시 2: 이슈 번호를 포함한 버그 수정
```
fix: resolve login failure with incorrect password
사용자가 잘못된 비밀번호를 입력했을 때 500 에러가 아닌
401 Unauthorized 에러를 반환하도록 수정합니다.
Closes #45
```
### 예시 3: Breaking Change를 포함한 리팩토링
```
refactor: simplify user data retrieval logic
기존의 복잡했던 사용자 정보 조회 로직을 단일 함수로 통합하여
유지보수성을 향상시키고 코드 중복을 제거합니다.
BREAKING CHANGE:
`/api/v1/user/info` 엔드포인트가 제거되었습니다.
이제부터 `/api/v2/users/{id}`를 사용해야 합니다.
```
### 예시 4: 연구개발 특화 타입 (모델)
```
model: increase transformer layers from 6 to 12
모델의 성능 향상을 위해 인코더와 디코더의 레이어 수를
6개에서 12개로 늘리고, 관련 하이퍼파라미터를 조정합니다.
```
---
## 6. 커밋 템플릿 적용하기
이 컨벤션을 쉽게 적용하기 위해 `.gitmessage` 파일을 Git 커밋 템플릿으로 등록할 수 있습니다.
아래 명령어를 터미널에 입력하여 Git 전역 설정에 템플릿을 등록하세요.
```bash
git config --global commit.template .gitmessage
```
이제 `git commit`을 실행하면, 커밋 메시지 에디터에 `.gitmessage`의 내용이 자동으로 나타나 일관된 커밋 메시지 작성을 돕습니다.

63
guide-readme/anl.md Normal file
View File

@ -0,0 +1,63 @@
# `anl-*` (데이터 분석) Repository README 작성 가이드
`anl-*` 접두사가 붙은 저장소는 특정 데이터셋에 대한 분석 과정과 결과를 기록하는 공간입니다. README의 목표는 분석의 재현성을 보장하고, 다른 사람이 분석의 맥락, 과정, 결론을 쉽게 이해할 수 있도록 만드는 것입니다.
---
### 1. 분석 개요 (Analysis Overview)
- **연구 질문 (Research Question)**: 이 분석을 통해 답하고자 하는 핵심 질문이 무엇인지 명확하게 제시합니다.
- **주요 결과 요약 (Executive Summary)**: 분석을 통해 얻은 핵심적인 인사이트나 결론을 2~3 문장으로 요약하여 서두에 배치합니다.
- **데이터 출처 (Data Source)**: 분석에 사용된 데이터가 어디에서 왔는지 출처를 밝히고, 데이터에 접근할 수 있는 링크를 제공합니다.
### 2. 환경 설정 (Setup)
- **목적**: 다른 분석가가 동일한 환경에서 코드를 실행하고 결과를 재현할 수 있도록 안내합니다.
- **필수 정보**:
- **의존성 설치**: `requirements.txt` 또는 `environment.yml` 파일을 제공하고, 설치 방법을 안내합니다.
```bash
# pip 사용 시
pip install -r requirements.txt
# Conda 사용 시
conda env create -f environment.yml
conda activate my-analysis-env
```
- **데이터 다운로드**: 원본 데이터를 다운로드하거나, 특정 디렉토리(`data/raw/`)에 위치시키는 방법을 설명합니다.
- **환경 변수**: API 키나 데이터베이스 접속 정보 등 민감한 정보를 `.env` 파일에 설정하는 방법을 안내합니다.
### 3. 분석 과정 (Analysis Workflow)
- **목적**: 데이터 전처리부터 모델링, 시각화에 이르는 전체 분석 단계를 순서대로 설명합니다.
- **단계별 설명**:
1. **데이터 전처리 (Data Preprocessing)**:
- 스크립트: `notebooks/01_data_cleaning.ipynb`
- 설명: 결측치 처리, 이상치 제거, 변수 파생 등 수행한 작업을 간략히 기술합니다.
2. **탐색적 데이터 분석 (EDA)**:
- 스크립트: `notebooks/02_exploratory_data_analysis.ipynb`
- 설명: 데이터의 분포, 변수 간 상관관계를 파악하기 위해 수행한 분석을 설명합니다.
3. **모델링 (Modeling)**:
- 스크립트: `notebooks/03_modeling.ipynb`
- 설명: 적용한 통계 모델이나 머신러닝 알고리즘을 설명하고, 선택 이유를 기술합니다.
### 4. 주요 결과 및 시각화 (Key Results & Visualizations)
- **목적**: 분석의 핵심 결과를 시각 자료와 함께 제시하여 직관적인 이해를 돕습니다.
- **팁**:
- `matplotlib`나 `seaborn`으로 생성된 주요 그래프(예: 상관관계 히트맵, 변수 중요도 플롯) 이미지를 README에 직접 삽입합니다.
- 각 시각화 자료에 대한 해석을 덧붙여, 그래프가 의미하는 바를 설명합니다.
- **예시**:
> 아래는 피처 A와 B의 관계를 나타낸 산점도입니다. 양의 상관관계가 뚜렷하게 나타났습니다.
>
> ![Scatter Plot](results/figures/scatter_plot_A_B.png)
### 5. 결과 재현 방법 (How to Reproduce)
- **목적**: 다른 사람이 저장소의 코드를 처음부터 끝까지 실행하여 동일한 결과를 얻는 방법을 안내합니다.
- **스크립트 실행 순서**:
```bash
# 1. 데이터 전처리 실행
python src/preprocess.py
# 2. 모델 학습 실행
python src/train_model.py
# 3. 결과 리포트 생성
# 혹은 Jupyter Notebook/Quarto를 실행하여 전체 분석을 재현
jupyter lab notebooks/
```

61
guide-readme/common.md Normal file
View File

@ -0,0 +1,61 @@
# 공통 README 구성 요소
모든 README는 다음 섹션을 포함해야 합니다. 이 가이드는 명확하고 일관된 문서 작성을 도와 신규 참여자도 프로젝트를 쉽게 이해하고 사용할 수 있도록 합니다.
---
### 1. 프로젝트 이름 (Project Name)
- **형식**: 대문자 `#` 헤딩 사용 (예: `# 내 멋진 프로젝트`)
- **내용**: 프로젝트의 공식 명칭을 간결하고 명확하게 표기합니다.
### 2. 한 줄 요약 (Introduction)
- **목적**: 프로젝트의 핵심 기능과 목적을 한 문장으로 요약합니다.
- **예시**: "이 프로젝트는 AI 모델의 학습 과정을 시각화하는 웹 기반 대시보드입니다."
### 3. 목차 (Table of Contents)
- **필요성**: 문서가 길어질 경우, 사용자가 원하는 정보로 빠르게 이동할 수 있도록 돕습니다. (선택 사항)
- **팁**: 마크다운 링크(`[섹션 이름](#섹션-이름)`)를 사용하여 각 섹션으로 이동하도록 만듭니다.
### 4. 설치 및 실행 (Installation & Setup)
- **필수 요소**:
- **선행 조건 (Prerequisites)**: 필요한 소프트웨어, 언어 버전, OS 환경 등을 명시합니다.
- **설치 명령어 (Installation)**: `pip install -r requirements.txt` 와 같이 정확한 명령어를 제공합니다.
- **환경 변수 (Environment Variables)**: `.env.example` 파일을 제공하고, 각 변수의 의미와 설정 방법을 안내합니다.
- **예시**:
```bash
# 1. 저장소 복제
git clone https://github.com/your/repository.git
cd repository
# 2. 의존성 설치
npm install
# 3. 환경변수 설정
cp .env.example .env
# .env 파일에 API 키 등 필요 정보를 입력합니다.
# 4. 실행
npm start
```
### 5. 사용법 (Usage)
- **목적**: 주요 기능을 어떻게 사용하는지 구체적인 코드 예시와 함께 보여줍니다.
- **구성**:
- **기본 사용법**: 가장 일반적인 사용 사례를 보여주는 코드 스니펫
- **고급 사용법**: 특정 옵션이나 심화 기능을 활용하는 예시
- **팁**: 코드 블록에 언어(e.g., `python`, `javascript`)를 명시하여 가독성을 높입니다.
### 6. 기여 안내 (Contributing)
- **핵심 내용**:
- **브랜치 전략**: `feature/기능이름` 과 같은 브랜치 명명 규칙을 안내합니다.
- **Pull Request (PR) 가이드**: PR 템플릿 사용법, 리뷰 프로세스를 설명합니다.
- **코드 스타일**: Prettier, ESLint 등 코드 포맷팅 및 린팅 규칙 링크를 제공합니다.
- **개발 환경**: 기여에 필요한 개발 환경 설정법을 별도로 안내합니다.
### 7. 라이선스 (License)
- **내용**: 프로젝트에 적용되는 라이선스(예: MIT, Apache 2.0)를 명시하고, `LICENSE` 파일 링크를 첨부합니다.
- **중요성**: 사용자와 기여자가 법적 권리와 의무를 명확히 인지하도록 합니다.
### 8. 유지보수자 (Maintainers or Contact)
- **정보**: 프로젝트의 주요 담당자나 팀의 연락처(이메일, 슬랙 채널 등)를 기재합니다.
- **목적**: 사용자가 질문이나 제안이 있을 때 누구에게 연락해야 하는지 안내합니다.

67
guide-readme/dataset.md Normal file
View File

@ -0,0 +1,67 @@
# `dat-*` (데이터셋) Repository README 작성 가이드
`dat-*` 접두사를 사용하는 저장소는 특정 데이터셋 자체를 저장하거나, 데이터셋에 접근하고 이해하는 데 필요한 모든 정보를 관리합니다. README의 핵심 목표는 데이터의 출처, 구조, 내용을 명확히 설명하여 사용자가 데이터를 올바르게 해석하고 활용할 수 있도록 돕는 것입니다. `Datasheet for Datasets`의 개념을 차용하여 체계적으로 정보를 제공하는 것이 중요합니다.
---
### 1. 데이터셋 개요 (Dataset Overview)
- **데이터셋 이름**: "서울시 지하철 혼잡도 이력 데이터" 와 같이 데이터셋의 공식 명칭을 기재합니다.
- **한 줄 요약**: 이 데이터셋이 무엇에 대한 데이터인지 한 문장으로 설명합니다.
- 예시: "2022년 한 해 동안 서울시 모든 지하철역의 시간대별 평균 혼잡도 정보를 담고 있는 시계열 데이터셋입니다."
- **키워드**: `시계열`, `교통 데이터`, `서울`, `지하철 혼잡도` 등 데이터셋을 설명하는 주요 키워드를 나열합니다.
### 2. 데이터 출처 및 수집 방법 (Source and Collection)
- **데이터 원천 (Source)**: 데이터가 어디에서 비롯되었는지 원본 출처를 명확히 밝힙니다.
- 예시: "서울 열린데이터 광장 (data.seoul.go.kr)"
- 원본 데이터에 접근할 수 있는 URL을 반드시 포함해야 합니다.
- **수집 방법 (Collection Process)**:
- 데이터가 어떻게 수집되었는지 설명합니다. (예: "매일 자정, API를 통해 전날 데이터를 수집하여 CSV 파일로 저장하는 스크립트를 실행함.")
- 데이터 수집 기간(예: `2022-01-01` ~ `2022-12-31`), 수집 주기(예: `일별`) 등 시간적 범위를 명시합니다.
### 3. 데이터 구조 및 스키마 (Data Structure and Schema)
- **파일 목록 및 설명**: 데이터셋을 구성하는 파일과 폴더 구조를 설명합니다.
```plaintext
/
├── data/
│ ├── subway_congestion_2022.csv # 2022년 전체 데이터
│ └── station_info.csv # 지하철역 메타데이터
├── scripts/
│ └── download_data.py # 데이터 다운로드 스크립트
└── README.md
```
- **데이터 스키마 (칼럼 설명)**: 각 CSV 파일의 칼럼(열)이 무엇을 의미하는지 상세히 설명합니다. 표를 사용하는 것이 가장 효과적입니다.
**`subway_congestion_2022.csv`**
| 칼럼명 (Column) | 데이터 타입 (Type) | 설명 (Description) | 예시 (Example) |
|-----------------|--------------------|--------------------------------------------------|----------------------|
| `date` | `YYYY-MM-DD` | 데이터 수집 날짜 | `2022-05-15` |
| `station_code` | `String` | 지하철역 고유 코드 (`station_info.csv` 참조) | `S1001` |
| `hour` | `Integer` | 시간 (0-23) | `18` (오후 6시) |
| `congestion` | `Float` | 해당 시간의 평균 혼잡도 (0.0 ~ 1.0) | `0.85` |
### 4. 데이터 사용 예시 (Usage Example)
- **목적**: 사용자가 데이터를 로드하여 기본적인 분석을 수행하는 간단한 코드 스니펫을 제공합니다.
- **Python (Pandas) 예시**:
```python
import pandas as pd
# 데이터 불러오기
congestion_df = pd.read_csv('data/subway_congestion_2022.csv')
station_df = pd.read_csv('data/station_info.csv')
# 데이터 병합
df = pd.merge(congestion_df, station_df, on='station_code')
# 강남역의 월별 평균 혼잡도 계산
gangnam_congestion = df[df['station_name'] == '강남']
monthly_avg = gangnam_congestion.groupby(pd.to_datetime(df['date']).dt.month)['congestion'].mean()
print(monthly_avg)
```
### 5. 라이선스 및 사용 제약 (License and Constraints)
- **라이선스**: 데이터셋에 적용되는 라이선스를 명시합니다. (예: `CC-BY 4.0`)
- **사용 제약**:
- 데이터 사용 시 출처를 반드시 표기해야 하는지 등 사용 조건을 안내합니다.
- 개인정보 포함 여부, 상업적 이용 가능 여부 등 민감한 사항을 명확히 고지합니다.
- **면책 조항 (Disclaimer)**: 데이터의 정확성이나 완전성을 보증하지 않으며, 데이터 사용으로 발생하는 문제에 대해 책임지지 않는다는 점을 명시할 수 있습니다.

50
guide-readme/docs-guide.md Normal file
View File

@ -0,0 +1,50 @@
# `doc-*`, `gui-*` (문서/가이드) Repository README 작성 가이드
`doc-*` (document) 또는 `gui-*` (guide) 접두사를 사용하는 저장소는 특정 주제에 대한 지식, 정책, 절차 등을 체계적으로 관리하는 것을 목적으로 합니다. README는 이 문서 저장소의 '목차'이자 '안내 데스크' 역할을 수행해야 합니다. 사용자가 원하는 정보를 쉽고 빠르게 찾을 수 있도록 돕는 것이 가장 중요합니다.
---
### 1. 문서 개요 (Documentation Overview)
- **문서의 목적 (Purpose)**: 이 문서 저장소가 어떤 종류의 정보(예: 온보딩 가이드, 개발 표준, 아키텍처 결정 기록)를 다루는지 명확히 설명합니다.
- **대상 독자 (Target Audience)**: 이 문서를 주로 읽게 될 사람이 누구인지(예: 신규 입사자, 프론트엔드 개발자, 모든 엔지니어) 명시하여 내용의 깊이와 범위를 짐작할 수 있게 합니다.
### 2. 목차 또는 주요 문서 링크 (Table of Contents or Key Links)
- **가장 중요한 섹션**: 사용자가 원하는 정보로 바로 이동할 수 있도록, 잘 정리된 목차나 핵심 문서로의 링크 목록을 제공해야 합니다.
- **구성 방법**:
- **주제별 분류**: 관련된 문서들을 카테고리별로 묶어 제공합니다.
- **🚀 시작하기**
- [개발 환경 설정 가이드](./getting-started/setup-dev-env.md)
- [첫 번째 Pull Request 만들기](./getting-started/first-pr.md)
- **🎨 프론트엔드 가이드**
- [코딩 컨벤션](./frontend/coding-style.md)
- [상태 관리 전략](./frontend/state-management.md)
- **⚙️ 백엔드 가이드**
- [API 설계 원칙](./backend/api-design.md)
- [데이터베이스 마이그레이션 절차](./backend/db-migration.md)
- **상대 경로 사용**: 저장소 내 다른 문서로 연결할 때는 반드시 상대 경로(`.` 또는 `..`로 시작)를 사용하여 링크가 깨지지 않도록 합니다.
### 3. 문서 구조 (Repository Structure)
- **목적**: 문서가 어떤 기준으로 폴더에 정리되어 있는지 설명하여, 사용자가 원하는 정보가 어디에 있을지 예측할 수 있도록 돕습니다.
- **예시**:
```plaintext
/
├── getting-started/ # 신규 입사자 및 초기 설정
├── frontend/ # 프론트엔드 관련 규칙 및 가이드
├── backend/ # 백엔드 관련 규칙 및 가이드
├── adr/ # 아키텍처 결정 기록 (Architecture Decision Records)
└── assets/ # 문서에 사용되는 이미지 파일
```
### 4. 문서 업데이트 및 기여 방법 (Contributing to the Docs)
- **목적**: 문서의 내용을 최신으로 유지하기 위해, 누구나 쉽게 내용을 추가하거나 수정할 수 있는 방법을 안내합니다.
- **프로세스**:
- **수정 제안**: 오타 수정이나 내용 보강은 어떻게 제안하는지 설명합니다. (예: "Pull Request를 생성해주세요.")
- **새로운 문서 추가**: 새로운 가이드를 작성할 때 따라야 할 템플릿이나 절차를 안내합니다.
- **리뷰 프로세스**: 문서 변경 사항은 누가, 어떻게 리뷰하는지 설명합니다. (예: "프론트엔드 챕터 리더의 승인이 필요합니다.")
### 5. 검색 팁 (Search Tips)
- **목적**: 사용자가 GitHub의 내장 검색 기능을 효과적으로 활용하여 정보를 찾을 수 있도록 팁을 제공합니다.
- **예시**: "GitHub 검색창에 `repo:my-org/my-docs state management` 와 같이 검색하면 이 저장소 내에서 'state management'에 대한 내용을 쉽게 찾을 수 있습니다."
### 6. 목차 자동 생성 (Optional: Automated TOC)
- **도구 안내**: `markdown-toc` 같은 도구를 사용하여 목차를 자동으로 생성하고 업데이트하는 방법을 안내할 수 있습니다. 이는 문서 구조가 자주 변경될 때 유용합니다.

86
guide-readme/library.md Normal file
View File

@ -0,0 +1,86 @@
# `lib-*` (라이브러리) Repository README 작성 가이드
`lib-*` 접두사를 사용하는 저장소는 다른 애플리케이션에서 가져다 쓸 수 있는 재사용 가능한 코드 패키지(라이브러리)를 관리합니다. 좋은 라이브러리 README는 사용자가 최소한의 노력으로 라이브러리를 설치하고, 핵심 기능을 빠르게 활용할 수 있도록 돕는 '퀵스타트 가이드'와 'API 명세서'의 역할을 동시에 수행해야 합니다.
---
### 1. 라이브러리 소개 (Library Introduction)
- **한 줄 요약**: 이 라이브러리가 어떤 문제를 해결하는지, 어떤 기능을 제공하는지 한 문장으로 명확하게 설명합니다.
- 예시: "React 애플리케이션에서 복잡한 폼(Form) 상태를 쉽게 관리하고 유효성을 검사하는 경량 라이브러리입니다."
- **주요 특징 (Features)**: 라이브러리의 핵심적인 장점을 3~4가지 항목으로 강조합니다.
- 예시:
- 🚀 제로 의존성(Zero-dependency) 및 작은 번들 크기
- 🎨 손쉬운 커스텀 유효성 검사 규칙 추가
- 📦 TypeScript 기반의 완벽한 타입 지원
- hooking 기반의 직관적인 API
### 2. 설치 (Installation)
- **목적**: 사용자가 자신의 프로젝트에 라이브러리를 추가하는 방법을 안내합니다.
- **패키지 매니저별 명령어**: `npm`, `yarn`, `pnpm` 등 주요 패키지 매니저에 대한 설치 명령어를 모두 제공합니다.
```bash
# npm
npm install @my-org/react-form-validator
# yarn
yarn add @my-org/react-form-validator
# pnpm
pnpm add @my-org/react-form-validator
```
- **피어 의존성 (Peer Dependencies)**: 라이브러리가 정상적으로 동작하기 위해 반드시 필요한 다른 패키지(예: `react`, `react-dom`)가 있다면, 명확하게 명시하고 설치를 안내합니다.
### 3. 기본 사용법 (Basic Usage / Quick Start)
- **가장 중요한 섹션**: 라이브러리의 핵심 기능을 보여주는 최소한의 'Hello, World!' 예제 코드를 제공하여 사용자가 즉시 따라 해볼 수 있도록 합니다.
- **코드 예시**:
```jsx
import React from 'react';
import { useForm, validateEmail } from '@my-org/react-form-validator';
function MyForm() {
const { register, handleSubmit, errors } = useForm();
const onSubmit = (data) => {
console.log('Form data:', data);
};
return (
<form onSubmit={handleSubmit(onSubmit)}>
<input
{...register('email', { required: true, validate: validateEmail })}
placeholder="이메일"
/>
{errors.email && <p>올바른 이메일을 입력해주세요.</p>}
<button type="submit">제출</button>
</form>
);
}
```
### 4. API 참고 (API Reference)
- **목적**: 라이브러리가 제공하는 주요 함수, 컴포넌트, 훅(Hook) 등의 상세한 명세를 제공합니다.
- **구성**:
- **`useForm()` Hook**:
- **`register(name, options)`**:
- `name` (string, required): 입력 필드의 이름
- `options` (object): `required`, `minLength`, `validate` 등 유효성 검사 규칙
- **`handleSubmit(callback)`**:
- `callback` (function, required): 유효성 검사를 통과했을 때 폼 데이터를 인자로 받아 실행되는 함수
- **`errors` (object)**: 각 필드의 유효성 검사 실패 정보를 담고 있는 객체
- **팁**: 내용이 길어질 경우, 별도의 `API.md` 파일로 분리하고 README에서는 해당 파일로 링크를 거는 것이 좋습니다.
### 5. 고급 사용법 및 레시피 (Advanced Usage & Recipes)
- **목적**: 기본적인 사용법을 넘어, 실제 애플리케이션에서 마주할 수 있는 복잡한 시나리오에 대한 해결책을 제공합니다.
- **예시**:
- 비동기 유효성 검사 방법
- 동적 폼 필드 처리하기
- 외부 UI 라이브러리(예: `Material-UI`, `Ant Design`)와 통합하기
### 6. 버전 호환성 (Version Compatibility)
- **목적**: 라이브러리가 특정 버전의 프레임워크나 환경에서만 동작하는 경우, 이를 명확히 표기하여 사용자의 혼란을 방지합니다.
- **예시 (표 활용)**:
| 라이브러리 버전 | React 버전 호환성 |
|-----------------|---------------------|
| `2.x` | `^18.0.0` |
| `1.x` | `^16.8.0` OR `^17.0.0` |

58
guide-readme/monorepo.md Normal file
View File

@ -0,0 +1,58 @@
# 모노레포(Monorepo) README 작성 가이드
모노레포는 여러 프로젝트(애플리케이션, 패키지)를 단일 저장소에서 관리하므로, 전체 구조와 각 컴포넌트의 상호작용을 명확히 안내하는 것이 중요합니다. 루트 README는 프로젝트의 진입점 역할을 해야 합니다.
---
### 1. 전체 구조 개요 (Repository Structure)
- **목적**: 저장소의 폴더 구조를 시각적으로 보여주어 각 패키지와 애플리케이션의 위치를 빠르게 파악할 수 있도록 돕습니다.
- **예시**:
```plaintext
my-monorepo/
├── apps/
│ ├── web-app/ # 사용자용 웹 애플리케이션
│ └── admin-dashboard/ # 관리자용 대시보드
├── packages/
│ ├── ui-kit/ # 공통 UI 컴포넌트
│ └── data-models/ # 공유 데이터 모델
└── README.md
```
- **팁**: 각 폴더에 대한 간단한 설명을 덧붙여 이해를 돕습니다.
### 2. 컴포넌트별 가이드 (Per-Component Instructions)
- **목적**: 각 `app`과 `package`의 개별적인 설정, 실행, 테스트 방법을 안내합니다.
- **구성**:
- **`apps/web-app`**:
- **설명**: 최종 사용자가 상호작용하는 기본 웹 애플리케이션입니다.
- **실행**: `npm run dev --filter=web-app`
- **테스트**: `npm test --filter=web-app`
- **`packages/ui-kit`**:
- **설명**: 디자인 시스템과 재사용 가능한 UI 컴포넌트를 제공합니다.
- **빌드**: `npm run build --filter=ui-kit`
- **스토리북**: `npm run storybook --filter=ui-kit`
- **팁**: 각 컴포넌트의 `README.md`로 연결되는 링크를 제공하여 상세 정보를 확인할 수 있도록 합니다.
### 3. 공통 스크립트 (Repository-wide Scripts)
- **목적**: 저장소 전체에 적용되는 명령어를 중앙에서 관리하고 안내합니다.
- **예시**:
- `npm install`: 모든 패키지의 의존성을 한 번에 설치합니다.
- `npm run build:all`: 모든 `app`과 `package`를 빌드합니다.
- `npm run test:all`: 전체 테스트를 실행합니다.
- `npm run lint`: 코드 스타일을 검사하고 수정합니다.
### 4. CI/CD 파이프라인 개요
- **목적**: 코드 변경 사항이 어떻게 빌드, 테스트, 배포되는지 전체 흐름을 설명합니다.
- **포함 내용**:
- **트리거**: 어떤 브랜치에 코드가 푸시되면 파이프라인이 실행되는지 명시합니다. (예: `main`, `develop`)
- **주요 단계**: 빌드, 유닛 테스트, E2E 테스트, 배포 등의 단계를 간략히 설명합니다.
- **배포 환경**: 개발(dev), 스테이징(staging), 프로덕션(production) 환경별 배포 정책을 안내합니다.
### 5. 버전 관리 및 릴리즈 전략
- **목적**: 패키지 버전 업데이트와 릴리즈 과정을 안내하여 일관성을 유지합니다.
- **도구**: [Changesets](https://github.com/changesets/changesets) 와 같은 도구를 사용한 버전 관리 방법을 설명합니다.
- **프로세스**:
1. `feature` 브랜치에서 `npx changeset` 명령어로 변경 사항을 기록합니다.
2. `main` 브랜치에 병합되면, Changesets PR이 자동으로 생성됩니다.
3. 해당 PR을 병합하면 버전이 업데이트되고 npm에 배포됩니다.
> **템플릿 활용**: 모노레포는 `tpl-monorepo-*` 템플릿을 기반으로 생성하는 것을 권장합니다. 루트 README는 해당 템플릿의 사용법과 커스터마이징 방법을 포함해야 합니다.

62
guide-readme/research.md Normal file
View File

@ -0,0 +1,62 @@
# `res-*`, `ppr-*` (연구/논문) Repository README 작성 가이드
`res-*` (research) 또는 `ppr-*` (paper) 접두사가 붙은 저장소는 특정 학술 연구나 논문의 실험 코드를 관리합니다. README의 핵심 목표는 제3자가 해당 연구의 실험 결과를 정확하게 재현(reproduce)하고, 나아가 확장(extend)할 수 있도록 상세하고 명확한 가이드를 제공하는 것입니다.
---
### 1. 연구 개요 (Research Overview)
- **논문 정보 (Citation)**:
- **제목**: 연구 논문의 전체 제목
- **저자**: 모든 저자 목록
- **학회/저널**: 논문이 발표된 학회나 저널 정보 (예: `NeurIPS 2023`)
- **링크**: 논문 PDF나 arXiv 링크를 반드시 포함합니다.
- **BibTeX 인용**: 다른 연구자가 쉽게 인용할 수 있도록 BibTeX 형식을 제공합니다.
- **연구 배경 및 가설 (Background and Hypothesis)**:
- 이 연구가 해결하고자 하는 문제가 무엇인지 간략히 설명합니다.
- 연구를 통해 검증하고자 했던 핵심 가설을 명확히 기술합니다.
### 2. 실험 환경 설정 (Setup for Reproducibility)
- **목적**: 논문에 기술된 실험 결과를 그대로 재현하는 데 필요한 모든 환경 정보를 제공합니다.
- **필수 구성 요소**:
- **하드웨어 요구사항**: GPU 종류(예: `NVIDIA A100`), 메모리(RAM, VRAM) 등 실험에 사용된 하드웨어 스펙을 명시합니다.
- **소프트웨어 의존성**:
- `requirements.txt` (Python), `environment.yml` (Conda) 등 패키지 목록을 제공합니다.
- CUDA, cuDNN 버전과 같이 시스템 레벨의 의존성을 명확히 표기합니다.
- Docker를 사용한 경우, `Dockerfile`과 빌드 및 실행 방법을 안내하는 것이 가장 좋습니다.
- **데이터셋 준비**:
- 원본 데이터셋을 다운로드하는 링크와 스크립트를 제공합니다.
- 데이터 전처리가 필요한 경우, `bash scripts/preprocess_data.sh` 와 같이 실행 명령어를 안내하고, 예상 소요 시간을 명시합니다.
### 3. 실험 재현 스크립트 (Reproduction Scripts)
- **목적**: 논문에 보고된 주요 실험 결과를 재현하는 스크립트와 실행 방법을 안내합니다.
- **핵심 실험별 가이드**:
- **모델 학습 (Training)**:
```bash
# Table 1의 ResNet-50 모델 학습 재현
python train.py --config configs/resnet50_cifar10.yaml --output_dir results/resnet50
```
- **모델 평가 (Evaluation)**:
```bash
# 사전 학습된 모델 가중치로 Figure 2의 정확도 평가 재현
python evaluate.py --checkpoint_path pretrained_models/resnet50.pth --config configs/resnet50_cifar10.yaml
```
- **사전 학습된 모델 (Pre-trained Models)**:
- 논문에서 사용한 모델의 가중치 파일을 다운로드할 수 있는 링크(예: Google Drive, Hugging Face Hub)를 제공합니다. 이는 전체 학습 과정을 생략하고 평가만 진행하려는 사용자에게 매우 유용합니다.
### 4. 코드 구조 (Codebase Structure)
- **목적**: 전체 코드베이스의 디렉토리 구조와 각 파일의 역할을 설명하여, 다른 연구자가 코드를 이해하고 수정하거나 확장하기 용이하게 만듭니다.
- **예시**:
```plaintext
/
├── configs/ # 실험 설정 파일 (YAML, JSON)
├── data/ # 데이터 로더 및 전처리 코드
├── models/ # 모델 아키텍처 정의
├── scripts/ # 데이터 준비, 실험 실행 쉘 스크립트
├── src/ or lib/ # 핵심 로직 및 유틸리티 함수
├── train.py # 모델 학습 스크립트
└── evaluate.py # 모델 평가 스크립트
```
### 5. 기대 결과 (Expected Results)
- **목적**: 사용자가 스크립트를 올바르게 실행했는지 확인할 수 있도록, 논문에 보고된 결과(예: 정확도, 손실 값)를 명시합니다.
- **팁**: 특정 실험 스크립트 실행 후 출력되는 로그 예시나, 생성되는 결과 파일의 형태를 보여주면 좋습니다.

65
guide-readme/test-poc.md Normal file
View File

@ -0,0 +1,65 @@
# `tst-*`, `poc-*` (테스트/PoC) Repository README 작성 가이드
`tst-*` (test) 또는 `poc-*` (Proof of Concept) 접두사를 사용하는 저장소는 특정 기술, 아키텍처, 또는 가설의 실현 가능성을 검증하기 위한 공간입니다. README의 핵심 목표는 테스트의 목적, 방법, 그리고 결과를 명확하게 문서화하여 다른 팀원이나 이해관계자가 결론을 빠르게 이해하고 의사결정에 활용할 수 있도록 돕는 것입니다.
---
### 1. PoC 개요 (Proof of Concept Overview)
- **검증 목표 (Objective)**: 이 PoC를 통해 무엇을 검증하고 확인하려 하는지 한두 문장으로 명확히 기술합니다.
- 예시: "기존 REST API를 gRPC로 전환했을 때, 응답 시간(latency)이 50% 이상 개선되는지 검증한다."
- **가설 (Hypothesis)**: PoC를 통해 증명하고자 하는 가설을 구체적으로 서술합니다.
- 예시: "동일한 데이터 조회 요청에 대해 gRPC는 JSON 기반 REST API보다 적은 페이로드 크기 덕분에 더 빠를 것이다."
- **결론 요약 (Executive Summary)**: 테스트 결과 도출된 최종 결론을 서두에 요약하여 바쁜 동료들이 핵심만 빠르게 파악할 수 있도록 합니다.
- 예시: "결론: gRPC 도입 시 평균 응답 시간이 62% 개선되었으며, CPU 사용량은 유사한 수준을 유지했다. 프로덕션 도입을 긍정적으로 검토할 것을 제안한다."
### 2. 테스트 환경 (Test Environment)
- **목적**: 테스트가 수행된 환경을 정확히 명시하여 결과의 신뢰성을 확보하고, 다른 사람이 동일한 조건에서 재현할 수 있도록 합니다.
- **포함 내용**:
- **하드웨어 스펙**: CPU, 메모리, 네트워크 등 테스트에 사용된 인프라 사양
- **소프트웨어 버전**: 사용된 언어, 라이브러리, 프레임워크, 데이터베이스 등의 정확한 버전
- **부하 테스트 도구**: `k6`, `JMeter`, `Artillery` 등 사용한 도구와 설정값
- **예시 (표 활용)**:
| 항목 | 사양 / 버전 |
|---------------|-----------------------------------|
| **서버** | AWS EC2 `t3.micro` |
| **언어** | `Node.js` v18.12.1 |
| **프레임워크**| `Express` v4.18.2, `grpc-js` v1.8.0 |
| **부하 도구** | `k6` v0.42.0 |
### 3. 테스트 시나리오 및 실행 방법 (Test Scenarios & How to Run)
- **목적**: 어떤 항목들을 테스트했는지 목록화하고, 각 테스트를 실행하는 방법을 안내합니다.
- **테스트 항목 목록 (Test Cases)**:
- 1. 사용자 1,000명 정보 조회 (REST vs gRPC)
- 2. 단일 사용자 정보 생성 (REST vs gRPC)
- 3. 동시 사용자 100명 부하 테스트
- **실행 명령어**:
```bash
# 1. 서버 실행 (두 개의 터미널에서 각각 실행)
npm run start:rest_api
npm run start:grpc_server
# 2. 부하 테스트 실행
# k6 스크립트를 사용하여 각 엔드포인트를 테스트합니다.
k6 run tests/performance/get_users.js
```
### 4. 벤치마크 결과 (Benchmark Results)
- **목적**: 테스트 결과를 정량적으로 제시하여 가설 검증의 근거를 명확히 합니다.
- **결과 제시 방법**:
- **표(Table)**: 비교 항목(예: REST, gRPC)과 측정 지표(예: TPS, 평균 응답 시간, P99 응답 시간)를 표로 정리하여 가독성을 높입니다.
- **그래프/차트**: 시간 경과에 따른 성능 변화, 부하량에 따른 응답 시간 분포 등 시각화 자료를 첨부하여 결과를 직관적으로 보여줍니다.
- **예시**:
**사용자 1,000명 조회 API 성능 비교**
| API 유형 | 평균 응답 시간 (ms) | P99 응답 시간 (ms) | 초당 요청 수 (RPS) |
|----------|-----------------------|----------------------|--------------------|
| **REST** | 128 | 210 | 78 |
| **gRPC** | 49 | 85 | 204 |
![Response Time Comparison Chart](results/images/latency_comparison.png)
### 5. 분석 및 결론 (Analysis and Conclusion)
- **결과 분석**: 벤치마크 결과를 바탕으로 가설이 맞았는지, 예상치 못한 결과가 있었는지 등을 분석하고 해석합니다.
- **최종 결론**: PoC를 통해 얻은 결론과 후속 조치(예: 기술 도입, 추가 테스트 필요, 기각)를 명확히 제안합니다.

62
guide-readme/tool-infra.md Normal file
View File

@ -0,0 +1,62 @@
# `tol-*`, `inf-*` (공용 도구/인프라) Repository README 작성 가이드
`tol-*` (tool) 또는 `inf-*` (infrastructure) 접두사를 사용하는 저장소는 여러 프로젝트에서 공통으로 사용되는 도구나 인프라 구성(IaC) 코드를 관리합니다. README의 핵심 목표는 사용자가 이 도구를 '어떻게' 사용하는지, 인프라를 '어떻게' 배포하고 관리하는지에 대한 명확하고 실용적인 가이드를 제공하는 것입니다.
---
### 1. 도구/인프라 개요 (Overview)
- **목적 (Purpose)**: 이 도구가 해결하는 문제나, 이 인프라 코드가 구성하는 시스템이 무엇인지 명확하게 설명합니다.
- 예시 (`tol-`): "이 CLI 도구는 여러 Git 저장소에 분산된 `package.json`의 의존성 버전을 한 번에 동기화합니다."
- 예시 (`inf-`): "이 Terraform 코드는 AWS EKS 클러스터와 네트워킹, IAM 역할을 표준 구성으로 배포합니다."
- **아키텍처 (Architecture)**:
- 도구의 경우, 주요 기능과 동작 방식을 설명하는 간단한 다이어그램을 포함하면 좋습니다.
- 인프라의 경우, 프로비저닝될 클라우드 리소스의 관계를 보여주는 아키텍처 다이어그램(예: Mermaid.js, Cloudcraft)을 반드시 포함해야 합니다.
### 2. 설치 및 설정 (Installation and Setup)
- **설치 방법 (Installation)**:
- **CLI 도구**: `pip`, `npm`, `go install` 등을 이용한 설치 방법을 안내하거나, 바이너리 파일을 다운로드하는 방법을 설명합니다.
```bash
npm install -g @my-org/dependency-sync-tool
```
- **인프라 코드 (IaC)**: Terraform, Ansible 등 필요한 도구의 설치 및 버전 요구사항을 명시합니다.
```bash
# Terraform 1.2.x 이상 버전 필요
brew install terraform
```
- **초기 설정 (Configuration)**:
- **인증 (Authentication)**: AWS 자격 증명, GitHub 토큰 등 도구/인프라 사용에 필요한 인증 정보를 어떻게 설정하는지 안내합니다.
- **환경 변수**: `.env.example` 파일을 제공하고, 각 변수의 의미와 설정 방법을 설명합니다.
- **인프라 변수**: Terraform의 `terraform.tfvars.example` 파일을 제공하여 사용자가 자신의 환경에 맞게 수정할 수 있도록 안내합니다.
### 3. 사용법 (Usage)
- **가장 중요한 섹션**: 사용자가 실제로 도구를 사용하거나 인프라를 배포하는 구체적인 예시를 제공합니다.
- **CLI 도구 사용 예시**:
- 자주 사용되는 명령어와 옵션을 실제 예시와 함께 보여줍니다.
```bash
# 현재 디렉토리 하위의 모든 package.json에서 'react' 버전을 18.2.0으로 통일
dep-sync --lib react --version 18.2.0
# 미리보기 모드로 실행 (실제 파일은 변경하지 않음)
dep-sync --lib react --version 18.2.0 --dry-run
```
- **인프라 배포 스크립트 예시**:
- 개발, 스테이징, 프로덕션 환경별로 인프라를 배포하는 명령어를 명확히 구분하여 제공합니다.
```bash
# 1. 개발 환경 초기화 (dev.backend.tfvars 사용)
terraform init -backend-config=dev.backend.tfvars
# 2. 배포 계획 확인
terraform plan -var-file=dev.tfvars
# 3. 개발 환경에 배포
terraform apply -var-file=dev.tfvars
```
### 4. 권한 및 정책 (Permissions and Policies)
- **목적**: 이 도구나 인프라를 사용하기 위해 필요한 IAM 권한이나 접근 정책을 명시합니다.
- **팁**: 최소 권한 원칙(Principle of Least Privilege)에 따라 필요한 권한 목록(JSON 형식)을 제공하면 사용자가 IAM 정책을 쉽게 생성할 수 있습니다.
### 5. 유지보수 및 트러블슈팅 (Maintenance and Troubleshooting)
- **업데이트 방법**: 도구의 버전을 업그레이드하거나, 인프라 변경 사항을 적용하는 방법을 안내합니다.
- **자주 묻는 질문 (FAQ)**: 사용 중 발생할 수 있는 흔한 문제와 해결 방법을 정리합니다.
- "Q: `AccessDenied` 오류가 발생합니다. -> A: AWS 자격 증명에 `s3:PutObject` 권한이 있는지 확인하세요."

59
guide-readme/tpl.md Normal file
View File

@ -0,0 +1,59 @@
# `tpl-*` (템플릿) Repository README 작성 가이드
`tpl-*` 접두사가 붙은 저장소는 새로운 프로젝트를 신속하게 시작할 수 있도록 설계된 템플릿입니다. README의 핵심 목표는 사용자가 이 템플릿을 어떻게 사용하고, 자신의 요구사항에 맞게 커스터마이징하는지 명확하게 안내하는 것입니다.
---
### 1. 템플릿 소개 (Template Introduction)
- **핵심**: 이 템플릿이 어떤 종류의 프로젝트(예: `React` 웹앱, `FastAPI` 서버)를 위한 것인지 한 문장으로 설명합니다.
- **포함된 기술 스택**: `TypeScript`, `Next.js`, `Docker` 등 주요 기술 스택을 나열하여 사용자가 기술적 요구사항을 빠르게 파악할 수 있도록 합니다.
### 2. 시작하기 (Getting Started)
- **목적**: 사용자가 템플릿을 기반으로 새로운 프로젝트를 생성하는 과정을 단계별로 안내합니다.
- **명령어 예시**:
```bash
# 1. GitHub에서 "Use this template" 버튼을 클릭하거나, degit을 사용해 프로젝트를 생성합니다.
npx degit your-github/tpl-react-basic my-new-project
# 2. 프로젝트 디렉토리로 이동합니다.
cd my-new-project
# 3. 의존성을 설치합니다.
npm install
# 4. 개발 서버를 실행합니다.
npm run dev
```
### 3. 프로젝트 구조 (Project Structure)
- **목적**: 템플릿이 제공하는 기본 폴더 구조와 각 디렉토리의 역할을 설명합니다.
- **시각화**: `tree` 명령어 결과나 다이어그램을 활용하여 구조를 명확하게 보여줍니다.
- **예시**:
```plaintext
/
├── public/ # 정적 파일 (이미지, 폰트)
├── src/
│ ├── components/ # 재사용 가능한 UI 컴포넌트
│ ├── pages/ # 페이지별 컴포넌트
│ └── styles/ # 전역 스타일시트
├── .env.example # 환경변수 예시 파일
└── package.json
```
### 4. 커스터마이징 방법 (Customization Guide)
- **핵심 섹션**: 사용자가 템플릿을 자신의 프로젝트에 맞게 수정하는 방법을 안내합니다.
- **주요 항목**:
- **테마 및 스타일**: `src/styles/theme.ts` 파일에서 색상, 폰트 등을 수정하는 방법을 설명합니다.
- **환경 변수**: `.env.example` 파일을 복사하여 `.env` 파일을 만들고, 필요한 API 키 등을 설정하는 방법을 안내합니다.
- **기본 컴포넌트 수정**: 로고, 페이지 제목 등 기본적으로 수정해야 할 부분을 명시합니다.
- **팁**: 표(Table)를 사용하여 각 커스텀 옵션과 해당 파일을 명시하면 가독성이 높아집니다.
| 기능 | 파일 경로 | 설명 |
|--------------|---------------------------------|------------------------------------------|
| **로고 변경** | `src/components/Header.tsx` | 웹사이트의 로고 이미지를 교체합니다. |
| **테마 색상** | `src/styles/theme.js` | 프라이머리, 세컨더리 색상을 변경합니다. |
| **폰트 적용** | `src/styles/global.css` | Google Fonts 등 외부 폰트를 추가합니다. |
### 5. 스크린샷 또는 데모 (Screenshot or Demo)
- **목적**: 템플릿을 사용했을 때 결과물이 어떻게 보이는지 시각적으로 보여줍니다.
- **팁**: 기본 템플릿의 랜딩 페이지 스크린샷이나, Storybook 배포 링크를 첨부하면 효과적입니다.

132
guide-repository-naming.md Normal file
View File

@ -0,0 +1,132 @@
# 실용적 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`
- **내부 폴더 구조 (템플릿 제공)**:
```plaintext
research-portal/
├── .github/
├── apps/ # 애플리케이션 (웹, 문서 등)
│ ├── web/
│ └── docs-site/
├── packages/ # 공유 패키지 (UI 컴포넌트, 로거 등)
│ ├── ui-kit/
│ └── logger/
└── README.md
```