README 정비로 팀 문서화 기준 확립

문서 작업은 항상 우선순위에서 밀린다. 기능 개발이 급하고, 버그 픽스가 급하고, 그러다 보면 README는 초기에 # Project Name 한 줄 달아놓은 채로 반년이 지난다. 그리고 그 repo를 반년 뒤에 열었을 때, README만 봐서는 뭐 하는 프로젝트인지 알 수가 없다.

이번에 README를 제대로 정리하면서 프로젝트 구조도 같이 다시 봤는데, 이 작업이 단순히 "문서 쓰기"가 아니라는 걸 다시 느꼈다. 구조를 문서화하려면 구조를 이해해야 하고, 이해하려면 다시 읽어야 하고, 읽다 보면 "이거 왜 이렇게 짰지?"가 튀어나온다. README 정비가 사실상 코드 리뷰 트리거다.

팀장 포지션이 되면 내가 직접 짠 코드보다 남이 짠 코드를 읽는 시간이 많아진다. 그 상황에서 README가 없거나 형식적으로만 존재하는 repo는 진짜 비용이다. 온보딩 때 구두로 설명해줘야 하고, 구두로 전달된 맥락은 퇴직하면 같이 사라진다. 문서가 살아있어야 팀의 지식이 사람에 종속되지 않는다.

README에 반드시 들어가야 할 것들

빠진 게 있으면 그냥 쓸모없는 문서가 된다. 최소한 이 네 가지는 있어야 한다.

## 프로젝트 개요
어떤 문제를 해결하는지 1-2줄로

## 설치 방법
복붙 가능한 명령어 위주로

## 환경 변수
| 키 | 설명 | 필수 여부 |

## 아키텍처 다이어그램
있으면 100배 이해 빠름

프로젝트 개요는 길게 쓰면 안 읽힌다. 한두 줄에 "무엇을", "왜"가 다 들어가야 한다. "이 서비스는 X 문제를 Y 방식으로 해결합니다" 수준이면 충분하다. 배경 지식 없는 사람이 읽어도 30초 안에 이게 뭔지 알 수 있어야 한다.

설치 방법은 복붙 가능한 명령어 중심으로 써야 한다. "pip install 후 환경 설정 후 실행" 이런 식으로 뭉개놓으면 결국 직접 물어봐야 하니까 문서로서의 가치가 없다. 처음 세팅하는 사람이 터미널을 열고 순서대로 따라했을 때 동작해야 한다.

환경 변수 섹션은 특히 놓치기 쉬운데, .env.example 파일 하나 있는 것보다 README에 표로 박아놓는 게 훨씬 접근성이 좋다. 어떤 키가 필수인지, 어떤 값 형식을 써야 하는지, 로컬 세팅하는 사람 입장에서 README가 첫 번째 창구니까.

아키텍처 다이어그램은 있으면 진짜 다르다. Mermaid 문법이 GitHub에서 바로 렌더링되니까 별도 이미지 파일 없이 마크다운에 박아놓을 수 있다. 간단한 서비스 플로우 하나만 있어도 코드를 읽기 전에 전체 맥락이 잡힌다. "이 요청이 어디서 들어와서 어디로 나가는지" 그림 하나가 설명 단락 열 줄보다 낫다.

한국어 vs 영어 - 상황마다 다르다

오픈소스나 외부 공개 목적이면 영어로 쓰는 게 맞다. 내부 프로젝트라도 팀원이 여럿이면 영어가 검색 효율이 좋다. GitHub에서 이슈·PR을 영어로 쓰는 팀이라면 README도 영어로 통일하는 게 자연스럽다. 코드 안의 변수명, 커밋 메시지, 이슈 제목이 영어인데 README만 한국어면 어색한 지점이 생긴다.

반대로 팀 전체가 한국어를 쓰는 내부 프로젝트라면 굳이 영어로 쓸 이유가 없다. 오히려 한국어로 써야 더 정확하게, 더 빠르게 전달되는 경우가 많다. 번역 오버헤드 없이 의도가 바로 전달된다. 선택 기준은 결국 하나다 - 누가 읽을 것인가.

이 작업으로 재확인한 개발 원칙들

README 정비가 좋은 이유 중 하나는 프로젝트를 외부인 시점에서 다시 보게 된다는 거다. 코드를 짤 때는 내 맥락이 다 있으니까 당연하게 넘어가는 것들이, 문서를 쓰다 보면 "이거 설명할 수가 없네"로 드러난다. 설명이 안 되면 설계가 애매한 거다.

이 작업을 진행하면서 재확인한 원칙들:

• 작은 커밋: 변경 단위를 작게 유지해야 코드 리뷰가 가능하고, 문제가 생겼을 때 롤백 범위도 좁아진다. 커밋이 크면 리뷰어도 피로하고 사이드 이펙트 예측이 어려워진다.
• 테스트 먼저: 변경 전 현재 동작을 파악하고, 변경 후 동일하게 동작하는지 확인한다. 테스트가 없으면 "잘 되는 것 같음"이 최선의 판단이 된다.
• 문서 동기화: 코드가 바뀌면 관련 주석과 문서도 같이 업데이트한다. 코드와 문서가 따로 노는 순간부터 문서는 거짓말을 하기 시작한다.

실패 우선 처리는 특히 API 개발할 때 차이가 난다. 정상 케이스만 설계하고 에러 핸들링을 나중으로 미루면, 나중에 에러 케이스를 끼워 넣기 위해 구조를 뜯어야 하는 상황이 온다. 처음부터 "이 함수가 실패하면 어디까지 영향이 가는가"를 생각하고 짜면 구조가 훨씬 탄탄해진다.

코드를 작성할 때 항상 세 가지 질문을 해본다.

• 미래의 나: 6개월 후에 이 코드를 다시 봤을 때 이해할 수 있는가
• 다음 개발자: 나 말고 다른 사람이 이 코드를 보면 어떻게 느낄까
• 운영 상황: 새벽 3시에 장애가 났을 때 이 코드가 문제를 빨리 파악하게 해주는가

세 번째 질문이 실용적으로 제일 유용하다. 장애 상황에서 로그를 뒤지다 보면 변수명 하나, 에러 메시지 하나의 품질이 얼마나 중요한지 체감된다. "Error occurred"가 아니라 "Failed to fetch user profile: userId=123, reason=timeout after 5000ms" 이 차이가 디버깅 시간을 반으로 줄이는 경우가 있다.

README가 없는 repo는 6개월 뒤 내가 봐도 모른다. 지금 10분 투자하면 나중에 1시간을 아낀다. 과장이 아니다. README 하나 없어서 로컬 세팅하는 데 반나절 날린 경험이 있으면, 다음 프로젝트에서는 README 먼저 쓰게 된다.

이런 작업들이 쌓이면서 시스템이 점점 견고해진다는 걸 느낀다. 당장 티가 안 나는 작업이지만, 이게 나중에 디버깅 시간을 크게 줄여준다. 기능 하나 더 추가하는 것보다, 지금 있는 기능이 다음 사람도 이해하고 운영할 수 있게 만드는 게 팀 전체의 속도를 올리는 경우가 많다. 팀장 포지션에서 느끼는 건, 개인의 생산성보다 팀의 정보 접근성이 훨씬 큰 레버리지라는 거다.