구직도 에이전트 파이프라인이 된다: MadsLorentzen/ai-job-search v1.7.2의 Drafter-Reviewer·PDF 검증 루프·신뢰 경계 심층 해부

“AI로 자기소개서 써 주는 도구”라고 하면 대개 프롬프트 몇 개를 묶은 웹앱을 떠올린다. 오늘(2026-10-18) GitHub Trending 전체 일간 2위에 오른 MadsLorentzen/ai-job-search는 결이 다르다. 실행 코드의 중심이 마크다운 명세다. .claude/commands/*.md와 .claude/skills/에 적힌 절차를 Claude Code가 그대로 따라 하며, 채용 포털 검색 → 배치 점수화 → CV·커버레터 LaTeX 초안 → 별도 컨텍스트 리뷰어의 비평 → PDF 컴파일·레이아웃 측정·ATS 텍스트 레이어 검사 → 지원 기록까지 한 저장소 안에서 돈다. 파이썬과 Bun 코드는 그 절차 중 “모델에게 맡기면 매번 달라지는 부분”(중복 키, 상태 파일, robots 판정, PDF 측정, 권한 감사)만 맡는다.

이 글은 “취업에 AI를 쓰자”는 소개글이 아니다. 에이전트 워크플로를 마크다운으로 설계할 때 어떤 부분을 코드로 내려야 하는가, 그리고 개인정보와 신뢰할 수 없는 웹 입력이 한 컨텍스트에 섞일 때 어떻게 경계를 긋는가를 보여 주는 실전 사례로 읽는다. 아래 수치는 모두 2026-10-18 오전(KST) master HEAD 5d9e097 기준으로 직접 체크아웃해 집계·실행한 값이다.

한눈에 보기: 오늘 체크아웃 기준

포크 수가 스타의 3분의 1에 이른다는 점이 눈에 띈다. 일반적인 라이브러리라면 이상한 비율이지만, 이 저장소는 “포크해서 내 프로필을 채워 쓰는 템플릿”이기 때문이다. 그리고 바로 이 사용 방식이 뒤에서 다룰 가장 큰 보안 함정과 연결된다.

탄생 배경과 설계 철학

작성자는 지구물리학자 출신으로, 2025년 말 포지션이 없어지자 자기 구직용으로 이 프레임워크를 만들었다고 README에 적었다. 같은 /scrape·/apply·/interview 흐름으로 69건을 맞춤 지원해 1차 면접 20건, 계약 1건을 얻었고 2026년 6월 AI 엔지니어로 입사했다는 것이 본인 진술이다(재현 가능한 벤치마크가 아니라 개인 사례라는 점은 감안해야 한다). 기본 포털 스킬이 덴마크 시장(Jobindex, Jobnet, Akademikernes Jobbank, Jobdanmark)용인 이유도 여기서 나온다.

CONTRIBUTING.md의 원칙은 꽤 단호하다. “마크다운 명세가 곧 구현”이므로 다른 에이전트 CLI용 포트나 래퍼 같은 두 번째 사본은 받지 않고, 국가별 포털도 업스트림에 넣지 않는다(인도·프랑스 등 PR이 거절된 선례를 명시). 대신 포크에서 /add-portal로 만들고 커뮤니티 인덱스(Discussion #78)에 공유하라는 것이다. 업스트림은 “범용 프레임워크 + 덴마크 데모”, 시장별 적응은 포크라는 분업 구조다.

저장소 구조: 명세·상태·검증 도구의 3층

AGENTS.md는 19줄짜리 “얇은 포인터”다. 다른 런타임(Codex, Gemini CLI, Cursor 등)에게 .claude/가 단일 진실 원천이니 복제하지 말라고만 알린다. 실질적으로는 Claude Code 전용이고, 다른 런타임에서 바로 쓰이는 것은 Agent Skills 형식의 포털 검색 CLI 정도다.

명령 지도: 14개 슬래시 명령이 하나의 파이프라인

/apply 내부: 작성자-리뷰어 분리와 PDF 검증 루프

apply.md는 418줄짜리 절차서다. 핵심은 세 가지 설계 결정이다.

1. 리뷰어는 새 컨텍스트로 띄운다. Step 3에서 Agent 도구로 general-purpose 에이전트를 생성하고, 초안은 파일을 다시 읽게 하지 않고 프롬프트에 인라인으로 넘긴다(토큰 절약). 리뷰어는 회사를 공고 속 링크가 아니라 회사명 검색으로만 조사하고, 결과를 company_research/<회사>.json 캐시에 쓴다.
2. 피드백은 기계적으로 적용 가능한 JSON으로 받는다. Part A는 {file, old_string, new_string, reason} 배열로, 작성자는 Edit 도구로 그대로 적용한다. 판단이 필요한 것만 Part B 서술형(누락 키워드·회사 각도·능동형 재작성·톤)으로 받는다.
3. PDF는 “보고” 끝내지 않고 “측정”한다. lualatex(CV)·xelatex(레터) 컴파일 후 verify_pdf.py --pages로 쪽수, verify_layout.py로 100pt 넘는 내부 구멍·고아 항목 제목·푸터 충돌·마지막 쪽 35% 이상 공백을 잡고, 그다음에 모델이 렌더링된 페이지를 읽는다.

ATS 텍스트 레이어 검사가 실무적으로 중요한 이유

ATS(지원자 추적 시스템)는 렌더링된 페이지가 아니라 PDF에 박힌 텍스트를 읽는다. LaTeX는 보기엔 멀쩡한데 추출하면 아이콘 글리프 이름이 이메일 자리에 들어가거나, 다단 레이아웃이 줄 단위로 뒤섞이는 PDF를 쉽게 만든다. v1.7.2에서 추가된 --ascii-dates는 실제 Workday 가져오기 사례에서 나왔다. 2016--2024가 텍스트 레이어에서 2016<U+2013>2024(en-dash)로 들어가 경력 종료일이 날아간 것이다. 이 플래그는 정규화 전 원시 레이어를 읽어 연도에 붙은 유니코드 대시를 코드포인트와 함께 지적한다.

python tools/verify_pdf.py cv/main_<company>_<role>.pdf --pages 2
python tools/verify_pdf.py cover_letters/cover_<company>_<role>.pdf --pages 1
python tools/verify_layout.py cv/main_<company>_<role>.pdf
python tools/verify_pdf.py cv/main_<company>_<role>.pdf --ascii-dates \
       --dump-text cv/main_<company>_<role>.txt   # pypdf 우선, 없으면 pdftotext

CV가 2쪽을 넘으면 “오래된 섹션부터 자르기” 대신 관련도 가중 컷을 쓴다. 각 줄을 (a) 이번 공고 키워드 관련도, (b) 문서 내 고유성, (c) 커버레터가 그 줄에 기대는지로 점수화해 가장 낮은 줄부터 자른다. 공고 키워드에 걸리는 옛 경력 bullet이 무관한 최근 bullet보다 살아남는 구조다.

/rank와 상태 관리: 모델에게 맡기지 않은 부분

평가 프레임워크(04-job-evaluation.md)는 점수 이전에 두 개의 하드 게이트를 둔다. Eligibility Gate(시민권·영주권·보안 인가 요구 시 채점·작성 자체를 중단하고 원문 인용)와 Language Gate(선언하지 않은 언어 요구는 FAIL, 선언 수준보다 높아 보이면 FLAG)다. “침묵은 허락이 아니다”, “회사 전체의 ‘해외 지원자 환영’은 직무 단위 허락이 아니다” 같은 규칙이 명문화돼 있다.

흥미로운 것은 상태 파일 처리다. 예전에는 /rank가 seen_jobs.json 전체를 모델 컨텍스트에 올려 눈으로 걸러 내고 전체를 다시 써냈다. 이 파일은 설계상 append-only라 워크스페이스가 오래될수록 매 실행 비용이 커진다. 지금은 tools/rank_state.py가 candidates(필요 필드만 투영) · sweep(저장된 마감일만으로 만료 처리, 무페치) · apply(결과 기록, 원자적 교체 저장)를 맡는다.

최근 변경(#534)은 데이터 모델 수준의 교훈을 담고 있다. 가져오기 실패와 마감을 같은 expired로 묶었더니, 순위를 매기는 날 일시적인 403 하나로 살아 있는 공고가 파이프라인에서 영구히 빠졌다. 그래서 unreachable 상태를 분리하고, 3회 시도 + 첫 시도와 마지막 시도 사이 48시간 이상이 지나야 expired_reason: "unreachable"로 포기하며, 포기한 공고는 “수동 확인” 목록에 URL과 함께 한 번 노출한다. 같은 날 예약 실행과 수동 실행이 시도 횟수를 다 태워 버리지 않게 하는 시간 하한이다.

중복 키도 같은 이유로 코드로 내려갔다. tools/job_key.py 독스트링에는 실제 워크스페이스에서 발견된 깨진 키들이 그대로 적혀 있다. deloitte_junior-cybersecurity-analyst-(ot/iot)처럼 /가 아카이브 경로를 쪼개거나, 실행마다 제목을 다른 길이에서 잘라 같은 공고가 두 키로 저장된 경우다. 지금은 회사+제목의 순수 결정적 함수이고, 회사 40자·제목 60자 상한을 넘으면 잘라 내되 해시 접미사로 구분한다.

신뢰 경계: 공고는 데이터, 명령이 아니다

SECURITY.md는 위협 모델을 솔직하게 적는다. “파일 접근 권한이 있는 LLM이 신뢰할 수 없는 웹 콘텐츠(채용 공고)를 개인 데이터(CV·프로필·지원 이력)와 함께 읽는다. 이 조합이 주된 위험 표면이며 완전히 제거할 수 없고 좁힐 수만 있다.” 그 좁히는 방법이 계층별로 설계돼 있다.

robots 판정은 실험으로 확인해 보면 의도가 분명하다. 아래 robots.txt에서 RFC 9309만 놓고 보면 Claude-User 전용 그룹이 있으므로 /jobs/list는 Claude-User에게 허용이다. 하지만 게이트는 Claude-User와 *를 둘 다 검사하므로 재시도를 막는다. 의도적으로 보수적인 해석이다.

User-agent: *
Disallow: /jobs/
Allow: /jobs/view/

User-agent: Claude-User
Disallow: /search
# allowed(body, '*', path) / allowed(body, 'Claude-User', path)
# /jobs/view/123  → True / True   → 재시도 가능
# /jobs/list      → False / True  → gate는 차단(* 쪽 Disallow)
# /search?q=x     → True / False  → 차단
# HTML 오류 페이지 200 → is_robots_body False → 'UNCONFIRMED', 재시도 안 함

설치·실행 치트시트

# 0) 개인 구직용: 포크 대신 비공개 저장소 + upstream (README 권고, SETUP.md 8절)
git clone https://github.com/MadsLorentzen/ai-job-search.git my-job-search
cd my-job-search
git remote rename origin upstream
git remote add origin git@github.com:<me>/my-job-search-private.git   # private로 생성해 둔 저장소

# 1) 포털 CLI 의존성 (lifecycle 스크립트 있는 매니페스트는 자동 건너뜀)
python3 tools/install_portal_clis.py --dry-run
python3 tools/install_portal_clis.py

# 2) 선택 의존성: ATS 검사용 pypdf (없으면 pdftotext 폴백)
pip install pypdf

# 3) Claude Code에서
claude
/setup                 # documents/ · CV 붙여넣기 · 인터뷰 중 택1
/scrape                # 포털 검색 → seen_jobs.json
/rank                  # 배치 점수화 숏리스트
/apply https://boards.greenhouse.io/<co>/jobs/<id>

# 4) 업스트림 추적: 태그 릴리스 기준으로 병합, 영향 파일 미리 보기
python3 tools/check_upstream_updates.py
python3 tools/upstream_triage.py

박스 스모크: 직접 돌려 본 결과

리눅스 박스(Python 3.13.5, Bun 1.4.2)에서 HEAD 5d9e097를 클론해 Claude Code 로그인 없이, 실제 채용 포털에는 요청하지 않고 결정적 도구와 오프라인 테스트만 돌렸다. LaTeX가 없는 환경이라 PDF 컴파일·레이아웃 검증과 LLM이 수행하는 /apply 본 흐름은 실행하지 않았다.

rank_state.py는 합성 상태 파일 5건(그중 1건 skipped)과 에이전트 결과 4건으로 실제 흐름을 재현했다. 기대대로 동작했다.

비교: 비슷한 오픈소스와 어디가 다른가

정리하면 ai-job-search의 차별점은 “AI가 글을 써 준다”가 아니라 검증 가능한 산출물(쪽수·레이아웃·텍스트 레이어·근거 감사)과 상태 기계(seen_jobs.json의 상태 전이, 재시도 하한), 그리고 명시적 신뢰 경계에 있다. 반대로 모델·런타임 선택의 자유는 가장 적다.

트레이드오프와 주의점

AGENTS.md와 CONTRIBUTING.md가 강조하는 “명세가 곧 구현” 원칙에는 대가도 있다. 마크다운 절차는 버전 관리와 리뷰는 쉽지만, 모델이 단계를 건너뛰는지 확인할 수단은 결국 산출물 검사뿐이다. 이 저장소가 PDF·상태·키·권한처럼 검사 가능한 지점을 계속 코드로 내리는 이유이고, 체인지로그에 “산문 규칙이었던 것을 실행 가능하게 만들었다”는 항목이 유독 많은 것도 같은 맥락이다. --ascii-dates, rank_state.py, job_key.py, install_portal_clis.py가 모두 그렇게 생겼다.

누가 도입하면 좋은가

정리

ai-job-search는 겉으로는 구직 도우미지만 속은 “LLM이 따르는 마크다운 명세 + 결정적 도구 + CI 가드”로 짠 에이전트 시스템의 교본에 가깝다. 리뷰어를 새 컨텍스트로 분리하고, 피드백을 기계 적용 가능한 JSON으로 받고, 결과물을 ‘보고’가 아니라 ‘측정’으로 검증하며, 상태 전이처럼 모델이 매번 다르게 할 부분은 파이썬으로 고정한다. 동시에 공고라는 신뢰할 수 없는 입력과 내 개인정보가 한 컨텍스트에 섞인다는 사실을 숨기지 않고, 지시 수준 방어의 한계까지 문서에 적었다. 구직 중이라면 비공개 저장소로 시작해 /rank → /apply 흐름을 써 볼 만하고, 구직 중이 아니더라도 에이전트 워크플로를 만드는 사람이라면 apply.md와 tools/를 한 번 읽어 볼 가치가 충분하다.