boss-agent-cli 딥다이브
— AI 에이전트가 대신 구직하는 JSON-네이티브 CLI

1프로젝트 한줄 요약

"사람용 채용 사이트를 AI 에이전트가 API처럼 쓸 수 있게 바꿔 주는 번역기"입니다. BOSS 直聘은 본래 사람이 브라우저로 클릭하며 쓰는 사이트입니다. boss-agent-cli는 그 사이트의 내부 API를 역공학(reverse engineering)해서, boss search "Golang" --city 광저우 같은 명령으로 검색하고, 결과를 사람이 아니라 LLM이 읽기 좋은 구조화 JSON으로 뱉습니다.

이름 그대로 boss(BOSS 즈핀) + agent(AI 에이전트) + cli(명령줄 도구)입니다. Claude Code·Cursor·Gemini CLI 같은 에이전트 호스트가 Bash로 이 도구를 호출하면, "구직 비서"가 한 명 생기는 셈입니다. 라이선스는 MIT, 2026년에 등장해 TrendShift 일간 7위에 올랐습니다. 코드는 약 17,600줄의 파이썬으로, README가 중국어·영어 모두 제공됩니다.

2왜 주목받는가

2026년의 가장 뜨거운 흐름은 "에이전트가 쓰는 도구(agent-first tooling)"입니다. 사람이 쓰던 CLI를 그대로 에이전트에게 던지면, 색깔 표·진행바·이모지가 섞여 LLM이 파싱하다 헷갈립니다. boss-agent-cli는 이 문제를 정면으로 푼 교과서적 사례라서 주목받습니다. 채용 자동화라는 실용성보다, "에이전트 친화적 CLI를 어떻게 설계하는가"의 모범답안이라는 점이 본질입니다.

경쟁 방식과의 비교

핵심 차별점 셋

3기술 스택 전체 지도

boss-agent-cli는 화려한 ML 스택이 아니라, 잘 설계된 단일 파이썬 CLI입니다. 약 17,600줄의 소스가 commands/ · api/ · auth/ · platforms/ · cache/ · bridge/로 깔끔히 나뉩니다. 무거운 의존성 없이도 "반검출 로그인 + 역공학 API 호출 + 암호화 캐시 + JSON 출력"이라는 풀스택을 파이썬만으로 구현한 점이 인상적입니다.

언어 / 빌드 / 배포

런타임 의존성 (핵심 8개)

4아키텍처 심화 분석

boss-agent-cli의 진짜 배울 점은 "계층 분리"입니다. 명령(commands/)은 비즈니스 로직만, 인증(auth/)은 로그인·토큰만, API(api/)는 HTTP·역공학만, 출력(output.py)은 JSON 봉투만 담당합니다. 한 번의 boss search가 CLI → 인증 → API 클라이언트 → 캐시 → JSON 출력이라는 명확한 파이프라인을 통과합니다.

전체 처리 흐름도

설계 패턴 ① — 출력 봉투(Envelope) 단일화

모든 명령의 마지막은 output.py의 emit_* 함수를 거칩니다. 성공이든 실패든, 검색이든 채팅이든 똑같은 7개 필드 봉투로 포장됩니다. 심지어 사용자가 명령을 잘못 입력한 Click 사용법 에러조차 BossCliGroup이 가로채 JSON으로 변환합니다. "이 도구가 내뱉는 stdout은 항상 유효한 JSON"이라는 불변식을 코드 전체가 지킵니다.

{
  "ok": true,
  "schema_version": "1.0",
  "command": "search",
  "data": [...],
  "pagination": {"page": 1, "has_more": true, "total": 15},
  "error": null,
  "hints": {"next_actions": ["boss detail <security_id>"]}
}

설계 패턴 ② — 3단계 로그인 降级(폴백)

로그인은 "덜 귀찮은 것"부터 시도하고 실패하면 한 단계씩 내려갑니다. ① 로컬 브라우저에서 즈핀 쿠키를 그대로 추출(이미 로그인돼 있으면 무탐지·무클릭) → ② 디버깅 포트가 열린 크롬을 재사용(CDP) → ③ 최후의 보루로 patchright 크롬을 띄워 QR 스캔. 각 단계는 "사람 지문을 얼마나 유지하느냐"로 정렬돼 있어, 봇 탐지 위험이 가장 낮은 길을 우선합니다.

설계 패턴 ③ — 인간 흉내 반(反)크롤링

