상담 신청
홈 › 작업 노트 › 개발 › 깃허브 저장소 첫 화면 README 정리하기

개발 · 점검 노트

깃허브 저장소 첫 화면 README 정리하기

포트폴리오 링크를 눌러 깃허브 저장소에 들어가면 파일 목록 아래로 README가 보입니다. 이 부분이 비어 있거나 엔진이 만든 기본 문구만 있다면, 방문자는 폴더 이름만 보고 무슨 프로젝트인지 추측해야 합니다. README는 저장소의 표지이자 사용 설명서입니다. 처음 들어온 사람의 눈으로 위에서부터 점검해 봅니다.

작업 노트 415 · 읽는 시간 약 4분 · 2026.11.17 정리

맨 위 세 줄: 이름, 한 줄 소개, 대표 이미지

README 맨 위에는 게임 이름과 한 줄 소개를 둡니다. 한 줄 소개는 장르와 핵심 재미를 담아 무엇을 하는 게임인지 바로 알 수 있게 씁니다. 그 아래에 대표 화면이나 짧은 움직이는 이미지를 하나 넣습니다. 방문자는 스크롤을 내리기 전에 이 세 가지로 계속 볼지 결정합니다. 점검할 때는 저장소를 처음 연 화면에서 스크롤 없이 이 셋이 다 보이는지 확인합니다.

이미지가 깨지는 문제가 자주 생깁니다. 내 컴퓨터의 파일 경로를 그대로 적었거나, 이미지를 저장소에 올리지 않은 경우입니다. 이미지는 저장소 안의 별도 폴더에 넣고 README에서는 그 폴더 기준 경로로 연결합니다. 다른 컴퓨터나 시크릿 창에서 저장소를 열어 이미지가 보이는지 꼭 확인합니다.

저장소 오른쪽의 소개 칸도 함께 채웁니다. 짧은 설명과 주제 태그, 플레이 영상이나 문서 링크를 넣어 둘 수 있습니다. 저장소 목록에서 내 프로필을 훑어보는 사람은 README를 열기 전에 이 소개 문구를 먼저 봅니다. 비어 있으면 저장소가 정리되지 않은 인상을 줍니다.

실행 방법: 처음 받은 사람이 따라 할 수 있는가

두 번째로 중요한 것은 실행 방법입니다. 빌드 파일을 바로 받아 실행할 수 있게 하려면 저장소의 릴리스 기능에 실행 파일 묶음을 올려 두고, README에서 그 위치를 안내합니다. 소스를 받아 엔진에서 열어야 한다면 엔진 이름과 버전, 처음 열 씬, 필요한 패키지를 적습니다. 버전이 다르면 열리지 않거나 경고가 쏟아지는 경우가 있어서 버전 표기는 빠뜨리지 않습니다.

조작 방법도 짧게 적습니다. 이동, 공격, 메뉴 같은 핵심 조작키를 표나 목록으로 정리하면 됩니다. 테스트를 쉽게 하려고 만든 단축키, 예를 들어 바로 보스 방으로 가는 키가 있다면 함께 적어 둡니다. 검토자가 끝까지 플레이할 시간이 없을 때 핵심 장면을 빨리 볼 수 있게 도와줍니다.

이 항목을 점검하는 가장 확실한 방법은 다른 컴퓨터에서 README만 보고 처음부터 따라 해 보는 것입니다. 내 컴퓨터에서는 당연했던 설정이 빠져 있는 경우가 대부분 이 단계에서 드러납니다. 따라 하다 막힌 곳이 있으면 그 자리에 한 줄을 더하는 식으로 고칩니다.

게임프로그래밍 수업에서 다루는 작업 예시
게임프로그래밍 수업에서 다루는 작업 예시

구현 내용: 무엇을 만들었고 어디에 있는가

다음에는 구현한 핵심 기능을 서너 개 적습니다. 기능 이름만 나열하기보다 한두 문장으로 어떻게 만들었는지 덧붙이고, 해당 코드가 있는 파일로 링크를 겁니다. 적 AI는 상태 머신으로 대기, 추격, 공격, 복귀를 나눴다는 설명 옆에 그 스크립트 파일 링크가 있으면, 관심 있는 사람이 바로 코드로 넘어갈 수 있습니다.

폴더 구조도 간단히 설명합니다. 스크립트, 프리팹, 씬, 데이터 폴더가 각각 무엇을 담고 있는지 한 줄씩 적어 두면, 처음 보는 사람이 파일 목록 속에서 길을 잃지 않습니다. 폴더 이름과 설명이 맞지 않거나 쓰지 않는 폴더가 남아 있다면 이 기회에 정리합니다.

