chorock.page
소개글시리즈프로젝트실험
© 2026 chorock.page
← 프로젝트 목록

Project

folio.ai

GitHub 저장소를 분석해 개발자 포트폴리오를 만들어 주는 AI 서비스: 6시간짜리 해커톤 MVP에서 출발해 계속 개발 중

작업 기간

2026.08 ~ 현재

프로젝트 정보

팀 구성

Codex Hackathon 12팀: Insight 2명 · Builder 2명

담당 역할

백엔드(해커톤) · 이후 단독 확장

데모 보기GitHub

목차

맡은 일성과와 한계주요 기능문제 해결스크린샷발표 슬라이드
목차
맡은 일성과와 한계주요 기능문제 해결스크린샷발표 슬라이드

사용 기술

앱

Next.js (App Router)React 19TypeScriptTailwind CSS

백엔드·데이터

Supabase (Postgres·Storage)GitHub OAuthVercel Workflow

생성

OpenAI Responses APIstrict JSON schema

프로젝트 개요

GitHub 저장소의 코드와 활동 기록을 분석해 취업용 포트폴리오와 이력서 초안을 만들어 주는 AI 서비스입니다. GitHub로 로그인해 저장소와 강조할 경험을 선택하면 저장소 분석과 AI 생성을 거쳐 케이스 스터디 형식의 포트폴리오 웹페이지가 만들어집니다.

Codex Community Korea 해커톤(2026.08)에서 시작한 프로젝트입니다. 지원자 280명 중 100명이 선발되어 25개 팀을 이뤘고, 당일 아침 처음 만난 4명(기획 2·개발 2)이 무작위로 한 팀이 되어 점심시간을 제외한 6시간 안에 기획부터 배포, 발표 자료까지 마치는 방식이었습니다. 제출 마감 약 10초 전에 업로드를 끝냈습니다. 그날의 기록은 해커톤 후기에 따로 정리해 두었습니다. 해커톤 이후에는 제가 단독으로 이어받아 개발을 계속하고 있습니다.

맡은 일

  • 해커톤 당일에는 Builder 2명 중 백엔드를 맡아 GitHub OAuth와 서버 세션, Supabase 스키마, 저장소 동기화, OpenAI 생성 Workflow, 생성 상태 polling API를 당일에 구현했습니다.
  • 해커톤 이후의 확장은 프론트엔드와 백엔드 모두 혼자 진행하고 있습니다. 다중 저장소 생성, 공개 공유 링크, A4 인쇄 기반 PDF, 생성 파이프라인 안정화를 거치며 46개의 커밋을 쌓았습니다.
  • 결제와 크레딧은 시연용 mock입니다. 실제 승인·지급·차감이 발생하지 않으며, 서비스 내 공지에도 이를 명시해 두었습니다.

성과와 한계

  • folio.klr.kr에서 운영 중이며, 해커톤 이후에도 개발을 이어가고 있습니다.
  • 작업마다 Node.js test runner 기반 테스트를 함께 작성해 왔고, 생성 계약·다중 저장소·공유 링크·오류 처리를 검증 대상으로 삼습니다.
  • 결제와 크레딧은 아직 mock이며, 실서비스 결제는 연동하지 않았습니다.
  • 해커톤에서 우승하지는 못했습니다. 대신 6시간짜리 MVP를 버리지 않고 실서비스 수준으로 끌어올리는 쪽을 택했습니다.
  • 에이전트만으로 MVP를 만든 것은 이번이 처음이라 미숙한 부분이 많았습니다. 에이전트를 협업에 활용하는 방식도 서툴렀고, 초반에 정책을 정하는 데 시간을 상당히 들였지만 그것이 효율적이었는지는 지금도 확신하지 못합니다. 같은 시간이 주어졌는데도 팀마다 결과물의 완성도 차이가 컸고, 이는 에이전트를 잘 쓰는 방법을 다시 생각하게 된 계기가 됐습니다.
  • 다음 단계는 실사용자를 차근차근 모아 보는 것입니다.

주요 기능

  • GitHub OAuth 로그인, 저장소 조회·동기화와 다중 선택(최대 5개)
  • 지원 직무·강조 경험·자유 프롬프트를 반영한 AI 생성: Vercel Workflow에서 비동기로 실행되며, 화면은 진행 단계를 polling하고 실패한 작업은 재시도할 수 있습니다
  • 케이스 스터디 중심의 반응형 포트폴리오 결과, 공개 공유 링크, A4 낱장 미리보기와 브라우저 인쇄 기반 PDF
  • 로그인 없이 볼 수 있는 맛보기와 포트폴리오 예시 갤러리

문제 해결

생성이 영구히 막히던 경로를 없앤 일

