HR Copilot LangGraph 설계 문서

초기 LangGraph 설계 기준점 정리 문서

목적: 개선 전 구조의 설계 근거, 노드별 역할, State 흐름, generation_basis 작성 기준을 일목요연하게 정리한다.

1. 문서 목적

본 문서는 HR Copilot의 초기 LangGraph 기반 면접 질문 생성 파이프라인을 AS-IS 기준으로 정리한 문서이다.

초기 구조는 단순히 LLM에게 면접 질문을 한 번에 생성시키는 방식이 아니라, 실제 면접관이 사고하는 흐름을 여러 노드로 분리하여 구성한 구조이다.

전체 흐름은 다음과 같다.

지원자 문서/세션 정보 입력
→ 지원자 문맥 구성
→ 문서 분석
→ 질문 후보 생성
→ 1차 선별
→ 예상 답변 생성
→ 꼬리 질문 생성
→ HR 품질 검수
→ 점수 평가
→ 조건부 재시도
→ 최종 질문 선택
→ API 응답 포맷 변환

2. 초기 설계 핵심 철학

구분	설계 원칙	설명	기대 효과
1	역할 기반 노드 분리	analyzer, questioner, reviewer, scorer처럼 실제 면접 운영 역할을 노드로 분리	각 단계의 책임이 명확해지고 디버깅이 쉬워짐
2	단계별 품질 제어	질문 생성 이후 reviewer와 scorer를 통해 품질을 검증	질문 품질을 한 번 더 통제 가능
3	비용 최적화	selector_lite에서 8개 질문 중 5개만 선별한 뒤 후속 LLM 노드 실행	predictor, driller, reviewer 등 고비용 노드 호출량 감소
4	부분 재생성	전체 질문을 다시 만들지 않고 낮은 점수 질문만 재생성	토큰 낭비 감소 및 재시도 효율 향상
5	State 기반 워크플로우	모든 노드가 AgentState를 읽고 필요한 필드만 갱신	노드 간 데이터 흐름 추적 가능
6	조건부 라우팅	route_after_scoring에서 점수/리뷰 결과에 따라 다음 노드를 결정	품질 부족 시 자동 보정 흐름 가능
7	관측 가능성 확보	llm_usages를 통해 노드별 토큰, 비용, 시간, 실패 여부를 기록	비용 대시보드와 성능 개선 근거 확보

3. AS-IS 전체 FLOW

build_state
  ↓
analyzer
  ↓
questioner
  ↓
selector_lite
  ↓
predictor
  ↓
driller
  ↓
reviewer
  ↓
scorer
  ↓
route_after_scoring
  ├─ retry_questioner → questioner
  ├─ retry_driller → driller
  └─ selector
        ↓
final_formatter

4. AgentState 데이터 흐름 요약

영역	필드	설명	주 사용 노드
Input	documents	지원자 이력서, 포트폴리오 등 문서 데이터	build_state, analyzer
Input	session_id	질문 생성 세션 ID	build_state, final_formatter
Input	target_job	대상 직무	build_state, analyzer, questioner
Input	difficulty_level	질문 난이도	questioner, final_formatter
Input	prompt_profile	프롬프트 프로필 설정	analyzer, questioner, reviewer
Input	target_question_ids	부분 재생성 대상 질문 ID	retry_questioner, questioner
Input	human_action	사용자 요청 또는 재생성 액션 구분값	questioner, retry_questioner
Input	additional_instruction	사용자 추가 지시사항 또는 재생성 보완 지시	questioner, retry_questioner
Workflow	candidate_context	지원자/직무/문서 정보를 합친 공통 문맥	analyzer, questioner, predictor
Workflow	document_analysis	강점, 약점, 리스크, 검증 포인트	questioner, driller, reviewer
Workflow	questions	생성된 면접 질문 목록	selector_lite, predictor, reviewer, scorer
Workflow	answers	예상 답변 목록	driller, reviewer, final_formatter
Workflow	follow_ups	꼬리 질문 목록	reviewer, scorer, final_formatter
Workflow	reviews	HR 품질 검수 결과	scorer, selector, final_formatter
Workflow	scores	질문별 점수 결과	router, selector, final_formatter
Workflow	review_summary	승인 수, 반려 수, 낮은 점수 질문 등 요약	route_after_scoring
Control	retry_count	전체 재시도 횟수	router, retry 노드
Control	max_retry_count	최대 재시도 횟수	router
Control	questioner_retry_count	questioner 재시도 횟수	router, retry_questioner
Control	driller_retry_count	driller 재시도 횟수	router, retry_driller
Control	max_questioner_retry_count	questioner 최대 재시도 횟수	router
Control	max_driller_retry_count	driller 최대 재시도 횟수	router
Control	retry_feedback	재생성 시 참고할 피드백	questioner, driller
Control	node_warnings	노드 실행 중 발생한 경고	final_formatter
Observability	llm_usages	노드별 LLM 호출 로그	runner, dashboard
Output	final_response	API 최종 응답	final_formatter

