주니어 개발자 포트폴리오 README, 무엇을 써야 할까

01 README가 먼저 설명해야 할 것

README 첫 부분에는 프로젝트 이름보다 이 프로젝트가 어떤 문제를 다루는지 먼저 보여주는 편이 좋습니다. 채용 담당자나 면접관은 저장소를 처음 열었을 때 결과 화면, 핵심 기능, 본인 역할을 빠르게 파악하려고 합니다.

따라서 첫 문단에는 프로젝트 목적, 주요 사용자, 해결하려는 문제, 최종 결과물 형태를 짧게 정리해야 합니다. 기술 스택을 맨 위에 길게 나열하기보다 왜 이 프로젝트를 만들었고 무엇을 확인할 수 있는지 먼저 쓰는 편이 읽기 쉽습니다.

개발 부트캠프를 볼 때는 과정명보다 직무 연결성, 프로젝트 결과물, 피드백 구조를 먼저 봐야 합니다.

02 필수로 들어갈 항목

README에는 프로젝트 개요, 핵심 기능, 사용 기술, 실행 방법, 배포 링크, 화면 예시, 폴더 구조, 본인 기여 범위가 들어가야 합니다. 실행 방법은 설치 명령어, 환경 변수, 로컬 실행 순서, 테스트 방법을 분리해 적어야 합니다.

배포 링크가 있다면 GitHub 링크와 함께 배치하고, 배포가 없다면 주요 화면 캡처나 짧은 GIF로 결과를 확인할 수 있게 해야 합니다. 팀 프로젝트라면 전체 기능을 모두 본인 성과처럼 쓰지 말고, 본인이 맡은 기능과 의사결정 범위를 따로 적는 것이 안전합니다.

폴더 구조는 모든 파일을 길게 나열하기보다 주요 디렉터리가 어떤 역할을 하는지만 설명하면 충분합니다.

03 주니어에게 중요한 설명 방식

주니어 포트폴리오에서 중요한 것은 기술을 많이 썼다는 사실보다 문제를 어떻게 쪼개고 해결했는지입니다. 예를 들어 React를 사용했다면 컴포넌트 분리 기준, 상태 관리 방식, API 연동 흐름, 예외 상황 처리 방식을 설명해야 합니다.

백엔드 프로젝트라면 API 설계, 데이터베이스 구조, 인증 흐름, 예외 처리, 배포 환경을 어떤 기준으로 정했는지 보여주는 편이 좋습니다. 완성된 기능만 쓰면 결과 보고서처럼 보일 수 있습니다. 막혔던 문제, 선택한 대안, 수정한 이유를 함께 적어야 면접 질문으로 이어지기 좋습니다.

README 문장은 과장보다 확인 가능한 표현이 낫습니다. '완벽한 서비스'보다 '회원가입, 로그인, 게시글 작성, 검색 기능을 구현했다'처럼 기능 단위로 적어야 합니다.

04 팀 프로젝트 README에서 나눌 것

팀 프로젝트는 공통 README와 개인 포트폴리오 설명을 분리해서 준비하는 편이 좋습니다. 공통 README에는 서비스 개요, 팀원, 기술 스택, 전체 기능, 실행 방법을 넣고, 개인 설명에는 맡은 기능과 해결한 문제를 중심으로 정리합니다.

내가 작성하지 않은 코드까지 모두 설명하려고 하면 오히려 면접에서 답변이 흐려질 수 있습니다. 본인 기여 범위에는 담당 화면, API, 데이터 구조, 테스트, 배포, 문서화 중 실제로 맡은 항목만 적어야 합니다.

협업 과정에서 남긴 이슈, PR, 코드 리뷰 기록이 있다면 링크로 연결하면 신뢰도가 올라갑니다.

05 제출 전 점검

README를 제출하기 전에는 처음 보는 사람이 3분 안에 프로젝트 목적과 핵심 기능을 이해할 수 있는지 확인해야 합니다. 링크가 깨지지 않는지, 이미지가 보이는지, 로컬 실행 명령어가 현재 코드와 맞는지 다시 확인합니다.

기술 스택 배지는 보기에는 좋지만 설명을 대신하지 못합니다. 각 기술을 왜 사용했는지 한두 문장으로 설명할 수 있어야 합니다. 마지막으로 README와 이력서 문장이 서로 맞는지 확인해야 합니다. 이력서에는 주요 성과를 짧게 쓰고, README에는 그 근거와 구현 과정을 더 자세히 남기는 구조가 좋습니다.

프로젝트형 학습을 고를 때도 README와 결과물 설명까지 이어지는 피드백이 있는지 확인하면 수료 후 정리 부담을 줄일 수 있습니다.

06 확인한 내용을 기록하는 방법

최종 결정 전에 과정명, 공식 URL, 확인 날짜, 모집 회차, 비용 관련 조건, 프로젝트 방식, 피드백 범위를 한 줄씩 남겨두면 좋습니다. 나중에 다시 비교할 때는 인상이나 후기보다 같은 기준으로 적어둔 항목이 더 도움이 됩니다.

특히 취업 준비 과정은 시간이 지나며 모집 조건과 운영 방식이 바뀔 수 있으므로, 확인 날짜를 함께 적어두는 것이 중요합니다. 기록할 때는 공개 페이지에서 확인한 내용과 상담을 통해 확인한 내용을 분리해야 합니다. 공개 페이지에 있는 정보는 출처 링크와 함께 남기고, 상담에서 들은 조건은 날짜와 질문 내용을 함께 적어야 나중에 혼동이 줄어듭니다.

여러 후보를 비교한다면 같은 열로 정리해야 합니다. 커리큘럼, 프로젝트, 피드백, 수료 후 지원, 비용 관련 조건, 모집 일정이 같은 순서로 놓이면 광고 문구보다 실제 차이가 더 잘 보입니다.

07 신청 전 마지막 점검

주니어 개발자 포트폴리오 README는 검색한 상태라면 지금 필요한 것이 개념 정리인지, 과정 선택인지, 결과물 보완인지 먼저 구분해야 합니다. 개발 취업 준비자에게 중요한 것은 많은 정보를 한 번에 보는 것이 아니라, 현재 수준에서 다음 행동으로 이어지는 기준을 남기는 일입니다.

공식 페이지에서 확인한 내용과 본인이 실제로 확보할 수 있는 학습 시간을 같이 적어두면, 후기나 광고 문구에 흔들리지 않고 선택지를 줄일 수 있습니다.

자주 묻는 질문