봇처럼 보이지 않으려고 throttle.py가 요청 사이에 가우시안 분포 난수 지연(예: 1.5~3.0초)을 넣고, 실패하면 지수 백오프로 점점 더 길게 기다리며 재시도합니다. 배치 인사(batch-greet)는 상한 10건으로 막아 두고, stoken 같은 보안 토큰은 브라우저 환경에서 생성합니다. "빠르게 많이"가 아니라 "사람처럼 천천히"가 설계 원칙입니다.

설계 패턴 ④ — 컴플라이언스 게이트

이 레포가 가장 신경 쓰는 부분입니다. compliance.py가 위험한 동작(대량 자동 투척, 채용담당자 측 개인정보 쓰기 등)을 COMPLIANCE_BLOCKED·ACCOUNT_RISK 에러로 막습니다. docs/capability-matrix.md는 "기본은 저위험 모드 — 읽기 우선, 사용자 능동 트리거, 대량/자동 미접촉"이라고 명시하고, 로그인 폴백을 "풍문 회피 수단으로 쓰지 말라"고 경고합니다.

5디렉토리 구조 해부

구조에서 읽어야 할 신호

두 가지가 핵심 인사이트입니다. 첫째, "명령 하나 = 파일 하나"(commands/)라는 규칙이 일관됩니다. 새 명령을 추가할 때 다른 파일을 건드릴 필요가 거의 없습니다. 둘째, 자주 바뀌는 것(엔드포인트·플랫폼)을 데이터·플러그인으로 분리했습니다. api/*.yaml에 경로를, platforms/에 사이트별 차이를 격리해, 즈핀이 바뀌거나 새 채용 사이트를 추가해도 충격이 한 폴더에 갇힙니다.

6학습 포인트 (기술별)

① 에이전트 친화적 출력 계약 설계

output.py의 JSON 봉투는 "도구를 LLM이 쓰게 만드는 법"의 핵심입니다. stdout(데이터)과 stderr(로그)의 분리, ok/error.recovery_action/hints.next_actions 필드 설계를 배우세요. 실습: 아무 사람용 CLI 하나를 골라 출력을 똑같은 7필드 JSON 봉투로 감싸는 래퍼를 작성해 보기.

② 자기서술 프로토콜 (schema 명령)

commands/schema.py는 도구가 자기 능력을 JSON으로 설명하는 패턴입니다. 실습: 내 CLI에 schema 서브커맨드를 붙여, 사용 가능한 명령·인자·에러코드를 기계가 읽는 형태로 출력해 보기. MCP의 tool 정의와 어떻게 닮았는지 비교하기.

③ 역공학 API + 엔드포인트 외부화

api/boss.yaml처럼 잘 깨지는 비공식 API 경로를 코드에서 빼 데이터로 두는 설계를 배웁니다. 실습: 브라우저 개발자도구로 아무 공개 사이트의 JSON 요청을 관찰하고, 경로를 YAML로 빼서 httpx로 호출하는 미니 클라이언트 작성하기(공개·허용된 대상으로만).

④ 다단계 인증 폴백 + 토큰 암호화

auth/manager.py의 "쿠키→CDP→QR" 폴백과, token_store.py의 Fernet+PBKDF2 머신바인딩 암호화를 보세요. 실습: cryptography 라이브러리로 비밀 토큰을 머신 고유 키로 암호화해 파일에 저장·복호화하는 모듈 만들기.

⑤ 반크롤링 매너 (지연·백오프·상한)

throttle.py의 가우시안 지연 + 지수 백오프 + 배치 상한은 "남의 서버를 예의 있게 쓰는 법"입니다. 실습: asyncio로 요청 사이에 정규분포 지연을 넣고, 429(rate limit)를 만나면 지수적으로 대기 시간을 늘리는 재시도 데코레이터 작성하기.

⑥ Click 커스터마이징 (사용법 에러까지 JSON)

main.py의 BossCliGroup(click.Group)은 Click의 표준 에러까지 가로채 일관된 봉투로 바꿉니다. 실습: click.Group을 상속해 main()을 standalone_mode=False로 호출하고, 예외를 잡아 JSON으로 변환하는 그룹 만들기.

7시스템 요구사항

설치 & 첫 1분 (docs/agent-quickstart.md 권장 순서)

# 설치
uv tool install boss-agent-cli
patchright install chromium   # QR 로그인 쓸 때만

# 첫 1분 — README를 다 읽지 않아도 됨
boss doctor    # 환경·의존성·로그인·네트워크 자가진단
boss schema    # 능력 자기서술 (에이전트가 가장 먼저 호출)
boss status    # 로그인 상태 확인
boss login     # status가 AUTH_REQUIRED일 때만

주요 명령어 한눈에

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

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

10핵심 키워드 사전

11참고 링크