resume-haness/README.md

한국식 이력서 생성 하네스

사실을 만들지 않고, 지원 공고에 맞는 현대적인 한국어 이력서를 생성·평가·수정하기 위한 하네스입니다. 이 저장소는 품질 계약을 중심으로 설계합니다.

• 모든 생성 문장에는 입력 근거 ID가 하나 이상 붙습니다.
• 근거 없는 경력·수치·기간·기술은 최종본에 들어갈 수 없습니다.
• 공고 분석, 근거 매핑, 문장 작성, 독립 평가를 서로 다른 단계로 분리합니다.
• 규칙 검사와 LLM 평가를 모두 통과해야 출력합니다.
• 공고에서는 필수 섹션·글자 수·파일 형식을, 설정에서는 날짜·섹션 순서를 코드로 재검사합니다.
• 사진·생년월일·성별·상세 주소·가족관계 등은 기본 제외합니다.
• 민간 일반형, 공공 블라인드/NCS형, 채용사 지정 양식형을 정책으로 갈라 둡니다.

정본과 현재 출력

이력서 내용의 정본은 Pydantic 도메인 모델 ResumeDraft입니다. JSON과 YAML은 이 모델을 교환·저장하기 위한 직렬화 형식입니다. 제출용 문서 렌더러가 아닙니다. 현재 구현된 최종 렌더러는 ATS 친화 단일 열 Markdown뿐입니다. HTML, DOCX, PDF, HWPX 및 채용사 지정 양식 렌더러는 현재 구현되어 있지 않습니다.

다음 세 모드는 내용 선택·개인정보·블라인드 검사에 적용되는 정책 프로필입니다. 출력 파일 형식을 의미하지 않습니다.

모드	용도	기본 전략
private_modern	일반 민간기업	핵심 요약·역량·성과 중심, 불필요한 개인정보 제외
public_blind	공공기관/NCS 블라인드	편견 유발 정보 차단, 직무 교육·자격·경력·경험 중심
employer_form	회사 지정 양식을 위한 정책	지정 필드·동의·채용사 요구 계약을 검증하되 전용 렌더러는 미구현

employer_form에서도 현재는 Markdown만 출력할 수 있으며 사진은 Markdown 렌더러가 거부합니다. 공고에 EMPLOYER_TEMPLATE 제약이 있으면 전용 어댑터가 없는 현재 코어는 통과한 척하지 않고 fail-closed로 차단합니다.

경력직은 최근 경력과 정량·정성 성과를 우선하고, 신입은 직무 관련 프로젝트·교육·경험을 우선합니다. 동일한 사실 저장소에서 모드별 콘텐츠 계획만 달라집니다.

CandidateProfile.records에는 회사·직무·재직기간·고용형태, 무급 직무경험, 학위·학교·전공, 자격명·발급기관·취득일을 구조화해 둘 수 있습니다. 각 레코드는 반드시 기존 EvidenceItem ID와 연결되며 회사·직무·학교·기간 같은 핵심 값도 연결 근거에서 확인되어야 합니다. 유급 경력과 무급 경험은 서로 다른 타입으로 검증됩니다. 이 레코드는 승인된 초안을 우회해 직접 출력하지 않습니다. 세부 계약은 구조화 레코드를 참고하세요.

headline과 summary는 현재 intake 메타데이터입니다. 승인된 DraftClaim으로 근거화되지 않으면 LLM에 전송하거나 최종본에 자동 출력하지 않습니다.

파이프라인

입력 검증/개인정보 최소화
  → 공고 요구사항 분석
  → 요구사항-후보자 근거 매핑
  → 섹션·분량 계획
  → 근거 ID가 붙은 초안 생성
  → 결정적 규칙 검사
  → 독립 품질 평가
  → 결함 단위 수정(최대 2회)
  → 승인된 ResumeDraft 아티팩트
  → Markdown 렌더링 전 로컬 하드 게이트 재검사

