16강. README와 문서화 | 깃허브 사용법 18강 — Git & GitHub 협업 · 입문 — 누구나패스

🎯 학습 목표

이 강을 마치면 다음을 할 수 있습니다.

GitHub 저장소의 첫인상을 결정하는 좋은 README.md를 작성할 수 있습니다.
GitHub 마크다운의 핵심 문법(헤딩, 리스트, 코드블록, 테이블, 이미지)을 사용할 수 있습니다.
shields.io 배지를 추가해 저장소에 빌드 상태와 기술 스택을 표시할 수 있습니다.
오픈소스 저장소를 완성도 있게 만드는 CONTRIBUTING.md, LICENSE 파일을 이해합니다.

📖 README.md — 저장소의 얼굴

이 섹션에서는 GitHub 저장소에서 README.md가 왜 중요하며 어떤 요소가 반드시 포함되어야 하는지 살펴보겠습니다.

README.md는 GitHub 저장소 홈 화면에서 자동으로 렌더링되어 표시되는 파일입니다. 저장소를 방문한 사람이 가장 먼저 보는 문서로, 이 프로젝트가 무엇인지, 어떻게 사용하는지를 설명합니다. 코드 품질만큼 README 품질도 중요합니다. 좋은 README는 "이 프로젝트를 신뢰할 수 있다"는 신호를 줍니다.

README가 특히 중요한 상황입니다.

오픈소스 프로젝트: 낯선 사람이 사용하고 기여할 수 있도록 안내
취업 포트폴리오: 면접관이 프로젝트를 이해하는 첫 관문
팀 내부 공유: 팀원이 프로젝트를 빠르게 파악하고 환경을 설정하도록 도움

📋 좋은 README의 필수 구성 요소

이 섹션에서는 목적에 따라 달라지는 README 구성과 각 섹션이 담아야 할 내용을 살펴보겠습니다.

모든 README에 들어가야 할 핵심 요소입니다.

프로젝트 이름 + 한 줄 설명: 이 프로젝트가 무엇인지 단숨에 파악
데모 또는 스크린샷: "백 마디 말보다 한 장의 이미지"
주요 기능: 무엇을 할 수 있는지 핵심 목록
설치 방법: 환경 요구사항 + 단계별 설치 명령어
사용 방법: 기본 사용 예시 코드 또는 명령어
기술 스택: 어떤 언어·프레임워크·라이브러리를 사용했는지
기여 방법: 협업하고 싶은 사람을 위한 안내 (또는 CONTRIBUTING.md 링크)
라이선스: 이 코드를 어떤 조건으로 사용할 수 있는지

✍️ GitHub 마크다운 핵심 문법

이 섹션에서는 README.md 작성에 필수적인 GitHub Flavored Markdown(GFM) 문법을 살펴보겠습니다.

GitHub은 일반 마크다운에 몇 가지 확장 기능을 더한 GitHub Flavored Markdown(GFM)을 사용합니다.

# 헤딩 (제목)
# H1 제목
## H2 소제목
### H3 소소제목

# 텍스트 강조
**굵게** 또는 __굵게__
*기울임* 또는 _기울임_
~~취소선~~

# 리스트
- 항목 1
- 항목 2
  - 중첩 항목

1. 순서 있는 목록
2. 두 번째
3. 세 번째

# 코드블록
인라인 코드: `npm install`

블록 코드 (언어 지정 시 문법 강조):
(triple backtick)bash
npm install
npm run dev
(triple backtick)

# 링크와 이미지
[링크 텍스트](URL)
![이미지 대체 텍스트](이미지URL)
![대체 텍스트](./docs/screenshot.png)  # 로컬 이미지

# 테이블
| 이름  | 역할      | 기술     |
|-------|-----------|----------|
| 홍길동 | 백엔드    | Node.js  |
| 김철수 | 프론트엔드 | React    |

# 체크박스 (GitHub Issues·PR에서 활용)
- [x] 로그인 기능
- [ ] 회원가입 기능
- [ ] 프로필 페이지

# 인용
> 이 부분은 인용 블록으로 표시됩니다.

# 수평선 구분
---

🏆 shields.io 배지 — 저장소 신뢰도 높이기

이 섹션에서는 GitHub 저장소에 빌드 상태, 버전, 라이선스 등을 시각적으로 표시하는 배지를 추가하는 방법을 살펴보겠습니다.

