DanielPan12/JobHuntBot

에이전트 주도 채용 지원 워크플로우 및 로컬 진행 상황 추적 대시보드입니다. 이 시스템은 파일을 읽고 작성된 지침을 따를 수 있는 모든 AI 코딩 에이전트(Claude Code, Codex CLI, Cursor 등)와 연동됩니다. 특별한 통합 과정이 필요하지 않으며, 단지 에이전트가 SKILL.md 파일에 접근하도록 지정하고 워크플로우를 따르도록 지시하면 됩니다. 이는 산발적인 구직 활동을 반복 가능한 시스템으로 전환합니다: 지원자 프로필 작성, 스크리닝 규칙 설정, 이력서 전략 수립, 지원 실행, 문제 해결(blocker triage), 후속 조치, 그리고 모든 것을 한눈에 볼 수 있는 브라우저 기반 대시보드를 제공합니다.

이것은 원클릭 자동 지원 봇이 아닙니다. 구조화된 워크플로우와 명시적인 안전 경계가 결합되어 있습니다. 에이전트는 누락된 사실을 한 번의 인수인계를 통해 수집하기 전에 도달 가능하고 확인된 모든 필드를 채웁니다. 최종 제출은 승인(authorization)을 필요로 하며, 기존에 부여된 승인은 그 명시된 범위 내에서 유효합니다.

SKILL.md 핵심 에이전트 워크플로우 및 안전 계약 — 여기서 시작하세요
references/
setup-workflow.md 에이전트가 따라야 할 단계별 온보딩 과정
...

저장소를 기기에 다운로드하거나 클론하여 사용하거나, 코딩 에이전트에게 GitHub URL을 지정해 주세요. -
에이전트에게 브라우저 접근 권한을 부여해야 합니다. (실제 지원서 작성에 필수) 리서치/잠재 고객 발굴(아래 5단계)은 공개 웹 소스를 사용할 수 있지만, SKILL.md의 7단계(실제 양식 작성 및 이력서 업로드)에서는 에이전트가 실제 브라우저를 제어할 수 있어야 합니다. 이를 한 번 설정해 두면 어떤 지원에도 요청할 수 있습니다: Claude Code 사용 시에는 Playwright MCP 서버를 추가하여 에이전트가 브라우저 도구(탐색, 클릭, 입력, 양식 채우기, 파일 업로드, 스냅샷 촬영)를 사용할 수 있도록 합니다. 이후 Claude Code 세션을 재시작/재개하면 새로운 도구를 인식하게 됩니다: claude mcp add playwright npx '@playwright/mcp@latest'

Codex CLI 또는 다른 에이전트: 해당 에이전트가 동등한 브라우저 자동화 또는 컴퓨터 사용 기능(Playwright 기반 MCP 서버, 내장 브라우저 도구 등)을 갖추고 있는지 확인하고, 에이전트 문서에 설명된 방식으로 이를 활성화하세요. 이것 없이는 에이전트가 리드 찾기 및 초안 작성까지는 모든 것을 수행할 수 있지만, 실제 애플리케이션 페이지를 열거나 제출할 수는 없습니다. - 만약 워크플로우의 리드 찾기/대시보드 추적 절반만 원하고 직접 지원서를 제출할 계획이라면 이 단계를 완전히 건너뛸 수 있습니다.

• 별도의 비공개 작업 디렉터리를 만들고 자료를 그곳에 넣으세요. 이 공개 저장소는 재사용 가능한 패키지로 유지하세요. 에이전트에게 템플릿과 대시보드를 비공개 작업 공간으로 복사하도록 요청한 다음, 이력서(가급적 편집 가능한 DOCX/Markdown 소스), 성적 증명서 및 프로젝트 노트를 해당 작업 공간의 my-materials/ 폴더에 배치하세요. .gitignore는 추적되지 않은 파일에는 도움이 되지만, 이미 추적 중인 CSV나 템플릿의 변경 사항을 보호할 수는 없습니다. 그런 다음 에이전트에게 어디를 봐야 할지 알려주세요: '제 이력서, 성적 증명서 및 프로젝트 노트는 my-materials/에 있습니다. 시작하기 전에 이것들을 읽어보세요.'

