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

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 배포 링크를 첨부하면 효과적입니다.