DenisSergeevitch/ex-ussr-kinship-research

Evidence-first genealogy skill for AI agents (Codex, Claude Code): church books, civil, military, deportation and repression records across the former USSR. Replies in your language.

이 프로젝트가 무엇인가

ex-USSR Kinship Research는 AI 코딩 에이전트(Codex나 Claude Code 등)를 구소련, 소비에트 연방, 러시아 제국의 신중한 가족사 연구자로 바꾸는 일련의 지침과 도구입니다. 웹사이트나 데이터베이스가 아니라 AI 에이전트의 작업 환경에 설치하는 "스킬"로, 교회 기록, 민사 기록, 군사 파일, 강제 이주 및 탄압 문서, 색인되지 않은 아카이브 스캔을 사용하여 조상을 추적하는 데 도움을 줍니다.

핵심 아이디어는 증거 우선입니다. 에이전트는 모든 발견을 추적 가능하게 유지하고, 원시 기록과 자체 해석을 명확히 분리하며, 입증된 것과 입증되지 않은 것을 명확히 밝힙니다.

대상 범위

구소련의 15개 공화국 모두: 러시아, 우크라이나, 벨라루스, 몰도바, 에스토니아, 라트비아, 리투아니아, 조지아, 아르메니아, 아제르바이잔, 카자흐스탄, 키르기스스탄, 타지키스탄, 투르크메니스탄, 우즈베키스탄. 스킬의 내부 지침은 러시아어로 작성되었지만, 에이전트는 사용자의 언어(영어, 우크라이나어, 러시아어, 폴란드어, 독일어 등)로 대화하고, 출처를 원래 철자와 번역으로 인용하며, 기록의 언어로 검색 쿼리를 구성합니다.

실제 기능

케이스 접수 및 범위 — 하나의 연구 질문, 알려진 사실, 생존 가능성이 있는 사람, 금지 사항을 제공합니다.
재현 가능한 레지스터 — 사람, 아티팩트, 주장, 관계의 구조화된 기록과 전체 검색 로그(CSV 파일)를 유지하며, 최종 보고서 템플릿도 포함합니다.
역사적 관할권 모델 — 각 이벤트는 오늘날의 지도가 아니라 이벤트 시점의 국가, 주, 지구, 교구 또는 민사 등록소로 해결됩니다. 이 지역에서는 국경과 행정 구역이 끊임없이 변했기 때문에 중요합니다.
이름 변형 매트릭스 — 개혁 전 러시아어, 우크라이나어, 폴란드어, 루마니아어, 독일어, 이디시어 이름 형태, 부계명, 결혼 전 성, 음역을 처리하여 같은 사람이 다른 철자로 놓치지 않도록 합니다.
출처 전략 — 원본을 최우선으로 하고, 그 다음 공식 카탈로그, 색인, 출판된 문서 컬렉션을 사용하며, 가계도와 포럼은 단서로만 사용합니다.
증거 프로토콜 — 주장에는 hypothesis, single-source, corroborated, strongly-corroborated, contradicted, unresolved와 같은 상태가 부여되며 백분율이 아닙니다. 동일한 기록의 사본은 independence_group을 공유하므로 독립적인 증거로 간주되지 않습니다.
신원 해결 — 같은 이름의 사람들은 구별 증거(집 번호, 부모, 대부모, 정확한 생년월일 또는 군대 부대)가 나타날 때까지 별도의 항목으로 유지됩니다.
감사 스크립트 — 모든 참조의 일관성을 확인하고 결론을 쓰기 전에 약한 입증을 표시합니다. 또한 최종 보고서를 검증합니다: 인용된 모든 ID가 레지스터에 존재해야 하며 모든 상태가 일치해야 합니다.
최종 보고서 — 각 관계 엣지를 하나씩 제시하며, 모순, 실패한 검색, 구체적인 다음 단계를 포함합니다.

설치 및 사용 방법

리포지토리를 AI 에이전트의 스킬 폴더에 클론합니다:

# Codex용
git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.codex/skills/ex-ussr-kinship-research

# Claude Code(개인 스킬)용
git clone https://github.com/DenisSergeevitch/ex-ussr-kinship-research ~/.claude/skills/ex-ussr-kinship-research

