개발자도 글을 잘 써야 하는 시대

PR을 올렸는데 리뷰어한테 이런 코멘트를 받은 적 있다.

"이 PR이 왜 필요한지 모르겠어요. 설명 좀 더 요청 드립니다. "

코드는 완벽하게 짰다. 기능도 잘 돌아간다. 근데 PR 설명란에는 "버그 수정" 네 글자만 적혀 있었다. 리뷰어는 코드를 처음부터 끝까지 읽어가며 맥락을 직접 파악해야 했다. 이 상황, 한 번쯤 겪어봤을 것이다.

코드 실력과 별개로, 글쓰기가 협업의 병목이 되는 순간이다.

---

1. 코드 주석과 기술 문서 — 협업 비용을 낮추는 글쓰기

팀에서 혼자 코드를 짜는 사람은 없다. 누군가는 내가 짠 코드를 6개월 뒤에 읽는다. 그 누군가가 나 자신일 때도 많다.

함수 하나에 주석 없이 복잡한 비즈니스 로직을 구겨 넣으면, 다음 사람은 코드를 해석하는 데 30분을 쓴다. 명세서나 README가 없으면 신입 온보딩에 시니어 개발자 하루가 통째로 날아간다.

글쓰기가 필요한 순간:

• 복잡한 알고리즘이나 비직관적인 로직에 왜(Why) 를 남길 때
• API 명세나 내부 라이브러리 사용법을 팀에 공유할 때
• 레거시 코드의 배경 맥락을 문서화할 때

즉시 실천 팁:
주석을 쓸 때 무엇(What) 이 아니라 왜(Why) 를 써라. // 리스트를 정렬한다 는 코드만 봐도 안다. // 정렬 기준을 createdAt DESC로 고정한 이유: 클라이언트 캐시 정책상 순서가 바뀌면 UX 이슈 발생 이게 진짜 주석이다.

---

2. PR 설명, 회고, 포스트모템 — 팀 커뮤니케이션을 설계하는 글쓰기

코드 리뷰는 코드만 보는 자리가 아니다. 리뷰어는 왜 이렇게 바꿨는지, 어떤 대안을 고려했는지, 사이드 이펙트는 없는지 를 판단해야 한다. 이 정보를 PR 설명에 담지 않으면 리뷰 시간이 두 배로 늘어난다.

회고나 포스트모템도 마찬가지다. 장애가 났을 때 "서버가 다운됐고 재시작했다" 로 끝나는 보고서는 재발 방지에 아무 도움이 안 된다. 원인 분석 → 타임라인 → 재발 방지책까지 구조화된 글이 있어야 팀 전체가 학습한다.

글쓰기가 필요한 순간:

• PR 올릴 때 변경 배경, 구현 방식, 테스트 결과를 서술할 때
• 스프린트 회고에서 문제를 구체적으로 기술할 때
• 장애 리포트를 작성하고 공유할 때

즉시 실천 팁:
PR 설명 템플릿을 만들어라. ## 변경 이유 / ## 구현 방식 / ## 테스트 방법 세 섹션만 있어도 리뷰 품질이 달라진다. 팀에 없으면 내 PR부터 먼저 적용해봐라.

---

3. 기술 블로그 — 커리어를 스스로 증명하는 글쓰기

이직 시장에서 포트폴리오와 깃허브는 기본이 됐다. 여기에 기술 블로그가 있으면 게임이 달라진다.

면접관은 블로그를 보고 이 사람이 어떻게 생각하는지, 문제를 어떻게 분석하는지, 기술을 얼마나 깊이 이해하는지 를 확인한다. 실제로 채용 공고에 기술 블로그 우대 항목이 늘고 있다. 스택오버플로우의 2023년 개발자 설문에서 기술 글쓰기는 커리어 성장에 중요한 역량 상위 5위 안에 들었다.

블로그는 단기 성과가 아니다. 글 한 편이 구글 검색에 올라와서 매달 수백 명에게 노출된다. 이게 누적되면 인바운드 채용 제안이나 사이드 프로젝트 기회로 연결된다.

글쓰기가 필요한 순간:

• 트러블슈팅 과정을 기록할 때 (가장 높은 트래픽)
• 새로운 기술을 학습하고 정리할 때
• 프로젝트 아키텍처 결정 이유를 공유할 때

즉시 실천 팁:
처음부터 완성도 높은 글을 쓰려고 하지 마라. 오늘 겪은 에러 하나, 해결 과정, 원인을 500자로 써라. 에러 메시지 + 원인 + 해결법 구조만 갖춰도 검색 유입이 생긴다.

---

4. AI 프롬프트 작성 — 2025년에 새로 생긴 글쓰기 역량

ChatGPT, Claude, Cursor를 쓰는 개발자는 이미 많다. 그런데 같은 도구를 써도 결과물 품질이 다르다. 차이는 프롬프트다.

"이 코드 리팩토링해줘" 와 "이 코드는 Python 3.11 기반이고, 현재 O(n²) 복잡도인데 O(n log n) 이하로 개선해줘. 외부 라이브러리는 사용하지 말고, 기존 테스트 코드는 그대로 통과해야 해" 의 결과물은 다르다.

AI에게 좋은 결과를 뽑으려면 맥락을 명확하게 전달해야 한다. 제약 조건, 목적, 형식, 예외 상황을 글로 구조화하는 능력이 곧 AI 활용 능력이다. 이건 기존 글쓰기 역량과 정확히 연결된다.

글쓰기가 필요한 순간:

• 코드 생성, 리뷰, 리팩토링 요청을 AI에 맡길 때
• AI로 기술 문서 초안을 뽑을 때
• 팀 내 프롬프트 가이드를 만들어 공유할 때

즉시 실천 팁:
프롬프트를 쓸 때 역할 + 맥락 + 제약 + 출력 형식 네 가지를 넣어라. 이 구조를 파일로 저장해두고 반복 사용하면 AI 활용 생산성이 눈에 띄게 달라진다.

---

정리

영역	핵심 상황	즉시 실천 팁
코드 주석 / 기술 문서	협업, 온보딩, 레거시 파악	What 말고 Why 를 써라
PR / 회고 / 포스트모템	코드 리뷰, 장애 대응, 스프린트	PR 설명 3섹션 템플릿 만들기
기술 블로그	이직, 브랜딩, 인바운드 기회	트러블슈팅 500자부터 시작
AI 프롬프트	코드 생성, 문서 작성, 자동화	역할+맥락+제약+형식 구조화

---