이커머스 PG 플랫폼 성과를 상단으로 올려 GitHub 프로필 가독성 개선

GitHub 프로필 README를 또 손댔다. 이번엔 이커머스 PG 플랫폼 Sprint highlight를 by-the-numbers 섹션 위로 올렸는데, 작은 변경처럼 보여도 이게 꽤 오래 고민한 결과다.

총괄 팀장 포지션으로 일하다 보면 스스로를 소개하는 방식이 계속 달라진다. 주니어 때는 "어떤 기술 쓸 줄 아냐"가 중요했다면, 지금은 "어떤 문제를 어느 규모에서 해결했냐"가 훨씬 더 중요하다. 그 관점의 변화가 프로필에도 반영되어야 한다고 생각해서 계속 다듬는 중.

정보 순서가 곧 메시지다

채용 담당자든 협업 제안자든 GitHub 프로필을 처음 열었을 때 실제로 스크롤을 얼마나 내려볼까. 솔직히 안 내려본다고 봐야 한다. 대략 5초 안에 "이 사람 어떤 개발자인지"에 대한 판단이 끝난다. 그러니 "뭘 할 수 있냐"보다 "뭘 해봤냐"가 먼저 눈에 들어와야 한다.

기존 구조는 by-the-numbers, 즉 커밋 수, 스타 수, 기여 그래프 같은 범용 통계가 위에 있었다. 그 아래에 PG 플랫폼 Sprint 성과가 놓여 있었는데, 문제는 저 통계들이 컨텍스트 없이는 아무 의미가 없다는 점이다. 커밋 1000개가 인상적인지 아닌지는 뭘 만들었냐를 알고 나서야 판단할 수 있으니까. 순서가 반대였던 거다.

바꾸고 나서 흐름:

• PG 플랫폼 Sprint highlight (뭘 만들었는지, 어떤 문제를 풀었는지)
• by-the-numbers (개발 활동 규모와 패턴)
• 기술 스택 (사용하는 도구 목록)

도메인 → 규모 → 수단 순서가 읽는 사람의 인지 흐름에 맞다. 반대 순서면 마지막까지 읽어야 핵심이 나온다. 읽는 사람한테 그 수고를 강요하면 안 된다.

추상적인 표현보다 수치 기반 성과를 먼저 보여주는 것도 같은 맥락이다. "결제 성능을 크게 개선했다"와 "결제 응답 17.8s → 0.12s" 중 어느 쪽이 임팩트가 더 빠르게 전달되는지는 말할 것도 없다. 수치가 있으면 읽는 사람이 스스로 판단할 수 있고, 수치가 없으면 쓴 사람의 주관을 그냥 믿어야 한다. 이 차이가 시니어, 특히 팀장급에서는 더 뚜렷하게 드러난다. 역할이 높을수록 "내가 직접 코딩했다"보다 "이 문제를 이 규모에서 해결했다"는 증거가 더 설득력 있다.

<details> 토글로 정보 밀도 문제 풀기

README가 길어지는 가장 큰 이유는 "다 보여주고 싶어서"다. 근데 다 보여주면 아무것도 안 읽힌다. 스크롤 두 번이면 이미 집중력이 분산된다.

이걸 해결하는 방법 중에 GitHub 렌더러가 지원하는 HTML <details> 태그가 꽤 유용하다. GitHub은 Markdown 안에 HTML 서브셋을 허용하는데, <details> / <summary> 콤보가 그 안에 포함된다.

<details>
<summary>이커머스 PG 플랫폼 Sprint 상세 내역</summary>

- 결제 플로우 응답 시간: 17.8s → 0.12s
- 정산 배치 처리 안정화
- 멀티 PG사 추상화 레이어 설계 및 구현

</details>

이렇게 구성하면 첫 화면에는 summary 텍스트만 노출되고, 관심 있는 사람만 클릭해서 상세를 본다. 정보를 감추는 게 아니라 읽을 의향이 있는 사람한테만 보여주는 방식이다. 스캔 단계에서 판단하고, 관심 생기면 파고드는 구조.

주의할 점이 하나 있다. <details> 안쪽에서 마크다운 파싱이 제한적이라는 것. 중첩 목록이나 코드 블록, 헤딩 태그가 GitHub 렌더러 버전에 따라 가끔 깨진다. 특히 모바일 GitHub 앱에서 렌더링이 틀어지면 더 어색해 보여서, 토글 안쪽은 최대한 단순한 구조로 유지하는 편이 안전하다고 느꼈음.

배지와 카드, 적당한 양이 있다

배지(badge)는 양날의 검이다. 잘 쓰면 한눈에 기술 스택이 들어오는데, 과하면 "이것저것 많이 써봤어요" 광고판이 된다. 배지 20개 달아놓은 프로필을 보면 오히려 신뢰가 안 간다. 뭘 진짜로 잘 하는지 모르겠으니까.

현재 핵심 기술 5-7개만 노출하고 있다. 선택 기준은 간단하다. 현재 실제로 쓰는 것, 그리고 다음 역할에서도 쓸 것. 3-5년 전에 썼던 기술이나 사이드 프로젝트 한 번만 써본 스택은 굳이 배지로 달 이유가 없다.

GitHub Stats 카드 같은 자동 생성 카드도 마찬가지다. 기여 그래프가 초록 가득이면 인상적이긴 한데, 그게 실제 프로덕트 임팩트랑 반드시 비례하지는 않는다. 카드 한두 개면 충분하고, 화면 절반을 통계 카드로 채우는 건 피하게 됐다. 팀장 포지션에서는 코드 양보다 어떤 결정을 했고 어떤 성과를 냈냐가 더 중요한 신호인데, 커밋 히트맵은 그걸 보여주지 못한다.

GitHub 프로필 README는 이력서랑 달리 언제든 고칠 수 있어서 오히려 방치하기가 쉽다. 근데 방치한 프로필은 금방 티가 난다. 6개월 된 "최근 프로젝트"나 이미 떠난 회사 정보가 그대로 남아 있으면, 자기 커리어를 얼마나 관리하는 사람인지에 대한 신호가 된다. 반기에 한 번이라도 읽어보고 낡은 정보를 솎아내는 게 필요하다. 이번처럼 섹션 순서 하나 바꾸는 작업도, 읽히는 순서가 달라지고 첫인상이 달라지니까 충분히 의미 있는 변경이었다.