팀 프로젝트라면 역할 분담을 적습니다. 팀원 이름과 맡은 부분, 내가 담당한 기능과 그 폴더를 분명히 표시합니다. 포트폴리오로 제출할 때는 내가 작업한 부분이 어디인지 검토자가 바로 찾을 수 있어야 합니다. 개인 저장소로 옮겨 올렸다면 원래 팀 저장소와의 관계도 짧게 밝혀 둡니다.

있으면 좋은 것과 빼는 편이 나은 것

있으면 좋은 것은 개발 기간과 사용 기술, 기술 문서나 플레이 영상 링크, 앞으로 고치고 싶은 점입니다. 사용 기술은 엔진, 언어, 버전 관리 도구 정도로 짧게 적습니다. 고치고 싶은 점을 적어 두면 프로젝트를 객관적으로 본다는 인상을 줍니다. 외부 에셋이나 폰트를 썼다면 출처와 라이선스 표기도 꼭 넣습니다.

빼는 편이 나은 것도 있습니다. 엔진이나 템플릿이 자동으로 만든 기본 README 문구, 개발 중에 쓴 할 일 메모, 지나치게 긴 개발 일지 전체입니다. 개발 일지는 별도 문서로 빼고 README에는 링크만 둡니다. README가 너무 길면 정작 중요한 실행 방법과 핵심 기능이 묻힙니다.

말투와 언어도 정합니다. 지원하는 회사가 국내라면 한국어로 쓰는 것이 자연스럽고, 해외 지원도 고려한다면 핵심 부분만 영어를 함께 적는 방법도 있습니다. 어느 쪽이든 한 문서 안에서 말투가 섞이지 않게 맞춥니다. 기술 용어는 처음 나올 때만 짧게 풀어 쓰고, 같은 대상을 가리키는 말은 문서 끝까지 하나로 통일합니다. 플레이어를 캐릭터, 주인공, 유저로 번갈아 부르면 읽는 사람이 서로 다른 것인지 헷갈립니다.

게임프로그래밍 과정에서 만드는 결과물 예시
게임프로그래밍 과정에서 만드는 결과물 예시

공개 전 README 점검표

  • 스크롤 없이 게임 이름, 한 줄 소개, 대표 이미지가 보이는가
  • 다른 컴퓨터에서 README만 보고 실행까지 따라 할 수 있는가
  • 엔진 이름과 버전, 처음 열 씬이 적혀 있는가
  • 핵심 기능마다 코드 파일로 가는 링크가 있는가
  • 팀 프로젝트라면 내 역할과 담당 폴더가 표시되어 있는가
  • 외부 에셋과 폰트의 출처가 적혀 있는가

여섯 항목을 다 채웠다면 마지막으로 휴대폰으로 저장소를 열어 봅니다. 채용 담당자가 이동 중에 링크를 열어 보는 경우도 있어서, 작은 화면에서 이미지와 표가 깨지지 않는지 확인해 두면 좋습니다. README는 한 번 쓰고 끝내는 문서가 아니라 프로젝트가 바뀔 때마다 함께 고치는 문서라는 점도 기억해 둡니다.

저장소를 포트폴리오로 내놓기 전에 다른 사람의 눈으로 점검받고 싶다면, SBS아카데미게임학원 게임프로그래밍 과정 무료 상담에 저장소 링크를 가져와 README와 코드 정리 상태를 함께 확인해 보세요.

자주 묻는 질문

README를 꾸미는 배지나 장식이 필요할까요?

필수는 아닙니다. 빌드 상태처럼 실제 정보를 담은 배지는 도움이 되지만, 장식이 많아지면 핵심 내용이 묻힐 수 있어 최소한으로 쓰는 편이 좋습니다.

비공개 저장소로 두고 링크만 줘도 되나요?

비공개 저장소는 검토자가 볼 수 없으니 공개로 전환하거나 별도 접근 방법을 안내해야 합니다. 공개하기 전에는 비밀 정보가 들어 있지 않은지 꼭 확인하세요.

게임프로그래밍 수업 예시
이 글과 이어지는 과정게임프로그래밍 과정 안내

수업 순서, 목표별 결과물, 가까운 센터를 한 페이지에서 볼 수 있습니다.

과정 보기 →

함께 읽으면 좋은 노트

무료 상담 신청

읽은 글과 관련해 궁금한 점이나 지금 상황을 남기면 담당자가 연락드립니다.

상담·컨설팅 무료 · 전화 상담 010-2135-9730

전화상담 신청