결제 플랫폼 README 반년치 부패 한 번에 정리

결제 플랫폼 사이드 레포 README가 반년째 방치돼 있길래 가볍게 손보려고 했음. "한 시간이면 되겠지" 싶었는데 두 시간 넘게 붙잡고 있었음. 문서가 코드보다 빨리 썩는다는 말이 진짜라는 걸 또 체감.

사실 이 레포 자체가 문제라기보단, 문서란 게 원래 그렇게 생겼음. 코드는 틀리면 빌드가 깨지고, 테스트가 빨간불 켜지고, 누군가 바로 PR 올림. 근데 문서는 틀려도 아무도 모름. 조용히 거짓말이 쌓임. 특히 결제 쪽은 환경변수 구성이 외부 서비스 연동이랑 엮여 있어서, 설치 가이드 하나가 낡으면 새 멤버가 로컬 세팅하는 데 반나절 날리는 경우가 생김. 그게 서너 번 반복되면 팀 전체가 이미 비용을 지불한 거나 마찬가지.

뭐가 문제였나

기존 README 훑어보니 이슈들이 한꺼번에 쏟아졌음.

설치 가이드의 의존성 버전이 두 단계 뒤처져 있음
"TODO" 섹션이 작년 분기 로드맵 그대로 남아있음
환경변수 목록 절반이 사라진 변수이고, 새로 생긴 변수는 누락
아키텍처 다이어그램이 파트너 연동 추가 전 버전

이 중에서 제일 골치 아팠던 건 환경변수 목록이었음. 어떤 변수는 README에 있는데 코드에 없고, 어떤 변수는 코드에서 쓰는데 문서에 없음. 둘 다 소스 오브 트루스가 아니니까 뭘 믿어야 할지 모르는 상태. 결국 코드 grep 해서 실제로 참조되는 변수 전부 뽑아서 표로 다시 정리하는 게 핵심 작업이 됐음.

다이어그램은 더 단순하게 해결했음. PNG 파일로 저장된 플로우 차트가 있었는데, 파트너 연동이 두 개 추가된 뒤로 아무도 안 건드린 상태. 이미지는 diff가 안 잡히니까 PR 리뷰에서도 묻히기 쉬움. 그래서 mermaid 텍스트로 옮기는 걸 선택함. 완전히 예쁠 필요는 없고, 틀리지만 않으면 됨.

이번에 정한 원칙

섹션마다 기준이 없으면 "넣고 싶은 것 전부 넣게" 되는 게 문제임. 그래서 이번에 손보면서 스스로 룰을 몇 개 정했음.

섹션	기준
빠른 시작	5분 안에 로컬 기동 가능해야 함
환경변수	표 형태, 필수/선택 구분, 예시값 명시
트러블슈팅	최근 6개월 안에 실제 겪은 케이스만
로드맵	분기 단위로만, 구체적 날짜 박지 않음
아키텍처	이미지 대신 mermaid, 코드와 함께 관리

트러블슈팅은 욕심내면 끝이 없는 섹션이라 "최근 6개월" 컷오프를 뒀음. 오래된 케이스는 사내 위키로 빼버림. README에 다 때려박으면 정작 찾아야 할 게 묻혀서 역효과임.

빠른 시작은 도구가 해결해야 함

기존 빠른 시작이 지나치게 친절했음. 한 줄이면 될 걸 다섯 줄로 풀어 적어놓은 상태. 예를 들어 .env 복사 방법을 세 단계로 설명해놓은 것 같은 것들. 결국 이 정도로 압축했음.

cp .env.example .env
make bootstrap
make run

이게 안 되면 README가 아니라 make 타겟을 고쳐야 한다는 결론. 문서로 우회로를 만드는 게 아니라, 도구 자체가 친절하게 되도록 하는 게 맞음. make bootstrap 하나가 의존성 설치, DB 마이그레이션, 시드 데이터 투입을 다 처리하게 만들어두면 README는 진짜 짧아져도 됨. 반대로 말하면, 빠른 시작이 길어야 한다면 그건 세팅 과정 자체가 복잡하다는 신호임.

한 가지 더 발견한 건 "예시 응답" 섹션에 실제 파트너 식별자가 그대로 박혀있었던 것. 더미값으로 교체했는데, 생각해보면 문서가 보안 구멍이 될 수 있다는 걸 이 시점에 처음으로 제대로 의식했음. API 예시, curl 샘플, 에러 로그 스니펫 같은 것들은 특히 조심해야 함. 실제 환경에서 복붙한 것들이 그대로 남아있을 가능성이 있음.