개발자는 글을 못 쓴다고요? - 글쓰기 점검을 개발 워크플로우에 넣기
'개발자는 글을 못 쓴다고요?'를 읽고 커밋 메시지부터 장애 보고서까지 실무 글쓰기의 점검 기준을 정리했습니다. 훅과 템플릿, AI 검토를 개발 워크플로우에 넣어 글을 다시 읽는 습관으로 이어 간 경험을 담았습니다.
들어가며: 개발자는 정말 글을 못 쓸까?
개발하다 보면 코드 외에도 쓸 글이 많습니다. 커밋 메시지와 PR 설명을 작성하고, README를 다듬고, Slack으로 장애 상황을 공유합니다. 매일 하는 일이지만 이런 작업을 글쓰기라고 생각하지는 않았습니다.
“개발자는 글을 못 쓴다고요?”를 읽으면서 평소 쓰던 문서를 돌아보게 됐습니다.
이 책은 개발자의 글쓰기를 크게 코드 안의 글쓰기(변수명, 주석, 커밋 메시지)와 코드 바깥의 글쓰기(README, 릴리스 노트, 장애 보고서, 기술 블로그)로 나눠 설명합니다. 이 글에서는 책을 읽고 참고할 만했던 내용을 여섯 가지 글쓰기 유형으로 정리했습니다.
1. 커밋 메시지: 변경 이유 남기기
왜 커밋 메시지가 중요한가
커밋 메시지에 변경 이유를 남겨 두면 나중에 git blame으로 코드를 살펴볼 때 도움이 됩니다. 책에서 커밋 메시지를 “미래의 동료(혹은 미래의 나)에게 보내는 편지”로 비유합니다.
fix bug만 적혀 있으면 어떤 문제를 고쳤는지 알기 어렵습니다. 증상과 수정 이유를 함께 적어 두면 당시 맥락을 다시 파악하는데 유용합니다.
좋은 커밋 메시지의 구조
Conventional Commits 규약을 따르면 다음과 같이 작성할 수 있습니다.
1
2
3
4
5
<type>(<scope>): <description>
[body]
[footer]
| 구성 요소 | 역할 | 예시 |
|---|---|---|
| type | 변경의 성격 분류 | feat, fix, docs, refactor, test, chore |
| scope | 변경이 적용된 모듈/범위 | auth, payment, api |
| description | 변경 사항 한 줄 요약 | add retry logic for payment gateway timeout |
| body | “왜” 이 변경을 했는지 상세 설명 | 기술적 맥락, 비즈니스 배경 |
| footer | 이슈 참조, Breaking Change 명시 | Ref #342, BREAKING CHANGE: ... |
나쁜 예시 vs 좋은 예시
1
2
3
4
5
// 나쁜 예시
fix bug
수정
Update
WIP
위 메시지들의 공통적인 문제는 무엇을 왜 변경했는지 알기 어렵다는 점입니다.
1
2
3
4
5
6
7
8
// 좋은 예시
feat(auth): add Google OAuth2 login support
- Google OAuth2 API를 사용하여 소셜 로그인 구현
- 기존 세션 기반 인증과 병행 가능하도록 인증 로직 확장
- 로그인 실패 시 fallback으로 이메일 로그인 유도
Ref #234
커밋 메시지 작성 원칙
- 제목은 50자 이내, 본문은 한 줄당 72자 내외로 줄바꿈
- 동사 원형으로 시작 (Added -> Add, Fixed -> Fix)
- 제목 끝에 마침표를 붙이지 않기
- 본문에는 “어떻게(How)”보다 “왜(Why)” 를 작성
- 하나의 커밋에 하나의 논리적 변경만 담기
책에서는 “커밋을 설계하라”고 표현합니다. 무작정 코드를 작성한 뒤 커밋하는 것이 아니라, 작업 단위를 먼저 나누고 그 단위에 맞게 커밋하는 습관이 결국 좋은 커밋 메시지로 이어진다는 뜻입니다.
2. README: 프로젝트 소개와 실행 방법
처음 보는 사람을 위한 설명
새로운 팀원이나 사용자는 보통 README부터 읽습니다. 프로젝트의 목적과 실행 방법이 빠져 있으면 코드를 읽기 전부터 막힐 수 있습니다.
책에서는 README를 “프로젝트의 현관문”에 비유합니다. 처음 보는 사람이 프로젝트를 이해하고 실행할 수 있도록 안내한다는 점에서 공감했습니다.
README에 담을 내용
| 순서 | 섹션 | 설명 |
|---|---|---|
| 1 | 프로젝트 이름 및 한 줄 소개 | 프로젝트의 목적을 짧게 설명 |
| 2 | 배지(Badges) | 빌드 상태, 커버리지, 라이선스 등 신뢰도 표시 |
| 3 | 스크린샷 / 데모 | 화면이나 사용 예시로 동작 설명 |
| 4 | Quick Start | 설치부터 첫 실행까지 필요한 절차 |
| 5 | 사용법(Usage) | 핵심 기능의 코드 예제 |
| 6 | 기여 가이드(Contributing) | 이슈 등록, PR 규칙, 코드 컨벤션 |
| 7 | 라이선스(License) | 법적 사용 범위 명시 |
흔한 실수
- 설치 가이드가 개발자 본인의 환경에만 맞춰져 있는 경우: “Node.js 설치하고
npm install하면 됨” 대신, Node.js 버전 요구사항과 필요한 OS별 차이점도 적어야 합니다. - 업데이트가 안 되는 README: 코드는 v3.0인데 README는 v1.0 기준으로 작성되어 있는 경우. README도 코드 변경에 맞춰 수정해야 합니다.
README는 이 프로젝트를 처음 보는 사람을 기준으로 씁니다. 배경을 모르는 사람도 설명을 따라 실행할 수 있는지 확인합니다.
3. 릴리스 노트: 사용자에게 변경 사항 알리기
사용자가 알아야 할 변경 사항
릴리스 노트에 커밋 목록만 나열하면 사용자가 자신에게 필요한 변경 사항을 찾기 어렵습니다. 새로 사용할 수 있는 기능, 달라진 동작, 업데이트할 때 주의할 점을 중심으로 정리합니다.
릴리스 노트 작성 구조
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
## v2.3.0 (2026-06-01)
### 새로운 기능
- **Google OAuth 로그인 지원**: 이제 Google 계정으로 간편하게 로그인할 수 있습니다.
- **대시보드 실시간 알림**: 주요 지표 변동 시 대시보드에서 즉시 알림을 수신합니다.
### 개선 사항
- 검색 결과 로딩 속도를 40% 개선했습니다.
- 모바일 환경에서 사이드바 네비게이션의 반응성을 향상시켰습니다.
### 버그 수정
- 결제 페이지에서 간헐적으로 발생하던 금액 표시 오류를 수정했습니다.
- 파일 업로드 시 한글 파일명이 깨지는 문제를 해결했습니다.
### 주의사항 (Breaking Changes)
- `/api/v1/users` 엔드포인트가 제거되었습니다. `/api/v2/users`를 사용해 주세요.
### 마이그레이션 가이드
- 기존 v1 API를 사용 중이시라면 [마이그레이션 문서]를 참고해 주세요.
릴리스 노트 작성 원칙
- 사용자 관점에서 작성: 기술 용어를 최소화하고, 사용자에게 달라지는 점을 중심으로 설명
- 카테고리별 분류: 새 기능, 개선, 버그 수정, Breaking Change를 명확히 구분
- 영향 범위 명시: Breaking Change가 있다면 마이그레이션 경로를 반드시 함께 제공
- 감사 인사: 오픈소스라면 기여자에 대한 감사 표시를 빠뜨리지 않기
4. 장애 보고서(포스트모템): 원인과 재발 방지 방법 기록하기
개인의 잘못보다 원인과 대응 과정에 집중하기
장애 보고서에는 발생 원인과 대응 과정을 기록하고 재발 방지 방법을 정리합니다. 개인의 잘못을 따지는 데 그치면 같은 문제가 생길 수 있는 조건을 놓치기 쉽습니다. Google SRE의 “비난 없는 포스트모템(Blameless Postmortem)”도 이런 접근을 설명합니다.
책에서도 장애 보고서를 다루며, “사람이 아닌 프로세스의 구멍을 찾아라”고 강조합니다.
장애 보고서 템플릿
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
# 장애 보고서: [장애 제목]
## 요약
- 발생 일시: 2026-05-30 14:23 ~ 15:47 (KST)
- 영향 범위: 결제 서비스 전체 (약 12,000명의 활성 사용자 영향)
- 심각도: P1 (서비스 핵심 기능 완전 중단)
## 타임라인
| 시각 | 이벤트 |
| :---- | :----------------------------------------------- |
| 14:23 | Grafana 알림 - 결제 API 5xx 에러율 급증 감지 |
| 14:28 | 온콜 엔지니어 확인, 결제 DB 커넥션 풀 고갈 확인 |
| 14:35 | DB 슬로우 쿼리 확인, 특정 배치 작업이 락 점유 중 |
| 14:50 | 배치 프로세스 수동 중지, 커넥션 풀 점진 회복 |
| 15:47 | 전체 서비스 정상화 확인 |
## 근본 원인 분석 (Root Cause Analysis)
배포된 야간 정산 배치가 트랜잭션 타임아웃 설정 없이 대량 데이터를
처리하면서 DB 커넥션을 장시간 점유. 이로 인해 실시간 결제 트랜잭션이
커넥션을 할당받지 못해 타임아웃 에러 발생.
## 5 Whys
1. 왜 결제 서비스가 중단되었나? -> DB 커넥션 풀이 고갈
2. 왜 커넥션이 고갈되었나? -> 배치 작업이 커넥션을 장시간 점유
3. 왜 배치가 커넥션을 오래 잡았나? -> 트랜잭션 타임아웃 미설정
4. 왜 타임아웃이 설정되지 않았나? -> 배치 코드 리뷰 시 체크리스트에 해당 항목 부재
5. 왜 체크리스트에 없었나? -> 배치 작업 배포 프로세스가 API와 동일한 기준으로 운영
## 재발 방지 대책 (Action Items)
| 우선순위 | 담당자 | 완료 기한 | 액션 |
| :------- | :----- | :-------- | :------------------------------------------- |
| P0 | 홍길동 | 06/05 | 모든 배치 트랜잭션에 30초 타임아웃 일괄 적용 |
| P1 | 김개발 | 06/10 | 배치 전용 DB 커넥션 풀 분리 구성 |
| P2 | 이검토 | 06/15 | 배치 배포 체크리스트에 리소스 격리 항목 추가 |
## 교훈 (Lessons Learned)
- 잘한 점: Grafana 알림이 5분 이내에 이상 감지하여 빠른 초동 대응 가능
- 개선할 점: 배치 작업과 실시간 서비스의 리소스 격리가 미흡
- 행운이었던 점: 피크 트래픽 시간 이전에 장애가 발생하여 영향 사용자 수가 제한적
장애 보고서 작성 원칙
- 비난하지 않기: “김 개발자가 실수해서”가 아니라 “타임아웃 미설정을 감지할 프로세스가 부재”
- 팩트 기반: 감정이나 추측을 배제하고, 로그와 메트릭 데이터에 근거
- 타임라인은 상세하게: 장애 인지부터 복구까지의 모든 이벤트를 시간순 기록
- 액션 아이템은 구체적으로: “개선한다” 대신 “누가, 언제까지, 무엇을” 명시
- 24~48시간 이내 작성: 기억이 선명할 때 초안 작성, 이후 팀 리뷰를 거쳐 확정
장애 보고서는 팀에 공유하고 다시 찾기 쉬운 곳에 보관합니다. 다른 팀도 참고할 수 있게 해 두면 비슷한 문제에 대응할 때 도움이 됩니다.
5. 기술 블로그: 배운 내용과 해결 과정 정리하기
기술 블로그를 써야 하는 이유
책에서는 기술 블로그의 가치를 크게 세 가지로 정리합니다.
- 지식의 검증: 안다고 생각했던 내용을 글로 정리하면, 모호하게 알고 있던 부분이 드러남
- 개인 브랜딩: 어떤 문제를 다뤘고 어떻게 판단했는지 보여주는 기록
- 기록의 축적: 반복적으로 검색하던 내용을 자기만의 언어로 정리하면, 나중에 다시 참고하기 좋음
좋은 기술 블로그 글의 구조
| 단계 | 질문 | 설명 |
|---|---|---|
| 도입부 | “이 글은 왜 필요한가?” | 독자의 문제 상황 공감, 글을 읽어야 하는 이유 제시 |
| 배경/맥락 | “어떤 상황이었는가?” | 기술 선택의 배경, 제약 조건 설명 |
| 본론 | “어떻게 해결했는가?” | 코드 예시, 아키텍처 다이어그램, 단계별 설명 |
| 결과/회고 | “그래서 어떻게 되었는가?” | 성과 수치, 남은 과제, 대안 비교 |
| 마무리 | “독자에게 무엇을 남길 것인가?” | 핵심 정리, 추가 참고 자료 안내 |
기술 블로그 작성 시 흔한 함정
- 공식 문서 번역에 그치는 글: “React에서 useState는 이렇게 사용합니다”는 이미 공식 문서에 있음. 차별점은 “내가 겪은 문제와 그 해결 과정”
- 결론만 있는 글: “이렇게 하면 됩니다”보다 왜 이 방법을 선택했고 다른 대안은 제외했는지 설명하면 판단 과정을 이해하기 쉬움
- 완벽주의에 빠져 발행하지 못하는 글: 초안을 먼저 쓰고 다듬어 발행할 수 있는 분량으로 마무리
오늘 해결한 버그나 새로 알게 된 API처럼 작은 주제부터 기록해도 좋습니다. 직접 확인한 내용과 해결 과정을 적으면 한 편의 글이 됩니다.
6. 코드 리뷰 코멘트와 PR 설명: 변경 의도 전달하기
수정 이유와 대안을 함께 설명하기
책을 읽으며 코드 리뷰 코멘트도 다시 보게 됐습니다. “이거 왜 이렇게 짰어요?”라고 묻기보다 우려하는 점과 수정 방향을 함께 설명하면 상대가 의견을 이해하기 쉽습니다.
PR 설명 작성 가이드
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
## 변경 사항 요약
결제 모듈에 재시도 로직을 추가하여 PG사 타임아웃 시 자동 재시도합니다.
## 변경 이유
- PG사 API의 간헐적 타임아웃으로 인해 월 평균 23건의 결제 실패 발생
- 사용자가 직접 재시도해야 하는 UX 문제 존재
## 변경 내용
- `PaymentService`에 지수 백오프 기반 재시도 로직 추가 (최대 3회)
- 재시도 횟수 초과 시 Slack 알림 발송
- 재시도 관련 메트릭 Grafana 대시보드 추가
## 테스트
- 단위 테스트 15건 추가 (재시도 성공/실패/타임아웃 시나리오)
- 스테이징 환경에서 PG사 타임아웃 시뮬레이션 완료
## 스크린샷
(해당 시 첨부)
코드 리뷰 코멘트 원칙
- 질문형으로 작성: 지시보다 제안, 강요보다 질문
- 코드에 대한 의견이지, 사람에 대한 평가가 아님을 명확히
- 칭찬도 포함: 좋았던 부분도 이유와 함께 설명
- 구체적 대안 제시: 단순히 “이건 좀 별로”보다 “이 부분을 Strategy 패턴으로 분리하면 확장성이 좋아질 것 같습니다”
읽고 나서
이 책을 읽고 평소 쓰던 문서의 목적을 다시 생각해 봤습니다.
그동안 커밋 메시지는 형식적으로 적거나 README 정리를 미룰 때가 있었습니다. 장애 보고서는 부담스러웠고, 기술 블로그도 시간을 내서 쓰기가 쉽지 않았습니다.
책에서 다룬 문서들은 코드의 의도를 전달하고, 팀이 겪은 문제와 해결 방법을 남기는 데 필요했습니다. 문서를 쓰는 이유를 이렇게 생각하니 어떤 내용을 담아야 할지도 조금 더 분명해졌습니다.
읽고 나서 기억에 남은 내용은 다음과 같습니다.
- 글에는 목적이 있다: 누가 어떤 이유로 읽을지 먼저 생각하면 담을 내용을 정하기 쉽습니다.
- 완벽보다 완료가 먼저다: 초안을 먼저 작성하고 여러 번 다듬습니다.
- 코드의 맥락을 남긴다: 구현 내용과 판단 근거를 적어 두면 동료가 코드를 이해하는 데 도움이 됩니다.
커밋 메시지와 PR 설명에도 무엇을 바꿨는지와 함께 왜 바꿨는지 남기기 시작했습니다.
정리
책에서 정리한 내용을 매번 되새기고, 아예 글을 잘못쓰는걸 방지하가위해 글마다 확인할 항목과 점검하는 방법을 정해 뒀습니다. 형식처럼 기준이 명확한 항목은 훅에서 검사하고, 문맥을 읽어야 하는 항목은 AI 검토 스킬에 담았습니다.
- 커밋 메시지
- 체크사항: 나중에 읽어도 무엇을 왜 바꿨는지 알 수 있는가?
- 적용 방법(훅): 커밋 메시지를 확정할 때 commitlint를 실행해 커밋 유형과 제목 형식을 검사합니다.
- 적용 방법(스킬): 코드 변경과 메시지를 함께 검토해 설명이 실제 변경과 맞는지, 변경 이유가 빠지지 않았는지 확인합니다.
- README
- 체크사항: 프로젝트를 처음 보는 사람이 설명을 따라 설치하고 실행할 수 있는가?
- 적용 방법(스킬): 설치 조건, 실행 방법, 사용 예시를 점검 기준으로 두고 코드 변경과 README를 비교합니다. 빠진 설명을 반영한 뒤 실행 절차는 직접 따라가 봅니다.
- 릴리스 노트
- 체크사항: 사용자가 달라진 기능과 업데이트할 때 주의할 점을 알 수 있는가?
- 적용 방법(스킬): 배포 전에 변경 목록과 초안을 함께 검토합니다. 빠진 기능이나 호환성 관련 안내가 있는지, 내부 구현 설명에 치우치지 않았는지 확인합니다.
- 장애 보고서
- 체크사항: 장애의 원인과 대응 과정, 재발 방지 대책이 구체적으로 적혀 있는가?
- 적용 방법(스킬): 템플릿에 맞춰 작성한 보고서에서 타임라인과 원인 설명이 이어지는지, 재발 방지 대책에 담당자와 기한이 있는지 점검합니다. 공유 전에는 실제 기록과 직접 대조합니다.
- 기술 블로그
- 체크사항: 문제를 겪은 배경과 해결 과정이 충분히 설명돼 있는가?
- 적용 방법(훅): 글을 커밋할 때 front matter의 필수 항목과 날짜 형식, Markdown 형식을 검사합니다.
- 적용 방법(스킬): 초안을 직접 다듬은 뒤 문장 흐름, 어색하거나 과장된 표현, 설명이 부족한 부분을 검토합니다. 발행 전에는 수정한 글을 처음부터 다시 읽습니다.
- PR 설명과 코드 리뷰 코멘트
- 체크사항: 변경 이유와 검증 결과가 드러나는가? 리뷰 의견의 이유와 제안을 상대가 이해할 수 있는가?
- 적용 방법(스킬): PR 템플릿에 적은 변경 이유와 테스트 결과를 코드 변경과 비교합니다. 리뷰 코멘트는 지적의 근거와 대안이 드러나는지, 불필요하게 공격적인 표현은 없는지 점검합니다.
훅으로 형식을 검사한 뒤에도 내용은 따로 검토합니다. AI가 짚어 준 내용은 원문과 비교해 필요한 부분만 반영하고, 공유 전에는 직접 다시 읽는 것을 습관으로 삼았습니다.
출처
- 전정은, 황수정. “개발자는 글을 못 쓴다고요?”. 제이펍, 2025.
- Conventional Commits 공식 사이트
- Google SRE Book - Postmortem Culture: Learning from Failure