상세 설계는 아키텍처, 품질 루브릭, 개인정보·공정성 정책, 배포 보안과 품질 승인 신뢰 경계를 참고하세요.

개발 상태와 실행

현재 단계는 실행 가능한 코어·CLI·Markdown 렌더러입니다. 공고 분석부터 수정까지의 조정은 LLMBackend 프로토콜을 통해 실행되지만 특정 LLM 공급자 어댑터는 저장소에 포함되어 있지 않습니다. 배포자가 어댑터를 별도로 연결해야 합니다. 이 어댑터는 시간 제한, 재시도, 비용·토큰 계측, 데이터 보존 정책을 갖춰야 합니다.

python3 -m pytest
PYTHONPATH=src python3 -m resume_harness.cli validate \
  --candidate examples/candidate.sample.yaml \
  --job examples/job.sample.yaml \
  --config examples/config.sample.yaml \
  --analysis examples/job-analysis.sample.yaml \
  --evidence-map examples/evidence-map.sample.yaml \
  --content-plan examples/content-plan.sample.yaml \
  --draft examples/draft.sample.yaml

PYTHONPATH=src python3 -m resume_harness.cli render \
  --candidate examples/candidate.sample.yaml \
  --job examples/job.sample.yaml \
  --draft examples/draft.sample.yaml \
  --config examples/config.sample.yaml \
  --analysis examples/job-analysis.sample.yaml \
  --evidence-map examples/evidence-map.sample.yaml \
  --content-plan examples/content-plan.sample.yaml \
  --quality-report examples/quality-report.sample.yaml

설정과 샘플에는 실명이 아닌 합성 데이터를 사용합니다. 실제 이력서 자료를 소스 관리에 커밋하지 마세요.

examples/quality-report.sample.yaml은 외부 평가 모델이 실제로 발급한 보고서가 아닙니다. CLI 계약과 렌더 게이트를 재현하기 위한 합성 golden fixture입니다. 따라서 예제의 점수를 실제 이력서 품질 인증으로 해석하면 안 됩니다. 실제 운영에서는 LLMBackend 평가 응답 또는 사람 검토 결과를 연결하고, 다중 사용자 배포라면 서명된 attestation까지 검증해야 합니다.

이 CLI의 fingerprint는 오래된 평가가 다른 아티팩트에 적용되는 것을 막는 무결성 검사이며 전자서명이 아닙니다. 품질 보고서 파일 자체를 신뢰할 수 없는 다중 사용자 배포는 서명된 attestation과 신뢰 저장소를 추가해야 합니다. 이 attestation은 평가 정책·모델 식별자·전체 보고서를 포함해야 합니다. 필드, 검증 순서, 키 회전 및 필수 공격 테스트는 배포 보안 설계에 정의했습니다.

품질 릴리스 기준

최종 출력 조건은 총점만으로 결정하지 않습니다.

• 근거 연결률 100%, 근거 없는 주장 0건
• 구조화 기록이 있으면 역할과 대표 성과를 나눈 핵심 요약, 검증된 핵심 역량, 경력별 역할과 복수 성과, 프로젝트별 역할·구현·검증 결과를 갖춤
• 날짜 역전·깨진 참조·중복 ID 0건
• 금지 개인정보 또는 기밀 노출 0건
• 전체 품질 점수 90점 이상, 주요 영역별 80% 이상
• 공고의 필수 요구사항 중 근거가 있는 항목은 빠짐없이 반영
• 현재 결정적으로 검증 가능한 공고별 필수 섹션·글자 수·Markdown 형식 위반 0건
• 수정 한도 이후 하드 게이트 실패 시 결과 대신 needs_user_input 반환

이 프로젝트는 이력서 작성 지원 도구이며 법률 자문이나 채용 합격을 보장하지 않습니다. 지원처의 공식 공고와 지정 양식이 항상 우선합니다.