그런 다음 가족에 대한 질문을 평이한 언어로 설명하기만 하면 됩니다. 예:

"제 증조부는 1930년대에 카자흐스탄으로 유배되었습니다. 교회 기록에서 그의 부모를 찾는 것을 도와주세요."
"결혼 증명서와 군인 카드 스캔이 있습니다. 같은 사람인지 확인하고 증거 체인을 구축해 주세요."
"1890년대 포돌리아의 한 마을에 대한 교구와 적절한 FamilySearch 필름을 찾고 성 X의 출생 기록을 읽어 주세요."

스킬 폴더에서 실행할 수 있는 명령줄 스크립트도 있습니다:

init_case.py — 새 연구 케이스를 시작합니다(--force를 사용해도 스킬 폴더 내부에서 생성하는 것을 거부합니다)
hash_artifact.py — 저장된 각 스캔 또는 문서에 대한 SHA-256 해시를 계산합니다
audit_evidence.py — 최종 보고서를 작성하기 전에 레지스터를 확인합니다
build_pdf.py — HTML 보고서를 PDF로 변환합니다(Chrome, Chromium 또는 Edge 설치 필요)

스크립트에는 Python 3와 표준 라이브러리만 필요합니다. build_pdf.py는 추가로 Chromium 기반 브라우저가 필요합니다. 개인 케이스 데이터는 스킬의 Git 체크아웃 외부에 보관해야 합니다.

리포지토리 구조

프로젝트는 다음과 같이 구성됩니다:

SKILL.md — 주요 지침(워크플로우, 하드 규칙, 언어 정책)
references/ — 상세 가이드: 출처 전략, 증거 프로토콜, 로케일 가이드(관할권, 이름 변형, 달력, 기록 유형), 브라우저 및 CAPTCHA 처리, 개인정보 보호 및 안전, 선별된 시작 출처, 현장 교훈, 변경 로그, 사진 검색, 합스부르크 갈리치아/부코비나 가이드
assets/ — 케이스 접수 템플릿, CSV 레지스터 템플릿, 최종 보고서 템플릿, 사진 README 템플릿, 읽기 쉬운 PDF 템플릿
scripts/ — 위에서 언급한 4개의 Python 스크립트
evals/ — 트리거 및 추론 테스트 케이스
tests/ — 단위 테스트

책임 있는 사용 규칙

이 스킬에는 명확한 가드레일이 있습니다:

가족 역사이지 감시가 아님 — 살아있는 사람의 현재 주소, 전화, 계정을 조회하는 것을 거부하고 보고서에서 그들의 데이터를 최소화합니다.
우회 금지 — CAPTCHA 해결, 페이월/지역 차단/속도 제한 회피, 유출 데이터베이스 사용이 없습니다. 로그인은 사용자가 수행합니다.
명시적 동의 없이 문서나 DNA 데이터를 제3자 서비스에 업로드하지 않습니다.
민감한 발견(강제 이주, 탄압, 입양, DNA 놀라움)은 중립적으로, 질문이 요구하는 범위 내에서만 보고됩니다.
아카이브 접근 규칙은 변경됩니다 — 스킬은 아카이브 요청 초안만 작성합니다. 절대 보내지 않으며, 항상 현재 공식 절차를 확인해야 합니다.

기여 및 라이선스

references/seed-sources.md에 새로운 출처를 환영합니다 — 검증된 소유자, 관할권, 컬렉션, 출처, ID, 접근, 제한 사항, 알려진 경우 확인 날짜를 포함하세요. 공백은 추측이 아니라 표시해야 합니다. 개인 데이터는 예제에서 제외해야 합니다.

요약

구소련에 조상이 있고 AI 에이전트로 연구하고 싶다면, 이 스킬은 그 에이전트에게 훈련된 증거 기반 워크플로우를 제공합니다: 역사적 관할권을 이해하고, 언어 간 이름 변형을 처리하며, 입증된 것과 입증되지 않은 것을 엄격히 추적하고, 검증 가능한 최종 보고서를 생성합니다 — 개인정보 보호와 접근 규칙을 존중하면서.