interviewstreet/hiring-agent 딥다이브
— 이력서 PDF를 '공정하고 근거 있는 점수'로 바꾸는 AI 채점 에이전트

interviewstreet/hiring-agent는 HackerRank(인터뷰스트리트)가 공개한, 지원자의 이력서 PDF를 읽어 점수로 바꾸는 AI 에이전트입니다. PDF를 구조화된 JSON으로 파싱하고, GitHub 실데이터(저장소·스타·커밋 수)로 주장을 검증한 뒤, 고정된 채점 기준(rubric)에 따라 항목별 점수 + 근거 + 가점/감점을 LLM이 매깁니다. 핵심은 두 가지 — 로컬에서 무료로(Ollama) 돌아가 이력서가 밖으로 안 나가고, 이름·성별·학교·학점·지역으로는 절대 점수를 매기지 않도록 공정성을 코드와 프롬프트에 박았다는 점. (저장소: interviewstreet/hiring-agent · 언어 Python 84% + Jinja 16% · ★ 약 1.2천 · 라이선스 MIT · HackerRank)

1프로젝트 한줄 요약

"키워드 매칭 ATS가 아니다. 이력서를 '이해'하고, GitHub로 '검증'하고, 근거와 함께 '채점'한다."

전체는 파이썬 CLI 스크립트 하나로 돕니다 — python score.py 이력서.pdf. 웹 서버도, 데이터베이스도, 프런트엔드도 없습니다. 기본 LLM은 로컬 Ollama(예: gemma3:4b)라 인터넷 없이, 무료로, 이력서를 내 컴퓨터 밖으로 내보내지 않고 채점할 수 있고, 설정만 바꾸면 클라우드 Gemini로도 돕니다. 이 문서는 사용법보다 그 안의 설계 — "PDF를 어떻게 믿을 수 있는 JSON으로 바꾸나", "어떻게 LLM의 산수를 안 믿고 코드로 점수를 가두나", "공정성을 어떻게 강제하나"를 파고듭니다.

2왜 주목받는가

"채용 테크 회사가 '자기들이 지원자를 채점하는 실제 로직'을 통째로 오픈소스로 공개했다."

먼저, AI 이력서 채점은 왜 어렵고 위험한가

AI로 이력서를 거르는 시도는 많았지만 악명도 높습니다 — 과거 아마존이 만든 이력서 AI는 여성 지원자에게 불리한 편향이 드러나 폐기됐습니다. 또 지원자는 이력서에 과장을 적기 마련이라, 글자만 믿으면 '튜토리얼 따라 한 프로젝트'와 '진짜 오픈소스 기여'를 구분하지 못합니다. hiring-agent는 이 두 난제를 정면으로 겁니다.

그리고 결정적으로 — 이걸 만든 곳이 HackerRank입니다. 기술 채용·코딩 테스트 플랫폼을 운영하는 회사가 '지원자를 어떻게 점수화하는지'의 실제 기준을 통째로 공개한 셈이라, 채용 현업과 학습자 모두에게 화제가 됐습니다. 활동도 활발해 별 약 1.2천에 포크 353개, 열린 PR이 89개에 이릅니다(사람들이 직접 고쳐 보며 기여 중).

3기술 스택 전체 지도

"무거운 AI 프레임워크가 하나도 없다. 파이썬 표준 + PyMuPDF + Pydantic + Jinja2 + Ollama가 전부다."

의외로 단출합니다. LangChain·LlamaIndex·벡터 DB·임베딩이 전혀 없습니다(파일명이 pymupdf_rag.py지만 실제로는 PDF→마크다운 변환일 뿐, 의미 검색 RAG는 어디에도 없습니다). 무게중심은 'PDF를 믿을 수 있는 JSON으로 바꾸기'와 '스키마로 출력 강제하기'에 있습니다.

① 언어 · 실행

② 문서 파싱 · 구조화

