좋은 PR과 README 작성하기

기술 문서 작성이 왜 중요한가

코드 리뷰에서 PR 설명은 리뷰어의 진입점입니다. 좋은 PR 설명은:

리뷰어가 빠르게 무엇을 했는지 이해하도록 함
왕복 질문을 줄임
사려 깊게 생각했다는 인상을 줌
3개월 후 이력을 확인할 때 시간을 절약

마찬가지로 좋은 README는:

새로운 사람이 빠르게 시작하도록 도움
반복적인 질문을 줄임
프로젝트가 전문적으로 보이게 함

PR 설명의 표준 구조: What/Why/How/Testing

1. What (무엇을 했나)

간결한 요약, 한 문장.

Refactor authentication flow to support OAuth2 and magic link sign-up

또는 더 상세한 버전:

What: Refactor authentication flow to support OAuth2 and magic link sign-up

This PR replaces the old session-based auth with a stateless JWT approach,
enabling OAuth2 for easy sign-in and magic link for passwordless access.

핵심 표현:

Add X — 새 기능 추가 (완전히 존재하지 않았던)
Fix X — 버그 수정
Refactor X — 코드 재작성 (기능 변경 없이)
Optimize X — 성능 개선
Implement X — 설계 구현

2. Why (왜 했나)

가장 자주 빠뜨리는 부분입니다. 배경과 동기를 설명하세요.

Why:
- Users requested passwordless sign-up option
- Current session-based auth doesn't scale to multiple domains
- OAuth2 is industry standard for enterprise integrations

좋은 Why의 특징:

비즈니스 이유를 언급 (사용자 요구, 성능, 유지보수성)
기존 방안이 왜 부족한지 설명
이 해결책이 왜 더 나은지 설명

3. How (어떻게 했나)

기술 구현의 상위 수준 개요. 줄줄이 설명할 필요는 없지만 (그것은 코드 리뷰의 역할), 리뷰어가 전체 아키텍처를 알 수 있도록 해야 합니다.

How:
1. Created JWT service using Web Crypto API for signing/verification
2. Replaced SessionMiddleware with AuthMiddleware that validates JWT
3. Added OAuth2 routes for Google/GitHub sign-in
4. Migrated user session storage from cookie to JWT claims
5. Added magic link generation and validation

Breaking changes:
- Moved user auth state from server session to JWT (stateless)
- Clients now need to store and send JWT in Authorization header

핵심 표현:

Created X using Y — 기술 선택
Replaced X with Y — 마이그레이션
Added X routes — 새 API 엔드포인트
Migrated X from Y to Z — 데이터 마이그레이션
Breaking changes — 하위 호환성이 깨지는 변경

4. Testing (어떻게 테스트했나)

이 변경이 올바르다는 것을 어떻게 검증했는지 설명합니다.

Testing:
- Manual testing: Verified OAuth2 sign-in with Google and GitHub accounts
- Verified JWT expiration and refresh flow works correctly
- Existing auth tests pass (147 tests)
- Added 23 new tests for JWT and OAuth2 flows
- Load tested with 1000 concurrent requests (no issues)
- Tested on staging environment with real data

Outstanding:
- QA will do full regression testing (scheduled for Thursday)
- Performance benchmarks vs old auth (will share results in comment)

PR 설명 템플릿

복사하여 빈칸을 채우면 됩니다:

## What
[한 문장 요약]

[더 상세한 설명, 2~3문장]

## Why
- [이유 1]
- [이유 2]
- [이유 3, 있다면]

## How
1. [변경 1]
2. [변경 2]
3. [변경 3]

[breaking changes가 있다면 여기에 설명]

## Testing
- [어떤 테스트를 했는지]
- [결과가 무엇인지]
- [미완성 부분 (있다면)]

## Related
Closes #123
Depends on #456 (wait for this to merge first)

README의 일반 구조

시작: 프로젝트가 무엇인가

# ProjectName

One-sentence description of what this project does.

[데모 gif 또는 스크린샷]

설치 (Getting Started)

## Getting Started

### Prerequisites
- macOS 12+
- Node.js 18+ (for backend development)
- Xcode 14+ (for macOS app development)

### Installation
1. Clone the repository
2. Follow setup instructions in `/backend` and `/MacApp`
3. Run `npm run dev` in backend folder
4. Open `MacApp/DevLingo.xcodeproj` in Xcode

사용법 (Usage)

## Usage

### Basic Usage
1. Select any English text
2. Press ⌘⇧D (global hotkey)
3. Learn pronunciation, examples, synonyms

### Advanced Features
- Save words to personal vocabulary
- Spaced repetition for review
- Batch import from CSV

기술 문서 작성의 문법 함정

1. 시제 (가장 흔한 실수)

원칙: 현재형은 코드가 하는 일, 과거형은 당신이 한 변경

실수	원인	올바른 표현
”The function was created to handle X”	역사 서술처럼 들림	”The function handles X” 또는 “This PR adds a function that handles X"
"The code will validate input”	너무 불확실	”The code validates input"
"We added the feature” (README에서)	README는 역사를 말하지 않음	”This feature allows users to…“

2. 관사 (한국어 사용자에게 흔한 실수)

원칙: 처음 언급 시 “a/an”, 이후 “the” 사용; 또는 복수형으로 관사 회피

실수	원인	올바른 표현
”We refactored authentication flow”	어떤 flow인지 불명확	”We refactored the authentication flow"
"Function handles case when user logs in”	한국어식, “the” 누락	”The function handles the case when a user logs in”

3. 과도한 수동태

원칙: 영어는 능동태를 선호. 누가 했는지 말하고 싶지 않은 경우를 제외하고 능동태 사용

수동태 (흔한 한국어 간섭)	능동태 (더 나은)
“The JWT is generated by the server"	"The server generates the JWT"
"The user data is stored in D1"	"We store user data in D1"
"Breaking changes were introduced"	"This PR introduces breaking changes”

4. 동의어의 미묘한 차이

어휘	용법
Add	새 기능 추가 (완전히 없었던): “Add OAuth2 support”
Implement	알려진 설계 구현: “Implement the design from #123”
Create	새 객체 생성: “Create JWT service”
Build	시스템 구축: “Build the CI/CD pipeline”
Refactor	기존 코드 개선, 기능 변경 없이: “Refactor auth middleware”
Optimize	성능 향상: “Optimize query performance”
Fix	버그 수정: “Fix race condition in cache”

PR 설명 빠른 체크리스트

PR 전송 전 확인:

What 부분이 변경을 명확히 설명
Why 부분에 비즈니스 또는 기술적 이유가 있음 (“그냥 하고 싶었다”가 아님)
How 부분에 상위 수준 설계가 있어 리뷰어가 코드를 줄줄이 읽지 않아도 됨
Testing 부분에 테스트 커버리지가 설명됨
과도한 수동태가 없음
관사가 올바르게 사용됨 (“the” vs “a”)
시제가 일관됨 (현재형은 코드 기능, 과거형은 변경)
관련 issue에 링크됨 (있다면)

README 빠른 체크리스트

첫 문장이 프로젝트가 무엇인지 명확히 설명
데모 또는 스크린샷이 있음
설치 단계가 명확하고 재현 가능
사용법 예시를 직접 복사할 수 있음
contributing 가이드가 있음 (외부 기여를 수용하는 경우)
license가 있음
언어가 간결함 (너무 학술적이거나 너무 캐주얼하지 않음)