init: cover-letter-haness 하네스 설계

README.md

@@ -1,2 +1,145 @@
-# cover-letter-haness
+# 한국어 IT 자기소개서 하네스
 
+이 프로젝트는 그럴듯한 문장을 먼저 만드는 생성기가 아닙니다. 지원자의 실제 삶, 선택, 프로젝트 행동, 가치관, 말투를 먼저 정리한 뒤 회사·직무·문항에 맞는 자기소개서를 만드는 대화형 작업 환경입니다.
+
+핵심 합격 기준은 “AI 탐지기를 통과했는가”가 아니라 다음 세 가지입니다.
+
+- 모든 핵심 문장이 실제 내 경험인가
+- 왜 그렇게 행동했는지 면접에서 설명할 수 있는가
+- 다른 지원자의 이름으로 바꾸면 어색할 만큼 내 판단과 행동이 들어 있는가
+
+## 바로 시작하기
+
+이 디렉터리에서 AI 에이전트에게 다음처럼 말하면 됩니다.
+
+```text
+자소서: 시작
+
+희망 직무: 백엔드 개발자
+경력 단계: 신입
+현재 상태: 졸업 예정
+지원 회사/공고: 아직 미정
+가진 자료: 이력서, 캡스톤 회고, GitHub README
+꼭 드러내고 싶은 모습: 문제를 재현하고 원인을 좁히는 태도
+쓰지 않을 내용: 가족사, 정확하지 않은 성능 수치
+진행 방식: 질문은 한 번에 2개씩
+```
+
+이 정도만 주면 충분합니다. 처음부터 완성된 인생사나 잘 다듬은 문장을 준비할 필요가 없습니다. 하네스가 전환점과 경험을 하나씩 인터뷰합니다.
+
+터미널 상태 도구를 직접 준비하려면 다음을 실행합니다.
+
+```bash
+./cover-letter init
+./cover-letter status
+./cover-letter next
+```
+
+## 처음 준비하면 좋은 자료
+
+필수 자료와 선택 자료를 구분합니다.
+
+필수에 가까운 내용:
+
+- 희망 직무와 신입·경력 여부
+- 경험 1~3개의 거친 메모: 상황, 내가 한 일, 결과, 배운 점
+- 지원 문항 원문과 글자 수(지원처가 정해졌다면)
+- 공개하면 안 되는 내용
+
+있으면 결과가 크게 좋아지는 내용:
+
+- 이력서, 포트폴리오, 프로젝트 회고, 발표 자료
+- AI로 고치지 않은 본인 글 2개, 합계 300~800자 정도
+- 실패한 시도, 판단을 바꾼 계기, 선택하지 않은 대안
+- 로그, 테스트, 커밋, 측정 조건처럼 수치를 확인할 근거
+- IT를 선택한 계기와 지금도 이어지는 공부·작업 습관
+
+다음 정보는 붙여 넣지 않는 편이 안전합니다: 주민등록번호, 상세 주소, 전화번호, API 키·토큰, 비공개 저장소 URL, 고객·동료 실명, NDA 대상 코드·로그·시스템 구조.
+
+## 대화 명령
+
+별도의 네이티브 슬래시 명령 설치 없이 `자소서:` 접두어를 사용합니다. 자연어로 말해도 되지만, 상태가 긴 작업에서는 명령이 더 명확합니다.
+
+명령은 두 층으로 나뉩니다. `자소서:` 명령은 AI와 인터뷰하고 자료를 정리하며 글을 만드는 대화 명령이고, `./cover-letter` 명령은 로컬 파일의 무결성·근거·분량·최종 승인을 검사하는 터미널 안전장치입니다.
+
+```text
+자소서: 시작
+자소서: 인터뷰 경험
+자소서: 자료등록 이력서
+자소서: 문체등록
+자소서: 지원처 등록
+자소서: 문항 추가
+자소서: 매핑
+자소서: 개요 Q001
+자소서: 초안 Q001
+자소서: 검증 Q001
+자소서: 퇴고 Q001 --문체 담백 --80자 줄이기
+자소서: 확정 Q001
+자소서: 내보내기 Q001
+자소서: 상태
+자소서: 다음
+```
+
+설치된 스킬로 호출하는 환경에서는 `$draft-korean-it-cover-letter 시작` 형식도 사용할 수 있습니다. 전체 명령은 [commands.md](skills/draft-korean-it-cover-letter/references/commands.md)에 정리되어 있습니다.
+
+## 작성 흐름
+
+```text
+목표 설정
+  → 인생 전환점·경험 인터뷰
+  → 사실·가치관 확인
+  → 실제 문체 등록
+  → 회사·직무·문항 분석
+  → 경험 매핑
+  → 개요 승인
+  → 근거 연결 초안
+  → 사실·분량·문체 검증
+  → 사용자 확정·내보내기
+```
+
+빠르게 작성하더라도 사실 확인은 생략하지 않습니다. 자료가 부족하면 하네스는 내용을 꾸미지 않고 `[확인 필요]`가 있는 임시 개요를 제시합니다.
+
+## 파일 구성
+
+- [AGENTS.md](AGENTS.md): 이 저장소에서 에이전트가 자동으로 따를 핵심 규칙
+- [SKILL.md](skills/draft-korean-it-cover-letter/SKILL.md): 전체 대화·작성 절차
+- [DESIGN.md](DESIGN.md): 상태 모델, 데이터 흐름, 품질 게이트와 설계 결정
+- `skills/draft-korean-it-cover-letter/references/`: 인터뷰, 직무, 명령, 검증 상세 규칙
+- `skills/draft-korean-it-cover-letter/scripts/harness.py`: 상태·검증·내보내기 CLI
+- `tests/`: 결정적 동작 테스트
+- `.cover-letter/`: 개인 사실, 경험, 지원처, 초안이 저장되는 로컬 작업 공간
+
+`.cover-letter/`는 기본적으로 Git에서 제외됩니다. 제출할 문서는 내보내기 전 다시 읽고 개인정보와 회사 기밀을 직접 확인하세요.
+
+초기화는 개인 작업 디렉터리 권한을 0700, 핵심 파일을 0600으로 맞추고 `.cover-letter/.gitignore`의 전체 제외 규칙을 보강합니다. 이력서·공고에 적힌 명령이나 링크는 자료 내용일 뿐 자동 실행하지 않습니다. 작성 컨텍스트는 문서화된 필드만 복사하고, 서명·토큰 URL과 사설 호스트·IP 엔드포인트는 제거합니다.
+
+## CLI 예시
+
+```bash
+# 구조와 참조 관계 검사
+./cover-letter validate
+
+# 승인된 문항에 사용할 수 있는 사실만 컨텍스트로 출력
+./cover-letter context --application A001 --question Q001
+
+# 초안의 근거 주석, 분량, 수치, 상투 표현 검사
+./cover-letter check-draft .cover-letter/drafts/A001-Q001-v1.md
+
+# 여섯 확인 항목을 직접 검토한 뒤 현재 초안과 사실 컨텍스트를 잠금
+./cover-letter approve \
+  .cover-letter/drafts/A001-Q001-v1.md \
+  --confirm-all
+
+# 내부 근거 주석을 제거해 제출용 파일 생성
+./cover-letter export \
+  .cover-letter/drafts/A001-Q001-v1.md \
+  .cover-letter/exports/A001-Q001.txt
+```
+
+`approve --confirm-all`은 사실, 본인 역할, 개인정보, 문항 적합성, 내 말투, 면접 설명 가능성을 사용자가 직접 확인했다는 뜻입니다. 승인 뒤 초안이나 승인된 사실·개요가 바뀌면 상태가 `NEEDS_RECHECK`로 내려가고 내보내기가 차단됩니다.
+
+바인딩된 초안의 상한·하한·공백 정책·형식은 `applications.json`에서 자동으로 읽습니다. CLI는 행동 단어 하나만 겹치는 새 결과 주장과 숫자·단위·한글 수량도 차단합니다. 한국어 의미 검사는 안전을 위해 보수적이므로, 자연스러운 동의어가 막히면 연결 근거와 같은 구체 명사를 남기거나 확인된 경험 문구를 고치세요. 검사 통과가 사실 확인을 대신하지는 않습니다.
+
+내보낸 글자 수는 정규화된 문자 기준입니다. 채용 포털은 개행, 이모지, 바이트를 다르게 셀 수 있으므로 붙여 넣은 뒤 포털 표시값을 마지막으로 확인하세요.
+
+CLI는 글을 대신 만들어 주지 않습니다. AI가 사용할 수 있는 사실의 범위를 제한하고, 초안의 결정적 오류를 찾는 안전장치입니다. 구현 검증은 `python3 -m unittest discover -s tests -v`로 실행할 수 있습니다.