배지(Badges)는 README 상단에 표시하는 작은 정보 스티커입니다. CI 상태, 버전, 라이선스, 다운로드 수 등을 한눈에 보여줍니다. shields.io에서 원하는 배지의 마크다운 코드를 생성할 수 있습니다.

# README.md 배지 예시 (마크다운 문법)

# GitHub Actions CI 상태
![CI](https://github.com/username/repo/actions/workflows/ci.yml/badge.svg)

# npm 버전
![npm version](https://img.shields.io/npm/v/패키지명)

# 라이선스
![License](https://img.shields.io/badge/license-MIT-blue)

# 기술 스택 배지
![Node.js](https://img.shields.io/badge/Node.js-339933?logo=nodedotjs&logoColor=white)
![React](https://img.shields.io/badge/React-61DAFB?logo=react&logoColor=black)
![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)

배지는 정보를 제공하는 것이 목적이므로 너무 많으면 오히려 산만해집니다. 3~6개 정도가 적당합니다.

📁 추가 문서 파일들

이 섹션에서는 완성도 있는 GitHub 저장소를 위해 README 외에 추가하면 좋은 문서 파일들을 살펴보겠습니다.

CONTRIBUTING.md: 외부 기여자를 위한 안내서입니다.

개발 환경 설정 방법
브랜치 네이밍 규칙
커밋 메시지 형식
PR을 보내기 전 체크리스트
코드 스타일 가이드 링크

Apache 2.0: MIT와 유사하지만 특허 관련 조항 포함
GPL 3.0: 수정·배포 시 반드시 같은 라이선스로 공개 (전염성)

# GitHub에서 저장소 생성 시 라이선스 선택 가능
# 기존 저장소에 추가: 루트에 LICENSE 파일 생성
# GitHub 웹에서 Add file → Create new file → "LICENSE" 입력
# → GitHub이 라이선스 선택 UI를 자동으로 표시

CHANGELOG.md: 버전별 변경 사항을 기록합니다. 사용자가 "이 버전에서 무엇이 바뀌었는지" 알 수 있게 합니다. Keep a Changelog(keepachangelog.com) 형식이 널리 사용됩니다.

CODE_OF_CONDUCT.md: 오픈소스 커뮤니티의 행동 강령. 다양한 배경의 기여자들이 서로 존중하며 참여할 수 있는 환경을 명시합니다.

💼 실전 README 작성 예시

이 섹션에서는 지금까지 배운 내용을 종합해 실제 프로젝트 README 구조를 살펴보겠습니다.

# README.md 기본 구조 예시

# 프로젝트 이름
![CI](badge-url) ![License](badge-url)

한 줄로 이 프로젝트를 설명합니다.

![스크린샷](./docs/screenshot.png)

## ✨ 주요 기능
- 기능 1 설명
- 기능 2 설명

## 🚀 빠른 시작

### 요구사항
- Node.js 18 이상
- npm 또는 yarn

### 설치
(backtick)bash
git clone https://github.com/username/project.git
cd project
npm install
npm run dev
(backtick)

## 🛠️ 기술 스택
- **프론트엔드**: Next.js, TypeScript, Tailwind CSS
- **백엔드**: Node.js, PostgreSQL
- **배포**: Vercel

## 🤝 기여하기
[CONTRIBUTING.md](./CONTRIBUTING.md) 를 참고해 주세요.

## 📄 라이선스
이 프로젝트는 [MIT License](./LICENSE)로 배포됩니다.

📝 핵심 요약

16강에서 배운 내용을 정리해 보겠습니다.

파일	역할	필수 여부
README.md	프로젝트 소개·설치·사용법	필수
LICENSE	코드 사용 권한 명시	오픈소스 필수
CONTRIBUTING.md	기여 방법 안내	협업 시 권장
CHANGELOG.md	버전별 변경 이력	릴리즈 있을 때
.gitignore	추적 제외 파일 목록	필수 (6강에서 학습)

다음 강인 17강 — GitHub Pages·Actions 맛보기에서는 GitHub의 강력한 자동화 기능 두 가지를 체험합니다. GitHub Pages로 정적 사이트를 무료로 배포하고, GitHub Actions으로 push 시 자동 테스트를 실행하는 CI를 설정합니다!

README와 문서화