5. 노드별 AS-IS 설계 요약

순서	노드	역할	IN 읽는 필드	OUT 쓰는 필드	LLM 호출	설계 근거
1	build_state	접수 담당자	documents, session_id, target_job, difficulty_level	candidate_context, retry_count, max_retry_count	없음	이후 모든 LLM 노드가 공통으로 참조할 문맥을 먼저 정리하기 위함
2	analyzer	서류 분석관	candidate_context, documents, prompt_profile	document_analysis, llm_usages	gpt-5-mini	질문 생성 전에 강점, 약점, 리스크, 검증 포인트를 구조화하기 위함
3	questioner	질문 설계자	candidate_context, document_analysis, target_question_ids, retry_feedback	questions, llm_usages	gpt-5-mini	문서 분석 결과를 기반으로 면접 질문 후보를 생성하기 위함
4	selector_lite	1차 편집자	questions	questions	없음	후속 고비용 LLM 노드 실행 전에 질문 수를 줄이기 위함
5	predictor	답변 예측관	questions, candidate_context, document_analysis	answers, llm_usages	gpt-5-mini	지원자가 답변할 가능성이 있는 내용을 미리 예측하여 꼬리 질문 품질을 높이기 위함
6	driller	심층 면접관	questions, answers, document_analysis	follow_ups, llm_usages	gpt-5-mini	예상 답변의 모호함, 과장 가능성, 근거 부족을 검증하기 위함
7	reviewer	HR 품질 검수관	questions, answers, follow_ups, target_job, prompt_profile	reviews, llm_usages	gpt-5-mini	질문의 직무 적합성, 공정성, 중복, 면접 활용성을 검수하기 위함
8	scorer	정량 평가관	questions, answers, follow_ups, reviews	scores, review_summary	없음	LLM scorer 제거, reviewer 기반 규칙형 scorer로 확정 예정
9	route_after_scoring	편집장	review_summary, retry_count, max_retry_count, questioner_retry_count, driller_retry_count, max_questioner_retry_count, max_driller_retry_count	다음 노드 결정	없음	점수와 리뷰 결과, 노드별 재시도 한도에 따라 재생성 또는 최종 선택 여부를 결정하기 위함
10	retry_questioner	질문 수정 지시자	review_summary, scores, retry_count	target_question_ids, human_action, additional_instruction, retry_feedback, questioner_retry_count	없음	낮은 점수 질문만 부분 재생성하기 위함
11	retry_driller	꼬리 질문 수정 지시자	review_summary, follow_ups, retry_count	retry_feedback, driller_retry_count	없음	꼬리 질문 품질 이슈만 별도로 수정하기 위함
12	selector	최종 선별자	questions, reviews, scores	questions	없음	최종 면접에 사용할 질문 5개를 선별하기 위함
13	final_formatter	최종 응답 편집자	questions, answers, follow_ups, reviews, scores, node_warnings	final_response	없음	API 응답 스키마로 변환하고 completed/partial_completed 상태를 결정하기 위함