개발자의 업무 중 코드를 직접 작성하는 시간은 생각보다 적다. 나머지는 읽고 쓰는 시간이다. PR 설명을 쓰고, 슬랙에서 기술적 결정을 설명하고, 장애 보고서를 작성하고, 기술 제안서를 쓴다. 이 글쓰기의 질이 팀의 생산성에 직접 영향을 준다.
PR 설명
PR 설명이 없거나 "기능 구현"이라고만 적힌 PR을 리뷰해본 적 있는가? 리뷰어는 코드를 한 줄씩 읽으며 "이게 뭘 하려는 거지?"를 추론해야 한다. 시간이 오래 걸리고, 의도를 잘못 파악하면 엉뚱한 코멘트를 단다.
좋은 PR 설명은 리뷰어의 시간을 줄여준다:
## 변경 사항
결제 페이지에서 쿠폰 적용 시 할인 금액이 음수로 표시되는 버그 수정
## 원인
쿠폰 할인율(`discountRate`)이 0~1 사이 소수인데,
UI에서 퍼센트(0~100)로 표시할 때 100을 곱하지 않고 그대로 사용함.
`0.15 * 10000 = 1500`이어야 하는데 `15 * 10000 = 150000`으로 계산됨.
## 해결
`formatDiscount()` 함수에서 discountRate에 100을 곱하는 로직 추가.
관련 유닛 테스트 3개 추가.
## 테스트
- [x] 10%, 50%, 100% 쿠폰으로 테스트
- [x] 쿠폰 없는 경우 기존 동작 확인이 PR은 코드를 보기 전에 이미 "무엇이 문제였고, 어떻게 고쳤는지" 파악이 된다. 리뷰어는 "이 수정이 맞는지"만 확인하면 된다.
장애 보고서
장애가 나면 보고서를 쓴다. 이걸 어떻게 쓰느냐에 따라 같은 장애의 재발을 막을 수도, 묻어버릴 수도 있다.
나쁜 장애 보고서:
결제 오류 발생. 서버 재시작으로 해결.
좋은 장애 보고서:
## 타임라인
- 14:23 — 결제 실패 알림 (Sentry)
- 14:25 — 확인 시작. 결제 API 타임아웃 확인
- 14:30 — PG사 상태 페이지 확인, 정상
- 14:35 — DB 커넥션 풀 고갈 확인 (max 10, active 10, waiting 47)
- 14:40 — 원인 파악: 배치 작업이 커넥션을 점유하고 반환하지 않음
- 14:42 — 배치 작업 중지, 커넥션 반환 확인
- 14:45 — 결제 정상 동작 확인
## 근본 원인
배치 작업에서 트랜잭션 에러 시 커넥션을 반환하지 않는 코드.
try-catch에서 catch 블록에 커넥션 release가 빠져 있었음.
## 조치
1. catch 블록에 커넥션 release 추가 (PR #234)
2. 커넥션 풀 사용량 모니터링 알림 추가
3. 커넥션 풀 최대값 10 → 30으로 조정
## 재발 방지
- 커넥션 풀 사용률 80% 이상 시 슬랙 알림
- 배치 작업은 별도 커넥션 풀 사용하도록 분리 (다음 스프린트)
두 번째 보고서는 3개월 후에 비슷한 상황이 발생했을 때, 이전 경험을 바탕으로 빠르게 대응할 수 있는 자산이 된다.
기술 제안서 (RFC)
새로운 기술이나 아키텍처를 도입하고 싶을 때 "이거 좋으니까 쓰자"로는 설득이 안 된다. 기술 제안서를 쓸 수 있어야 한다.
# 상태 관리 라이브러리 마이그레이션 제안
## 현재 상태
Redux + Redux Saga로 전역 상태 관리.
보일러플레이트 코드가 과도하고, 새 기능 추가 시 action/reducer/saga를
매번 작성해야 해서 개발 속도 저하.
## 제안
Zustand로 마이그레이션
## 근거
1. 보일러플레이트 감소: 같은 기능을 30% 적은 코드로 구현 가능
2. 번들 사이즈: Redux Toolkit(~11KB) + Saga(~14KB) vs Zustand(~1KB)
3. 학습 곡선: 새 팀원 온보딩 시간 단축
4. 커뮤니티: npm 주간 다운로드 3배, GitHub 이슈 응답 속도
## 대안 검토
- Jotai: 원자적 상태에 적합하나 우리 앱의 전역 상태 패턴과 안 맞음
- Recoil: Meta 내부 지원 불확실, 업데이트 빈도 저조
## 마이그레이션 계획
1. 새 기능은 Zustand로 작성 (즉시)
2. 기존 기능을 점진적으로 전환 (분기 1건)
3. Redux 완전 제거 목표: 3개월
## 리스크
- 마이그레이션 중 두 시스템 공존으로 인한 복잡도 증가
- 기존 Redux devtools 대비 디버깅 경험 변화이 문서 하나로 팀 미팅에서 30분이면 결정이 난다. 문서 없이 회의하면 1시간을 써도 "다음에 다시 이야기하자"로 끝나기 쉽다.
슬랙 메시지
짧은 슬랙 메시지도 글쓰기다.
나쁜 예:
이거 안 돼요
좋은 예:
결제 페이지에서 "적용" 버튼 클릭 시 콘솔에
"TypeError: coupon.discount is not a function" 에러가 나면서
할인이 적용되지 않습니다. Chrome 최신, 로컬 dev 환경.
스크린샷 첨부합니다.
두 번째 메시지는 읽는 사람이 바로 원인을 추론할 수 있다. "어떤 페이지에서, 어떤 동작을 했더니, 어떤 에러가 나며, 어떤 환경에서" — 이 네 가지만 포함해도 메시지의 질이 완전히 달라진다.
코드를 잘 쓰는 사람이 글도 잘 쓰는 건 아니다. 그런데 글을 잘 쓰는 개발자는 팀 안에서 다른 종류의 영향력을 갖게 된다. 기술적 결정을 주도하고, 장애 상황을 정리하고, 팀의 지식을 체계화하는 사람. 코딩 실력만으로는 얻기 어려운 위치다.