• AI 코딩 에이전트와 세션을 시작하세요(Claude Code, Codex CLI 또는 로컬 파일을 읽을 수 있는 모든 에이전트). 이 폴더에서 다음 명령을 입력하세요: 'SKILL.md를 사용하여 저의 구직 워크플로우를 초기화해 주세요.'

에이전트는 최소한의 필수 질문 세트를 요청하고, 소스 자료와 답변을 사용하여 비공개 작업 공간에 candidate_profile.json 및 application_rules.md와 같은 개인 사본을 생성할 것입니다. 공개된 templates/ 파일은 비어 있게 유지됩니다. 민감한 사실이 누락된 경우 사용자가 확인하기 전까지는 알 수 없습니다. - 안전한 첫 번째 시험 실행. 에이전트에게 명시적으로 다음을 지시하세요: '리드 찾기만 하는 테스트를 진행해 주세요: 3~5개의 직무를 찾아 분류하고, 대시보드를 업데이트하되, 지원 흐름은 열거나 아무것도 제출하지 마세요.'

이 단계에는 웹 검색만 필요하며, 2단계의 브라우저 자동화는 필요하지 않습니다. 이는 실제 애플리케이션 양식에 접근하기 전에 워크플로우가 작동하는 것을 확인하는 권장 방식입니다.

• 대시보드를 열어 진행 상황을 확인하세요: - Windows: dashboard/start-dashboard.bat 더블클릭

• macOS/Linux: dashboard/start-dashboard.sh 실행
  (Node.js가 설치되어 있어야 합니다; 필요한 경우 chmod +x를 한 번 실행하세요) - 이렇게 하면 브라우저에 http://localhost:8420/dashboard.html이 열립니다. 이 도구는 같은 폴더의 CSV 파일을 실시간으로 읽습니다. 새로고침할 때마다 최신 상태가 표시되며, 빌드 단계도 없고 외부 서버도 없으며, 아무것도 기기를 벗어나지 않습니다.

• Windows: 더블클릭

에이전트의 도움을 받아 계속 지원하세요. 한 회사씩 진행합니다. 여기서 2단계의 브라우저 자동화가 실제로 사용됩니다. 이 도구는 작업이 진행됨에 따라 job_pool.csv, application_log.csv, blocker_queue.csv, 그리고 follow_up.csv를 업데이트하며, 현재 지원하는 곳에 이미 제출 승인이 없는 경우에만 제출 승인을 요청합니다.

워크플로우는 하나의 브라우저 도구 호출에서 완전한 양식 섹션 또는 여러 예측 가능한 인접 섹션을 채우는 방식으로 기본 설정됩니다. 에이전트는 확인된 답변을 한 번 준비하고, 저장된 값과 유효성 검사 오류를 함께 확인하며, 차이점만 수정합니다. 배치가 중단되면 무엇이 저장되었는지 확인하고 미완료 필드부터 재개합니다. 종속적인 컨트롤은 여전히 실제 옵션을 기다립니다. 로컬 공백은 독립적인 섹션을 멈추지 않으며, 접근할 수 없는 페이지와 저장되지 않은 필드는 정직하게 기록됩니다. 기존의 제출 승인은 범위 내에서 재사용됩니다. 실행 규칙은 애플리케이션 플레이북을 참조하세요.

대시보드는 정적 HTML 페이지와 작은 로컬 Node 서버(프레임워크, 빌드, 외부 종속성 없음)로 구성되어 있습니다. 여기에는 네 가지 진행 상황 보기와 통합된 작업 대기열이 제공됩니다:

지원 완료 (Applied)— status = Submitted인 행들로, 후속 조치 타임라인과 각 지원이 어떻게 제출되었는지 보여줍니다. 카드를 확장하고 하단의 **

