휴가 뒤 묵은 자바스크립트 프로젝트를 포트폴리오로 되살리는 과정

• 목록
• 답변
• 글쓰기
• 옵션
  • 수정
  • 삭제

멈춘 프로젝트에서 살릴 가치부터 찾아냅니다

완성도가 아니라 설명할 문제를 봅니다

여름휴가가 끝난 뒤 저장소를 열면 미완성 기능과 오래된 할 일 목록부터 눈에 들어옵니다. 하지만 개발자 포트폴리오에 필요한 것은 모든 기능이 완벽한 대형 서비스가 아닙니다. 어떤 문제를 발견했고, 자바스크립트로 어떻게 해결했으며, 결과를 무엇으로 확인했는지가 명확한 프로젝트가 더 설득력 있습니다.

먼저 README, 커밋 기록, 이슈, 배포 주소를 차례로 확인해 프로젝트의 현재 상태를 한 문장으로 적어 보세요. 예를 들어 ‘지역 행사 정보를 저장하고 날짜별로 거르는 웹 앱’처럼 사용자와 기능이 함께 드러나야 합니다. 포트폴리오라는 개념의 범위가 모호하다면 포트폴리오 용어 정의를 참고해 결과물과 역량 증거를 구분하는 것도 좋습니다.

• 유지: 지금도 정상 작동하며 프로젝트 목적을 보여 주는 기능
• 수정: 핵심 흐름을 방해하지만 짧은 시간 안에 고칠 수 있는 오류
• 제외: 목적과 무관하거나 설명 비용만 키우는 실험 기능
• 증명: 화면, 테스트, 수치 또는 커밋으로 보여 줄 수 있는 성과

살릴 프로젝트는 기능이 가장 많은 저장소가 아니라, ‘왜 만들었는가’를 30초 안에 설명할 수 있는 저장소입니다.

첫날에는 실행 환경을 다시 세웁니다

새 컴퓨터에서도 재현되는지 확인합니다

오래 멈춘 자바스크립트 프로젝트는 코드보다 실행 환경에서 먼저 막힙니다. Node.js 버전이 달라졌거나 환경변수 이름이 기억나지 않고, 사라진 API 때문에 첫 화면조차 열리지 않을 수 있습니다. 기존 로컬 폴더를 그대로 믿지 말고 저장소를 새로운 디렉터리에 복제한 뒤 설치부터 실행까지 다시 진행해야 방문자의 조건을 현실적으로 확인할 수 있습니다.

package.json의 scripts에는 최소한 개발 서버, 빌드, 테스트 명령을 분명히 넣으세요. Node.js 버전은 .nvmrc나 engines 필드로 고정하고, 비밀값이 없는 .env.example을 제공합니다. npm, pnpm, yarn 가운데 실제 사용한 패키지 관리자 하나만 안내해야 잠금 파일 충돌을 피할 수 있습니다.

1. 깨끗한 환경에서 저장소를 복제하고 문서의 명령만 따라 실행합니다.
2. 설치 경고와 빌드 오류를 별도 이슈로 기록합니다.
3. 필수 환경변수에는 용도와 발급 위치를 설명합니다.
4. 리눅스와 주요 데스크톱 환경에서 줄바꿈·경로 차이를 점검합니다.
5. 처음 실행하는 사람이 10분 안에 화면을 볼 수 있는지 측정합니다.

둘째 날에는 의존성을 안전하게 정돈합니다

무조건 최신보다 작은 변경이 낫습니다

몇 달 쉬었던 프로젝트에서 모든 패키지를 한꺼번에 최신 버전으로 올리면 오류의 원인을 찾기 어려워집니다. 먼저 감사 명령과 변경 이력을 확인하고, 보안 위험이 크거나 배포를 막는 의존성부터 작은 묶음으로 갱신하세요. 각 묶음마다 테스트와 빌드를 실행하면 어느 변경이 문제를 만들었는지 빠르게 추적할 수 있습니다.

프레임워크의 메이저 버전 전환은 포트폴리오의 목적과 비용을 함께 따져야 합니다. 채용 담당자에게 현대적인 설계를 보여 줄 필요가 있고 공식 마이그레이션 경로가 분명하다면 가치가 있습니다. 반면 데모 복구가 목표인데 전면 전환에 주말 전체가 필요하다면 현재 버전을 유지하고 제한 사항을 문서화하는 편이 정직합니다.

• 즉시 처리: 실제 공격 경로가 있으며 런타임에 포함되는 심각한 취약점
• 계획 처리: 호환성 검토가 필요한 프레임워크·빌드 도구의 메이저 업데이트
• 제거 검토: 코드에서 더 이상 import하지 않는 라이브러리와 중복 유틸리티
• 기록: 업데이트 전후 번들 크기, 테스트 결과, 주요 변경 이유

