ai job search 로컬 환경 구축 및 /setup 프로필 생성 가이드

ai-job-search는 Anthropic의 Claude Code CLI 환경에서 동작하는 에이전트 기반 구직 보조 도구입니다. 사용자의 경력과 역량을 바탕으로 프로필을 구성하고 채용 공고를 분석하여 맞춤형 서류 작성을 보조하는 구조를 갖추고 있습니다.

처음 ai-job-search를 로컬 환경에 설정할 때 여러 런타임 의존성이 얽혀 있어 설치 오류를 겪거나 프로필 설정 명령어가 어떻게 동작하는지 파악하기 어려울 수 있습니다. 이 글에서는 공식 저장소 문서를 기준으로 필수 런타임 준비, 단일 CLI 설치 스크립트 실행, 그리고 /setup을 통한 세 가지 프로필 생성 경로를 안내합니다.

ai-job-search 실행을 위한 사전 요구사항과 비용 모델

터미널 명령어가 표시된 랩톱과 개발 환경 — ai-job-search 구동에 필요한 런타임 환경 구성

ai-job-search 프레임워크를 사용하기 위해서는 실행 환경인 Claude Code뿐만 아니라 언어 런타임 및 문서 컴파일러가 로컬 시스템에 미리 갖추어져 있어야 합니다.

Claude Code CLI: 터미널 환경에서 에이전트를 구동하는 핵심 인터페이스입니다. 공식 문서에 명시되어 있듯이 Claude Code에는 무료 요금제가 없으므로, Anthropic API 크레딧(토큰당 과금)을 보유하고 있거나 Claude Pro, Max, Team 구독 계정이 반드시 필요합니다.
Python 3.10 이상: 포털 설치 자동화 스크립트 및 급여 벤치마킹 도구 실행에 필요합니다. 시스템 터미널에서 python3 --version(Windows는 py --version)을 실행하여 3.10 이상인지 확인해야 합니다.
Bun: 채용 포털 검색 도구(TypeScript 기반)를 실행하고 관리하기 위한 런타임입니다. macOS 및 Linux에서는 curl -fsSL https://bun.sh/install | bash, Windows PowerShell에서는 powershell -ExecutionPolicy Bypass -c "irm https://bun.sh/install.ps1 | iex" 명령어로 설치할 수 있습니다.
LaTeX 배포판: 서류 출력을 위해 lualatex와 xelatex 엔진을 모두 지원하는 LaTeX 환경(TeX Live, MacTeX, TinyTeX, MiKTeX 등)이 필요합니다. 이력서(CV)는 moderncv 템플릿의 폰트 확장을 위해 lualatex로 컴파일되며, 자기소개서(Cover Letter)는 fontspec 요구사항으로 인해 xelatex로 컴파일됩니다.

설치 도구들이 올바르게 인식되는지 확인하려면 각 도구의 버전을 터미널에서 점검하십시오.

# 1. Claude Code CLI 전역 설치
npm install -g @anthropic-ai/claude-code

# 2. Python 버전 확인 (3.10 이상 필수)
python3 --version

# 3. LaTeX 컴파일러 동작 확인
lualatex --version
xelatex --version

터미널을 열고 위 명령어를 순서대로 실행합니다.
각 명령어 실행 시 버전 정보가 오류 없이 출력되는지 확인합니다.
만약 command not found 오류가 발생한다면 해당 런타임의 바이너리 경로가 시스템 PATH 환경 변수에 등록되었는지 점검해야 합니다.

저장소 복제 시 보안 주의사항과 비공개 저장소 관리

ai-job-search를 사용할 때 가장 주의해야 할 점은 개인정보 보호입니다. 온보딩 과정에서 사용자의 실명, 연락처, 학력, 이전 직장 경력, 희망 연봉 등의 민감한 정보가 Git 추적 파일에 직접 작성됩니다.

GitHub에서 공개 저장소를 단순히 포크(Fork)하면 해당 포크 저장소 역시 공개 상태로 유지됩니다. GitHub 정책상 공개 저장소의 포크는 비공개로 전환할 수 없으므로, 공개 포크 상태에서 프로필을 설정하고 커밋 후 푸시하면 모든 개인정보가 외부에 노출될 수 있습니다.

따라서 코드 기여 목적이 아닌 실제 개인 구직 활동을 위해 도구를 사용하는 경우라면, 새로운 비공개(private) 저장소를 생성한 뒤 공식 ai-job-search 저장소를 upstream 원격 저장소로 연결하여 사용하는 방식이 권장됩니다.