4아키텍처 심화 분석 (이력서 PDF가 점수가 되기까지)

"곧게 흐르는 6단계 파이프라인. 그 한가운데 'GitHub로 검증하고 LLM이 고르는' 에이전트 매듭이 있다."

전체 흐름 한 장

한 바퀴를 풀면 이렇습니다. ① PDF를 곧장 LLM에 던지지 않고 먼저 마크다운으로 바꿉니다(제목·표 구조가 살아 더 잘 읽힘). ② 한 번에 "이력서 전체 파싱해"라고 안 하고, 6개 섹션을 각각 좁은 프롬프트로 따로 뽑습니다(작은 로컬 모델에서 훨씬 안정적). ③ 여기가 에이전트의 핵심 — 이력서 속 GitHub 주소를 따라가 실제 커밋·기여자 수를 확인하고, 그 정보를 보고 평가에 쓸 저장소 7개를 LLM이 직접 고릅니다. ⑤ 마지막에 공정성 규칙(시스템) + 기준표(유저)로 채점하되, ⑥ 점수는 코드가 다시 상한으로 자릅니다.

설계의 심장 — 4개 가중 항목 + 가점/감점

설계 패턴 ① — 모델의 산수를 안 믿고 코드로 가둔다

LLM에게 상한을 알려 주지만, score.py가 다시 한 번 각 항목을 min()으로 자르고 총점도 120으로 클램프합니다. "알려 주되, 믿지 않고, 코드로 강제"하는 방어적 태도입니다.

# 각 항목 점수를 상한으로 자른다 — LLM이 넘겨도 무효
category_score = min(category_data["score"], category_data["max"])
...
max_possible_score = max_score + 20  # 100 + 가점 20
if total_score > max_possible_score:
    total_score = max_possible_score   # 총점도 가둔다

설계 패턴 ② — 공정성을 프롬프트에 명문화

편향을 막는 규칙이 기준표 프롬프트에 대문자로 못 박혀 있습니다. 그대로 베껴 쓸 만한 '편향 완화 프롬프트'의 예시입니다.

설계 패턴 ③ — 제공사 추상화(Strategy 패턴)

LLMProvider라는 약속(Protocol)을 두고 OllamaProvider·GeminiProvider가 각각 .chat()을 구현합니다. Gemini 응답을 Ollama 모양({"message":{"content":…}})으로 바꿔 주어, 나머지 코드는 어떤 제공사든 똑같이 다룹니다.

5디렉토리 구조 해부

"폴더가 거의 없는 평평한 구조. 파일 이름이 곧 파이프라인 단계다."

6학습 포인트 (기술별)

"'문서를 믿을 수 있는 JSON으로 바꾸는 법'과 '공정한 LLM 채점 설계'를 통째로 배울 수 있다."

# 채점: 스키마로 형식을 강제하고, 받은 뒤 다시 검증
kwargs = {"format": EvaluationData.model_json_schema()}
response = self.provider.chat(**chat_params, **kwargs)
evaluation_data = EvaluationData(**json.loads(response_text))

7시스템 요구사항

"파이썬 3.11과 LLM 백엔드 하나면 끝. 도커도, 서버도 없다."

8직접 해볼 수 있는 실습 과제

"내 이력서로 돌려 보기 → 기준표 바꿔 보기 → 검증 로직 뜯어보기 순으로."

9관련 기술 심화 학습 로드맵

"문서 파싱 → 구조화 출력 → LLM 채점 설계 → 공정성/평가 순으로."

10핵심 키워드 사전

"문서에 나온 용어를 한자리에."

11참고 링크

• GitHub 저장소: github.com/interviewstreet/hiring-agent
• PyMuPDF(문서 파싱): pymupdf.readthedocs.io
• Pydantic(스키마): docs.pydantic.dev
• Ollama(로컬 LLM): ollama.com
• HackerRank(만든 곳): hackerrank.com