깃허브 README 잘 쓰는 법 — 구조와 마크다운 요령

코드를 아무리 잘 짜도 README가 비어 있으면 그 저장소는 "공사 중" 간판을 단 것과 같습니다. 특히 취업 포트폴리오라면 README가 곧 채용 담당자가 읽는 자기소개서죠. 막막할 때 그대로 따라 쓰는 표준 구조와 요령을 정리합니다.

표준 구조 — 이 순서로 쓰면 됩니다

1. # 프로젝트명 + 한 줄 소개 — 무엇이고, 왜 존재하는가. ("무료 온라인 도구 모음 — 설치 없이 브라우저에서")
2. 스크린샷 / 데모 GIF — 글보다 빠른 증명.
3. 주요 기능 — 불릿 3~6개.
4. 설치·실행 — 복사해서 바로 되는 명령어 블록. (직접 한 번 실행해 검증!)
5. 사용 예시 — 가장 흔한 사용 시나리오 하나.
6. 기술 스택 / 폴더 구조 / 라이선스 — 선택이지만 있으면 신뢰가 올라갑니다.

첫 화면 3초를 잡는 요령

• 한 줄 소개를 깎으세요 — "~~를 위한 ~~"의 20자 문장이 문단보다 강합니다.
• 이미지를 위로 — 스크린샷·데모 GIF가 스크롤 없이 보이게. 움직이는 GIF는 정적 캡처보다 시선을 오래 잡습니다.
• 배지(badge)는 양념만 — 빌드·버전 배지 한두 개는 깔끔하지만 한 줄을 넘기면 소음입니다.

포트폴리오라면 한 가지 더

• 명령어는 반드시 새 환경에서 복사-실행으로 검증 — "안 돌아가는 설치법"이 가장 큰 감점입니다.
• 커밋이 멈춘 프로젝트라면 "현재 상태와 배운 점"을 솔직하게 적는 것이 방치보다 낫습니다.

게시 전 미리보기로 검증

README가 깨지는 단골 지점은 표, 코드 블록, 중첩 목록입니다 — 문법이 한 글자만 어긋나도 모양이 무너집니다.

1. 작성한 마크다운을 미리보기 도구에 붙여 넣습니다.
2. GitHub 스타일(GFM)로 렌더링된 결과에서 표·코드 블록·목록이 의도대로인지 확인합니다.
3. 틀어진 곳을 고치고 커밋합니다 — 푸시 후 깨진 README를 발견하는 것보다 훨씬 빠릅니다.