자동 수정 명령의 성공 메시지만으로 안전하다고 판단해서는 안 됩니다. 실제 실행 경로와 배포 환경을 확인하고, 잠금 파일도 함께 커밋해야 다른 사람이 같은 의존성을 설치할 수 있습니다.

셋째 날에는 핵심 사용자 흐름만 완성합니다

기능을 더하기 전에 한 경로를 닫습니다

오래된 사이드 프로젝트를 되살릴 때 가장 흔한 실패는 새 기능부터 추가하는 것입니다. 포트폴리오 방문자는 여러 메뉴를 오래 탐색하지 않습니다. 첫 화면에서 목적을 이해하고, 대표 행동을 수행한 뒤, 결과나 오류 메시지를 확인할 수 있는 하나의 완결된 사용자 흐름이 먼저 필요합니다.

할 일 관리 앱이라면 가입, 할 일 생성, 상태 변경까지를 핵심 경로로 정할 수 있습니다. 영화 검색 앱이라면 검색어 입력, 결과 필터링, 상세 정보 확인이 한 묶음입니다. 이 경로와 직접 관련되지 않는 소셜 로그인, 테마 선택, 복잡한 관리자 화면은 후속 작업으로 옮기세요. 범위를 줄였다는 사실도 우선순위 판단 능력을 보여 주는 좋은 프로젝트 기록입니다.

1. 사용자가 도착한 뒤 수행할 대표 행동 하나를 선택합니다.
2. 로딩, 빈 결과, 성공, 실패 상태를 각각 구현합니다.
3. 모바일 화면에서도 같은 행동을 끝낼 수 있게 조정합니다.
4. 오류 메시지에 원인과 다음 행동을 함께 적습니다.
5. 완료 기준을 이슈에 남기고 관련 커밋을 연결합니다.

여기서 스스로 물어볼 질문은 간단합니다. “링크를 처음 받은 사람이 설명 없이도 성공 상태까지 갈 수 있는가?” 답이 아니라면 버튼 문구와 입력 안내부터 고쳐야 합니다. 화려한 애니메이션보다 예측 가능한 흐름이 소프트웨어 프로젝트의 완성도를 더 직접적으로 전달합니다.

넷째 날에는 전후 차이를 측정 가능한 기록으로 바꿉니다

회고에는 결정과 근거를 함께 남깁니다

‘성능을 개선했다’거나 ‘코드를 리팩터링했다’는 문장만으로는 작업의 깊이를 판단하기 어렵습니다. 변경 전후의 초기 로딩 시간, 번들 크기, 실패 테스트 수, 접근성 오류 수처럼 다시 확인할 수 있는 지표를 남기세요. 숫자가 크지 않아도 측정 조건과 도구가 투명하면 충분히 가치 있는 프로젝트 증거가 됩니다.

예를 들어 목록 렌더링이 느렸다면 데이터 개수, 사용 기기, 측정 위치를 적고 개선 전후를 나란히 제시합니다. 숫자를 얻지 못한 설계 결정은 대안 비교로 보완할 수 있습니다. 상태 관리 라이브러리를 추가하지 않은 이유, 서버 렌더링 대신 정적 배포를 선택한 이유처럼 선택하지 않은 것까지 설명하면 판단 과정이 드러납니다.

• 문제: 사용자가 겪은 현상과 재현 조건
• 가설: 원인으로 추정한 코드 또는 네트워크 구간
• 행동: 적용한 수정과 검토했던 다른 선택지
• 결과: 같은 조건에서 측정한 전후 값
• 한계: 아직 검증하지 못했거나 다음에 개선할 부분

작업 전후 화면을 캡처하되 이미지에만 정보를 가두지 말고 텍스트 설명도 붙이세요. 포트폴리오를 결과물의 선별과 표현이라는 관점에서 이해하려면 포트폴리오의 의미와 활용도 참고할 수 있습니다.

다섯째 날에는 README를 짧은 사례 연구로 고칩니다

설치 설명보다 먼저 프로젝트의 맥락을 보여 줍니다

README 첫 화면이 배지와 설치 명령으로만 채워져 있으면 프로젝트를 만든 이유가 뒤로 밀립니다. 상단에는 해결하려던 문제, 주요 사용자, 대표 기능, 라이브 데모 링크를 배치하세요. 이어서 기술 선택의 이유와 성과를 설명하면 개발자가 아닌 방문자도 프로젝트의 가치를 이해할 수 있습니다.