작업 행을 넣은 뒤 저장소 연결 삽입이 실패하면, 보상 처리 없이 예외만 던지고 있었습니다. 활성 작업은 사용자당 하나만 허용하는데 남겨진 대기 행이 그 사용자의 다음 생성을 영원히 막았고, 재시도는 실패 상태에서만 가능해 사용자가 스스로 풀 방법도 없었습니다. 삽입이 실패하면 방금 넣은 행을 되돌리도록 수정했습니다.

프로세스가 중간에 종료되는 경우까지는 보상 처리로 막을 수 없습니다. 그래서 오래 진척이 없는 작업을 실패로 전환하는 정리 로직을 넣었는데, 문제는 실행 위치였습니다. 무료 플랜의 크론은 하루 한 번뿐이라 리퍼로 쓸 수 없었습니다. 대신 막힌 사용자가 반드시 거치는 두 지점, 즉 생성 요청 진입부와 진행 화면이 2초마다 호출하는 조회에서 정리를 실행했습니다. 서버 어디에도 외부 호출 시간 제한이 없던 점도 이때 함께 고쳤습니다. 매달린 작업 하나가 다음 시도까지 막는 구조였기 때문입니다.

실패가 전부 같은 문장으로 뭉개지던 문제

생성이 실패하면 원인과 관계없이 "잠시 후 다시 시도해주세요"라는 한 문장만 나왔습니다. GitHub 호출 한도에 걸린 사용자와 연동이 끊긴 사용자가 같은 화면을 보고, 둘 다 곧바로 재시도를 눌러 같은 실패를 반복했습니다. 에러를 원인별로 분류해 사유를 보여 주고, 다시 시도해도 결과가 같을 실패는 그 자리에서 종료하도록 했습니다. 진행 화면의 폴링은 한 번만 실패해도 즉시 멈춰서, 네트워크가 잠깐 끊기면 멀쩡한 작업이 실패한 것처럼 보였습니다. 이를 최대 세 번까지 간격을 늘려 가며 재시도하도록 바꿨습니다.

이 결함들이 오래 남아 있던 이유가 핵심입니다. 목 백엔드가 한 번도 실패하지 않으니 실패 경로가 로컬에서 실행될 일이 없었습니다. 그래서 목에 실패를 주입하는 스위치를 만들었고, 이제 실패 화면도 로컬에서 개발하고 확인할 수 있습니다.

남의 커밋이 지원자의 성과로 서술될 뻔한 문제

커밋과 PR을 저자 구분 없이 생성 근거로 넘기고 있었습니다. 팀 저장소라면 팀원의 작업이 지원자의 성과로 서술될 수 있는 구조였고, 이는 포트폴리오 생성 서비스가 가장 피해야 할 실수입니다. 응답에 이미 포함된 저자 정보로 본인 작업과 팀 작업을 구분해 담고, 팀 작업은 맥락으로만 활용하라는 지침을 추가했습니다. 추가 API 호출은 없습니다.

같은 이유로, 근거에 없는 기술이 결과에 섞이면 걸러냅니다. 프롬프트로 금지해도 모델은 그럴듯한 이름을 덧붙이기 때문이며, 면접에서 설명하지 못할 한 줄이 남는 쪽이 더 큰 손해입니다. 무엇을 걸렀는지는 로그로 남겨 프롬프트를 고치는 근거로 씁니다.

스크린샷

대시보드: 최근 작업과 공지

포트폴리오 예시 갤러리

생성 결과: 저장소 근거 기반 케이스 스터디

발표 슬라이드

해커톤 제출 자료입니다. 기획·시장 조사 슬라이드는 Insight 팀원들이 제작했고, 저는 Builder로서 제품 화면 부분을 맡았습니다.

표지: 취업의 문턱을 간단한 클릭으로 넘다

Vision & Mission: 증가하는 구직자 수, 줄어드는 신입채용

Vision & Mission: 자료는 남아있지만 포트폴리오에는 담기지 않는 경험

Persona: 프로젝트는 했는데 포트폴리오 작성이 막막한 개발자

Problem & Solution: 저장소 선택 · 커밋/PR 분석 · 템플릿 제공

Product/Service: 레포지토리만 선택하세요, 경험은 저희가 정리할게요

1. 선택해요: 연동된 GitHub 저장소에서 원하는 것만 고르기

2. 보충해요: 지원 직무와 강조하고 싶은 경험을 프롬프트로

3. 만들어요: 저장소 분석부터 화면 완성까지 진행 단계 표시

4. 확인해요: 완성된 포트폴리오와 PDF 이력서 내려받기

시연 영상 안내

Competitive Landscape: 국내 IT 기업 맞춤형 포트폴리오 생성

Market Size: 국내 IT 개발자를 시작으로 세계 시장까지