그리고 해당 직무는 다음 새로고침 시 매칭되는 Offer 또는 Rejected 뷰로 이동합니다. (또한, 에이전트가 그 사이에 동일한 파일을 업데이트했을 경우를 대비하여 로컬 서버에서도 쓰기 전에 해당 행이 회사 + 직무 제목과 여전히 일치하는지 확인합니다.)대기 중(Pending)— status = Pending인 회사는 제출/종료 기록이 없으며, 회사별로 그룹화되고 cohort_match_status 열을 사용하여 "확정된 오픈 상태, 아직 지원 안 함" 대 "오픈하지 않음 / 불분명함"으로 분할됩니다 (전체 필드 참조는 templates/dashboard-template/README.md를 참조하십시오).거절됨(Rejected)— Rejected로 표시된 행들로 구성되며, 자체 카운트, 검색 및 카테고리 필터가 있습니다.오퍼 수신(Offer received)— Offer로 표시된 행들로 별도로 계산되고 필터링됩니다. 면접 단계를 통과하는 것은 오퍼를 의미하지 않습니다.

**액션 대기열(Action queue)**은 열려 있는 blocker_queue.csv 항목들과 Needs user / Blocked 역할을 결합하여, 여러 공백 기간 및 제출 후 수정을 보존합니다. 지원/거절/오퍼 카운트는 record_type=company_summary를 제외하며, 날짜와 직무 설명(JD)은 정확한 직무에 일치합니다. CSV 쓰기는 스냅샷을 검증하고 실패한 다중 파일 업데이트를 롤백합니다.

뷰 아래에는 7일 달력이 Applied 버킷의 직무에 대한 예정된 이벤트(테스트, 인터뷰, 예약하는 모든 것)를 보여줍니다. **"+ 일정 추가"**를 클릭하여 하나를 추가할 수 있습니다: 날짜/시간을 선택하고, 이미 제출한 목록에서 회사/직무를 검색한 다음, 이벤트 내용을 자유롭게 입력합니다 (예: "2차 면접", "필기시험") — 어떤 내용을 입력하든 그대로 사용됩니다. 이는 모든 회사의 프로세스가 다르게 읽히기 때문입니다. 이벤트를 저장하면 해당 직무의 job_pool.csv에 동일한 텍스트로 current_stage가 기록되어 Applied 카드가 즉시 이를 표시합니다. 이벤트는 나중에 달력에서 편집하거나 삭제할 수 있습니다. 하나를 삭제한다고 해서 current_stage가 이전 상태로 되돌아가지는 않으므로 (롤백할 신뢰할 수 있는 "이전 단계"가 없으므로 필요하다면 수동으로 편집하십시오), 그럴 경우 직접 수정해야 합니다. 달력 데이터는 follow_up.csv에 저장됩니다.

CSV 파일은 Excel/Google Sheets/Numbers에서도 직접 열 수 있습니다. 대시보드는 동일한 파일을 보는 뷰(view)이며, 쓰기 작업은 위쪽의 결과 및 달력 액션에 한정됩니다.

중요: dashboard.html을 더블클릭하여 여는 것이 아니라 start-dashboard.bat 또는 ./start-dashboard.sh를 통해 대시보드를 열어야 합니다. 그렇지 않으면 해당 페이지가 http://를 통해 CSV 파일을 가져오려고 하는데, 브라우저는 로컬 디스크에서 직접 파일이 열릴 때 이를 차단합니다.

에이전트는 다음을 절대 해서는 안 됩니다:

• 신원, 취업 허가(work authorization), 보상, 또는 법적 사실을 추측하는 것.
• CAPTCHA, Cloudflare, 또는 봇 방지 검사를 우회하거나, 알 수 없는 계정/2FA를 통해 자동 로그인하는 것.
• 경험, 자격 증명(credentials), 포트폴리오 작업을 꾸며내는 것.
• 저장되거나 추적되는 채용 공고를 제출된 지원서로 간주하는 것.
• 현재 지원에 대한 승인 없이 최종 제출을 클릭하는 것; 이미 변경되지 않고 승인된 제출은 추가 확인이 필요하지 않습니다.

