개발 직무 포트폴리오 (프로젝트·GitHub·README)

개발자 포트폴리오의 3대 축

개발 직무 포트폴리오는 세 가지 요소로 완성됩니다. 첫째는 프로젝트 자체(무엇을 만들었나), 둘째는 GitHub 저장소(코드를 어떻게 관리하나), 셋째는 README와 문서(그것을 어떻게 설명하나)입니다. 아무리 좋은 코드도 설명이 없으면 읽히지 않고, 아무리 좋은 설명도 실행되는 코드가 없으면 신뢰받지 못합니다. 세 축이 균형을 이뤄야 합니다.

어떤 프로젝트를 담을 것인가

프로젝트는 양이 아니라 질입니다. 완성도 낮은 10개보다 완결성 있는 3개가 낫습니다. 프로젝트 선정 기준은 다음과 같습니다.

• 완결성: 실제로 동작하고 배포까지 된 프로젝트. ‘만들다 만’ 프로젝트는 오히려 감점입니다.
• 직무 연관성: 백엔드 지원이면 API·DB 설계가 드러나는 프로젝트, 프론트엔드면 UI 구현·상태관리가 드러나는 프로젝트.
• 문제 정의: 튜토리얼 클론이 아니라 ‘내가 겪은 불편’을 해결하는 프로젝트가 스토리텔링에 유리합니다.
• 기여 명확성: 팀 프로젝트라면 내가 담당한 부분이 명확히 구분되는 것.

토이 프로젝트라도 ‘왜 이 기술을 선택했는가’를 설명할 수 있으면 강력합니다. 면접에서 가장 많이 나오는 질문이 바로 기술 선택의 이유입니다.

GitHub 저장소 관리 원칙

면접관은 코드보다 먼저 커밋 히스토리를 봅니다. 다음을 지키면 ‘협업 가능한 개발자’라는 인상을 줍니다.

• 의미 있는 커밋 메시지: “update”, “fix” 같은 모호한 메시지 대신 “feat: 로그인 JWT 인증 추가”처럼 목적이 드러나게.
• 일정한 커밋 단위: 하나의 커밋에 하나의 논리적 변경. 3000줄을 한 번에 커밋하지 않기.
• .gitignore 관리: node_modules, .env 등 불필요/민감 파일 제외. API 키가 커밋되어 있으면 즉시 감점.
• 브랜치 전략: 팀 프로젝트라면 feature 브랜치와 PR 흔적이 협업 능력을 증명합니다.

합격하는 README 템플릿

README는 저장소의 얼굴입니다. 방문한 면접관이 3분 안에 프로젝트를 파악할 수 있어야 합니다. 아래 템플릿을 기준으로 작성하세요.

# 프로젝트명

한 줄 소개: 이 서비스가 해결하는 문제를 한 문장으로

## 데모
- 배포 링크: https://...
- 시연 GIF 또는 스크린샷

## 주요 기능
- 기능 1 (핵심 화면 이미지)
- 기능 2

## 기술 스택
- Frontend: React, TypeScript
- Backend: Node.js, Express
- DB: PostgreSQL
- Infra: Vercel, AWS

## 아키텍처
(간단한 구조도 또는 폴더 구조)

## 내가 맡은 역할
- 검색 API 설계 및 성능 최적화

## 트러블슈팅
### 문제: 검색 응답이 평균 3.2초
- 원인: 인덱스 미설정 + N+1 쿼리
- 해결: 복합 인덱스 추가, 쿼리 개선
- 결과: 0.4초로 단축 (약 87% 개선)

## 실행 방법
git clone ...
npm install
npm run dev

이 중 트러블슈팅 섹션이 가장 중요합니다. 문제 상황, 원인 분석, 해결 방법, 수치화된 결과를 담으면 ‘스스로 문제를 해결하는 개발자’임을 증명할 수 있습니다.

좋은 예와 나쁜 예

항목	나쁜 예	좋은 예
README	“React 연습용 프로젝트” 한 줄	문제·스택·역할·트러블슈팅 구조화
커밋	“수정” 50개 연속	“feat/fix/refactor” 규칙 준수
배포	로컬에서만 실행	배포 링크 + 데모 GIF
역할	“팀 프로젝트”만 기재	“백엔드 검색 로직 담당”

면접으로 이어지는 포트폴리오

개발 포트폴리오의 진짜 목적은 ‘서류 통과’가 아니라 ‘기술 면접에서 할 이야기 준비’입니다. 면접관은 포트폴리오를 놓고 “이 부분은 왜 이렇게 구현했나요?”, “다른 방법도 있었을 텐데 왜 이걸 골랐나요?”, “성능 문제는 어떻게 확인했나요?”를 묻습니다. 즉 포트폴리오에 적은 모든 문장은 예상 질문입니다.

따라서 자신이 완전히 설명할 수 없는 내용은 적지 않는 것이 안전합니다. 남의 코드를 그대로 붙여 넣거나, 이해하지 못한 라이브러리를 “썼다”고만 적으면 면접에서 바로 드러납니다. 반대로 작은 기능이라도 “이 상황에서 A와 B를 비교했고, 트래픽 특성상 B가 유리해 선택했다”처럼 설명할 수 있으면 강력한 무기가 됩니다.

• 기술 선택의 근거를 각 프로젝트마다 1~2개씩 준비해 둡니다.
• 실패와 개선 경험을 솔직히 담습니다. 완벽함보다 성장이 더 설득력 있습니다.
• 코드 품질: 지원 전 대표 저장소의 코드를 리팩터링해 가독성을 높여둡니다.

포트폴리오는 ‘내가 면접에서 하고 싶은 이야기’를 미리 배치하는 지도입니다. 설명할 수 없는 것은 쓰지 마세요.

관련 검색어  ·  개발자 포트폴리오, README 작성법, 신입 개발자 GitHub