기술 스택은 로고를 나열하는 것으로 끝내지 않는 편이 좋습니다. React를 사용했다면 컴포넌트 분리가 어떤 유지보수 문제를 줄였는지, Express를 선택했다면 API 구조와 배포 환경에 왜 적합했는지 연결해 쓰세요. 도구 이름보다 선택의 맥락이 개발자의 사고방식을 더 선명하게 보여 줍니다.

• 한 문장으로 쓴 프로젝트 소개와 실제 사용 대상
• 대표 화면으로 바로 이동하는 데모 및 저장소 링크
• 세 가지 이내로 압축한 핵심 기능
• 구조도 또는 주요 데이터 흐름에 대한 짧은 설명
• 재현 가능한 설치·실행·테스트 명령
• 알려진 제한 사항과 다음 개선 후보

README를 쓴 뒤 처음 보는 동료에게 1분만 보여 주세요. 프로젝트 목적을 다르게 이해했다면 코드를 고치기 전에 첫 세 문장을 고치는 편이 빠릅니다.

여섯째 날에는 공개 전 품질과 개인정보를 검사합니다

배포 링크가 신뢰를 잃지 않게 만듭니다

가을 채용 시즌을 앞두고 급히 공개하면 API 키, 실제 이메일 주소, 테스트 계정의 개인정보가 저장소에 남을 수 있습니다. 현재 파일에서 값을 지우는 것만으로는 과거 커밋이 사라지지 않습니다. 노출된 키는 즉시 폐기하고 재발급하며, Git 기록과 배포 플랫폼의 환경변수도 함께 확인해야 합니다.

품질 점검에서는 데스크톱의 정상 화면만 보지 마세요. 느린 네트워크, 모바일 너비, 키보드 이동, 잘못된 URL, API 실패를 직접 재현해야 합니다. 데모가 외부 무료 API에 의존한다면 호출 제한과 장애 시 대체 메시지를 표시하세요. 테스트용 데이터는 실제 인물과 혼동되지 않는 가상 정보로 교체하는 것이 안전합니다.

1. 저장소와 커밋 기록에서 비밀값·개인정보 흔적을 검색합니다.
2. 모든 외부 링크를 시크릿 창에서 열어 권한 문제를 확인합니다.
3. 키보드만으로 대표 흐름을 수행하고 포커스 표시를 점검합니다.
4. 404 페이지와 API 실패 상태에 복구 행동을 제공합니다.
5. 모바일 두 가지 너비에서 텍스트 겹침과 버튼 크기를 확인합니다.
6. 라이선스와 사용한 오픈소스·외부 데이터의 출처를 표기합니다.

공개 포트폴리오는 단순한 전시물이 아니라 실제 운영되는 소프트웨어입니다. 작은 오류를 숨기기보다 알려진 문제와 대응 계획을 적어 두면 프로젝트를 책임 있게 관리한다는 인상을 줄 수 있습니다.

일주일 만에 어디까지 공개해야 할까요

완벽한 버전이 아니라 검증 가능한 버전을 공개합니다

가장 자주 생기는 고민은 “아직 부족한데 지금 공개해도 되는가?”입니다. 답은 핵심 흐름이 작동하고, 설치 또는 데모 접근이 가능하며, 남은 한계를 솔직히 표시했다면 공개해도 된다는 것입니다. 반대로 로그인부터 막히거나 비밀값 노출 가능성이 있고 주요 설명이 사실과 다르다면 하루를 더 써서 고쳐야 합니다.

일주일의 목표는 거대한 리뉴얼이 아니라 면접에서 깊게 설명할 수 있는 최소 공개 버전입니다. 배포 후에는 방문 분석 숫자만 바라보기보다 실제로 받은 질문을 기록하세요. “왜 이 라이브러리를 선택했나요?”라는 질문이 반복되면 README의 기술 결정 부분을 보강하고, 데모 사용법을 묻는 사람이 많다면 첫 화면 안내를 수정하면 됩니다.

• 바로 공개: 핵심 경로, 오류 처리, README, 데모 링크가 정상인 상태
• 조건부 공개: 일부 기능이 미완성이지만 제한 사항과 대체 흐름이 분명한 상태
• 공개 보류: 보안 위험, 개인정보 노출, 반복되는 치명적 오류가 있는 상태
• 다음 주 작업: 사용자 질문을 바탕으로 문서와 대표 흐름을 한 번씩 개선

공개 시점에는 태그나 릴리스 이름을 붙여 기준점을 남겨 두세요. 이후 기능을 추가하더라도 당시의 안정 버전을 다시 확인할 수 있고, 프로젝트가 어떻게 성장했는지도 보여 줄 수 있습니다. 이렇게 복구 범위와 공개 기준을 분명히 하면 묵은 자바스크립트 저장소도 가을에 활용할 수 있는 살아 있는 개발자 포트폴리오가 됩니다.