이 레포지토리는 개인 데이터가 없는 빈 템플릿과 빈 대시보드를 제공합니다. candidate_profile.json, job_pool.csv 및 나머지 파일을 자신의 정보로 채운 후에는 절대로 그 채워진 사본을 공개적으로 게시하지 마십시오 (개인 포크의 데이터를 공개 레포지토리에 푸시하거나, 이슈에 스크린샷으로 올리는 등의 행위 금지). 작업 중인 사본은 비공개로 유지하고; 공유할 목적은 오직 워크플로우/템플릿 계층뿐입니다.

레포지토리 루트에서:

node scripts/check-public-package.js
node --test scripts/check-public-package.test.js
node --test dashboard/tests/*.test.js

공개 패키지 검사(public-package check)는 채워진 시작 데이터베이스와 금지된 비공개 아티팩트를 거부합니다. 스테이징된 diff도 확인하십시오. 자유 텍스트나 Git 히스토리가 익명임을 증명할 수 있는 자동화된 검사는 없습니다. 회귀 테스트(regression suite)는 CSV 파싱/원자적 쓰기(atomic writes), 역할 매칭, 결과 분리 및 액션 큐를 다룹니다. 브라우저 테스트는 Playwright와 호환 가능한 브라우저가 사용 가능할 때 실행되며, 그렇지 않으면 해당 테스트는 건너뜁니다. CI에서는 공개 패키지 검사와 사용 가능한 테스트를 실행합니다.

개인 운영 사본(private operational copy)에서 데이터를 편집한 후에는 node dashboard/scripts/audit-data.js와 node dashboard/scripts/company-categories.js --check를 사용하세요.

사실을 지어내서 경고 메시지를 해소하기보다는, 역사적 공백(historical gaps)을 명시적으로 보존해야 합니다.

MIT — LICENSE 참조

이 프로젝트는 Yvonne He의 오픈 소스 ApplyPilot 워크플로우를 이름 변경/각색한 파생물입니다. 원본 저작권 고지 사항은 (MIT 라이선스에 따라) 이 각색본의 저작권 라인과 함께 LICENSE에 보존되어 있습니다.

一个由 AI Agent驱动的求职投递工作流,配一个本地的求职进度追踪看板。它适用于任何能读文件、能听懂并执行文字指令的编程 Agent(Claude Code、Codex CLI、Cursor 等)——不需要任何特殊的官方集成,你只需要让 Agent 打开 SKILL.md

并按照里面的工作流执行即可。它会把零散的投递过程变成一套可重复的系统:候选人信息、筛选规则、简历策略、投递执行、卡点处理、后续跟进,外加一个网页版进度看板。

这不是一个"일괄 자동 투척(一键自动海投)" 로봇입니다. 그것은 구조화된 프로세스 + 명확한 안전 경계입니다—먼저 접근 가능하고 확인된 모든 내용을 채우고, 알려지지 않은 사실에 대해서만 집중적으로 질문합니다. 최종 제출에는 권한이 필요하며; 범위가 변하지 않는 한 이미 얻은 권한을 재사용하고 중복 확인하지 않습니다.

SKILL.md Agent 핵심 워크플로우 및 안전 약속 — 여기서 시작
references/
setup-workflow.md Agent가 따라야 할 단계별 초기화 프로세스
...

이 저장소를 로컬에 다운로드하거나 클론하세요(또는 GitHub 주소를 프로그래밍 Agent에게 직접 전달하세요). -
Agent에게 브라우저를 탐색하는 능력(capability)을 부여하세요—실제 양식을 제출할 때 필수입니다. 아래 5단계의 "직무 검색" 조사에는 공개 웹 출처를 사용할 수 있지만, SKILL.md

7단계(실제 양식 작성 및 이력서 업로드)에서는 Agent가 실제로 브라우저를 조작할 수 있어야 합니다. 실제 투척을 시작하기 전에 다음을 설정하는 것이 좋습니다: Claude Code: Playwright MCP를 설치하여 Agent가 브라우저 조작 도구(페이지 열기, 클릭, 입력, 양식 작성, 파일 업로드, 스크린샷 등)를 갖게 하세요. 설치 후 Claude Code 세션을 새로 시작하여 새 도구를 로드하게 하세요. claude mcp add playwright npx '@playwright/mcp@latest'

Codex CLI 또는 다른 Agent: 해당 Agent가 대응하는 브라우저 자동화/컴퓨터 사용 능력이 있는지 확인하세요(예: Playwright 기반의 MCP, 내장된 브라우저 도구 등). 자체 문서를 따라 활성화합니다. 이것을 설정하지 않아도 "직무 검색" 조사 및 자료 초안 작성 부분은 영향을 받지 않지만, 실제로 양식 페이지를 열고 제출하는 것은 불가능합니다. - 만약

이 단계는 웹 검색만 필요하며, 2단계에서 설정한 브라우저 자동화 기능은 필요하지 않습니다. 이 방식으로 워크플로우가 어떻게 작동하는지 먼저 확인한 후, 실제 지원 양식에 접촉하도록 하는 것을 권장합니다.

• 진행 대시보드 열기로 상황을 확인하세요: Windows: 더블클릭 dashboard/start-dashboard.bat

• macOS/Linux: 실행 dashboard/start-dashboard.sh

(Node.js를 먼저 설치해야 합니다. 필요한 경우, 먼저 chmod +x를 실행하세요.) - 브라우저에 다음 주소로 열립니다:
http://localhost:8420/dashboard.html

이것은 같은 디렉터리의 CSV 파일을 실시간으로 읽어옵니다. 새로고침할 때마다 최신 상태이며, 빌드나 외부 서버가 필요하지 않고 데이터는 사용자 컴퓨터를 벗어나지 않습니다.

• Windows: 더블클릭

• Agent의 도움을 받아 계속 지원하기: 한 번에 한 회사씩 처리합니다. 이 단계에서 비로소 2단계에서 설정한 브라우저 자동화 기능이 실제로 사용됩니다. Agent는 job_pool.csv, application_log.csv, blocker_queue.csv, follow_up.csv 파일을 지속적으로 업데이트합니다.

이번 제출 승인이 아직 얻어지지 않은 경우에만 전체 검증을 거쳐 일괄 요청하며, 이미 승인을 받은 경우에는 중복으로 요청하지 않습니다.

워크플로우는 기본적으로 한 번의 브라우저 도구 호출에서 모든 모듈을 완전히 작성하고, 조건이 명확할 때는 여러 인접한 모듈을 병합합니다. Agent는 확인된 정보를 집중적으로 준비하여 결과와 오류를 통합 검토 및 저장하며, 차이점만 수정합니다. 배치(batch)가 중단된 후에는 먼저 저장된 내용을 검토한 다음, 미완료된 부분부터 이어서 작성합니다. 일부 누락된 부분이 다른 작성 가능한 모듈을 방해하지 않으며, 아직 확인되지 않은 페이지와 저장되지 않은 내용을 기록합니다. 연동 컨트롤은 여전히 실제 옵션을 기다리며, 최종 제출 시에는 적용 범위 내에 이미 받은 승인을 사용합니다. 구체적인 실행 규칙은 지원 양식 매뉴얼을 참조하세요.

대시보드는 순수 정적 웹페이지와 매우 작은 로컬 Node 서버(프레임워크 없음, 빌드 불필요, 외부 종속성 없음)로 구성되어 있습니다. 여기에서 네 가지 유형의 진행 상황 보기와 중앙 대기 항목 진입점을 제공합니다:

지원 완료 (Submitted) — status = Submitted인 기록에 첨부되며, 후속 조치 타임라인과 지원 방식을 포함합니다. 특정 카드를 펼쳐서 가장 아래쪽에 있는 **