app/agent/1. 미션
버튼으로 안 되는 작업을 에이전트로 처리한다. 세 축이다 — ① 이력서 비정형 → 정형 추출 ② 도구 호출 에이전트 ③ RAG 질의응답(보조).
셋 모두에서 최종 확정은 항상 사람이다. AI가 만든 모든 것은 화면에서 점선 상태로 시작하고, 사람의 명시적 액션을 거쳐야만 실선이 된다. 이것은 구현 편의가 아니라 채용이라는 도메인에서 되돌릴 수 없는 판단을 자동화하지 않겠다는 결정이다.
2. 범위
포함
- 이력서 구조화 추출 — PDF · DOCX · HWP 텍스트 추출(텍스트 PDF만, 스캔본 제외 · HWP 실패 시 수동 폴백) → 경력 · 기술 · 학력 구조화 필드 + 담당자용 요약문
- 접수 시 1회 생성 · 저장. 재생성은 명시적 버튼으로만
- 도구 호출 에이전트 — 자연어 한 문장 → 검색 · 조회(읽기) / 단계 변경 · 메일 초안(쓰기) 순차 호출
- 에이전트 API 라우터와 그 UI 스펙 (UI 구현은 프론트와 협업)
- (여유) 음성 입력 — STT → 엔티티 해석 레이어 → 기존 텍스트 에이전트
- (여유) RAG 질의응답 — ①②의 보조
제외
- 최종 합불 자동 확정 — 영구 제외
- 음성 대 음성 응답 · TTS
- 표정 분석 · SNS 크롤링 · 실시간 화상면접
쓰기 도구는 반드시 확인 단계를 거친다. "김도현을 불합격으로 옮길까요?"를 사람이 승인해야 실행된다. 메일도 초안까지만 만들고 발송은 사람이 확정한다.
3. 확정된 설계 결정
착수 전에 결정이 필요했던 3건. 모두 2026. 08. 25.에 확정됐다.
| 결정 | 확정 내용 |
|---|---|
| 에이전트 UI 위치 | 혼합안 — 단축키 콘솔을 기본으로 두고, 확인 카드는 콘솔 안에, 요약은 지원자 상세 패널의 별도 블록에 둔다. 시안 3안을 만들 계획이었으나 결정이 먼저 나와 시안 작업이 불필요해졌다. |
| 모델 · 비용 | 도구 호출은 claude-opus-5, 요약은 claude-haiku-4-5.
도구 호출 정확도가 데모 품질을 좌우하므로 그쪽에만 상위 모델을 쓴다.
사용 모델명은 레코드에 기록해 발표 때 근거로 제시한다. |
| 음성 입력 위치 | 콘솔 전용 마이크. UI 위치 결정에 묶어 함께 확정했다. |
비용 가드 — 더미 10만 건에 LLM 호출 금지
요약 1건이 약 $0.03이다. 성능 검증용 더미 10만 건에 그대로 호출을 걸면 $3,000짜리 사고가 된다. 더미의 요약 필드는 비워두거나 문장 은행에서 채운다. 여기에 더해 호출마다 토큰 사용량을 로깅하고, API 키는 환경변수로만 두어 코드와 로그에 남기지 않는다.
4. 인터페이스 계약
의존 — 도구가 호출할 대상인 백엔드 코어 API(검색 · 지원자 조회 · 단계 변경 · 평가)와 이력서 원문 접근 경로. 제공 — 지원서 접수 흐름이 호출할 요약 생성 함수, 그리고 에이전트 API.
에이전트 도구는 기존 REST를 서비스 레이어로 재사용한다 — 권한 검사를 우회하는 별도 경로를 만들지 않는다. 에이전트가 뒷문이 되면 역할 기반 접근 제어 전체가 무의미해지기 때문이다.
5. 주간 계획
에이전트는 초기 버전(09. 04.) 범위 밖이다. 그 시점까지의 기여는 전환기 백엔드 분담과 UI · 모델 결정이다.
| 주차 | 마일스톤 | 내용 | 완료 기준 |
|---|---|---|---|
| W108. 24. ~ 28. | M1–M4 조기 완료 | 목업 · 추출 PoC · 에이전트 본체 · 설계 결정 4건 확정 · 확정안 목업 재작업 착수 · 프론트 지원 | 달성 M1부터 M4까지 코드가 W1 안에 끝났다. 목업 착수 |
| W208. 31. ~ 09. 04. | 목업 · 테스트 · 데모 | 확정안 목업 완성(확인 카드 · 동명이인 · 마이크) → 프론트 전달 · 테스트 정식 배치 · 전 구간 데모 시나리오 실행 | 목업 전달 완료, 테스트가 CI에서 통과, 4단계 시나리오 성공 |
| W309. 07. ~ 11. | 프롬프트 튜닝 · 폴리시 | 실호출 기반 프롬프트 개선 · 엣지 케이스 처리 · 토큰 비용 실측 갱신 | 프롬프트 2차 버전, 비용 실측치 기록 |
| W409. 14. ~ 18. | (여유) 음성 입력 | STT + 엔티티 해석 레이어 — 이름 유사도 매칭 · 기술 용어 음차 정규화 · 한글 수사 → 숫자 | 음성 → 에이전트 연결 데모 |
| W509. 21. ~ 25. | 데모 동결 · 발표 | 데모 시나리오 최종 확인 · 발표 스토리 정리 | — |
| 버퍼09. 28. ~ 30. | 동결 | 남은 이슈 처리 · (여유) RAG 질의응답 | 09. 30. 1차 완성. 음성이 들어가면 파괴적 명령은 음성에서도 확인 단계를 거친다 |
6. 품질 기준
전 마일스톤 공통으로 적용한다.
환각 가드 — 응답은 도구 결과만 인용한다
존재하지 않는 지원자나 수치를 만들어내면 그 시점에서 실패로 취급하고 프롬프트를 수정한다. 그럴듯한 답변을 성공으로 세지 않는다.
확정은 사람 — 점선에서 실선으로
AI가 만든 모든 것은 점선 상태로 시작하고, 사람의 명시적 액션으로만 실선이 된다. 화면에서 "AI 제안"과 "사람 확정"이 색과 선으로 구분되어 보이게 설계했다.
재현성 — 프롬프트는 코드다
프롬프트를 소스 트리 안에서 버전 관리하고, 호출마다 모델명과 토큰 사용량을 로깅한다. "그때는 됐는데"를 없애기 위한 조건이다.
7. 리스크 및 대응
| 리스크 | 대응 |
|---|---|
| 코어 API가 늦으면 도구를 붙일 데가 없다 | M1을 API와 무관한 작업(추출 PoC · UI 시안 · 프롬프트 설계)으로 구성했고, 전환기에 본인이 평가 API를 직접 만들어 선행을 스스로 풀었다. |
| HWP 추출 불안정 | 처음부터 "실패 시 수동 입력 폴백"을 설계에 포함했다. 나중에 대응하는 예외가 아니라 정상 경로의 일부다. |
| 비용 폭주 | 비용 가드 3종 — 더미 데이터 호출 금지 · 토큰 사용량 로깅 · 키의 환경변수 격리. |
8. 발표 포인트
- 도구 호출 에이전트 설계 — 한 문장이 검색 → 필터 → 상태 변경 → 문서 생성으로 분해되는 과정, 그리고 왜 쓰기 도구에만 확인 단계를 강제했는가.
- 음성 인식 오류가 도구 호출로 전파되는 것을 어떻게 막았는가 — 엔티티 해석 레이어. (음성 기능을 넣는 경우)
- 왜 "버튼으로 되는 일"에 에이전트를 쓰지 않았는가 — AI를 추천까지만 쓰기로 한 원칙을 본인 언어로.