단일 명령어로 포털 CLI 도구 의존성 설치하기

터미널에서 스크립트를 통해 의존성을 설치하는 화면 — tools/install_portal_clis.py를 통한 포털 CLI 일괄 설치

ai-job-search에는 채용 공고를 검색하기 위한 여러 포털 CLI 도구들이 .agents/skills/*/cli/ 디렉터리 내에 구성되어 있습니다. 과거에는 각 도구 디렉터리를 일일이 순회하며 설치해야 했으나, 최신 릴리스에서는 단일 크로스 플랫폼 스크립트로 자동화되었습니다.

저장소 루트 디렉터리에서 다음 명령어를 실행하여 의존성을 설치합니다.

# 저장소 루트에서 포털 CLI 도구 전체 설치 실행
python3 tools/install_portal_clis.py

# Windows 환경인 경우:
# python tools\install_portal_clis.py

터미널에서 저장소 루트 경로로 이동한 후 설치 스크립트를 실행합니다.
스크립트는 .agents/skills/*/cli/package.json 경로를 자동으로 탐색(discover)하여 각 하위 도구에 대해 bun install을 순차적으로 수행합니다. 설치 시 실행되는 라이프사이클 스크립트가 선언된 패키지가 있다면 보안을 위해 실행을 건너뛰고 터미널에 보고합니다.
설치 예정 항목만 미리 확인하고 싶다면 --dry-run 플래그를 붙여 실행할 수 있습니다.

기본 포함된 도구 중 linkedin-search와 freehire-search는 런타임 외부 의존성이 없어 일반 Bun 런타임 환경에서 바로 동작하며, bun install은 TypeScript 개발용 타입 정의를 가져오는 용도로만 사용됩니다. 한편, 기본 내장된 포털 검색 스킬 중 다수는 덴마크 구직 시장을 기준으로 설정되어 있으므로, 다른 국가나 플랫폼을 검색하려는 경우 향후 /add-portal 명령어를 통해 로컬 구직 사이트에 맞는 검색 도구를 확장 구성할 수 있습니다.

/setup 온보딩을 통한 3가지 프로필 구축 경로와 정상 확인

런타임과 포털 CLI 설치를 완료했다면 Claude Code를 구동하여 구직자 프로필을 구축하는 /setup 단계를 진행합니다.

# 1. Claude Code 시작
claude

# 2. Claude Code 대화창 내부에서 프로필 설정 명령어 입력
/setup

/setup 명령어를 실행하면 Claude가 로컬 저장소 상태를 감지한 뒤 다음 3가지 경로(Path) 중 하나를 선택하도록 안내합니다.

Path A (documents 폴더 분석): 가장 권장되는 방식으로, 저장소의 documents/ 디렉터리에 기존 이력서 PDF, 링크드인 프로필 내보내기 문서, 학위 증명서, 추천서, 이전 지원서 등을 넣어두고 분석을 요청합니다. Claude가 폴더 내 파일들을 일괄 교차 참조하여 누락된 정보를 채우고 프로필 업데이트를 제안합니다. 이 작업은 멱등성(idempotent)을 가지므로 자료를 추가한 뒤 다시 실행해도 안전합니다.
Path B (단일 CV 파일 또는 텍스트 입력): 단일 이력서 파일만 있는 경우 사용합니다. 대화창에서 @파일명 형태로 이력서를 지정하거나 내용을 복사해 붙여넣으면, Claude가 이를 파싱해 프로필을 추출하고 부족한 항목에 대해 추가 질문을 던집니다.
Path C (대화형 인터뷰 모드): 사전에 준비된 문서가 없는 경우 선택합니다. Claude가 구직자의 경력, 학력, 핵심 역량 등을 섹션별로 질문하고 사용자가 순차적으로 답변하면서 프로필을 완성해 나갑니다.

프로필 작성이 완료되면 저장소 루트의 CLAUDE.md 파일과 .claude/skills/job-application-assistant/ 디렉터리 내에 세부 프로필(후보자 기본 정보, 행동 특성, 작성 스타일 가이드 등)이 마크다운 파일 형태로 정상 생성되었는지 확인해야 합니다. 파일들이 채워져 있다면 초기 온보딩이 성공적으로 마무리된 것입니다.