문서 진화 추적기은(는) 무엇을 하나요?
문서가 여러 버전을 거치며 어떻게 진화하는지 추적하는 자체 포함형 스킬입니다.
버전 제품군(v1.md, v2.md, ...` 또는 타임스탬프 파일이 있는 디렉토리)이 주어지면,
연속된 버전 간의 단락 수준 차이를 계산하고 개념 진화(도입/유지/수정/제거)를 추적합니다.
필수 워크플로우
종속성 부트스트랩 (첫 실행 시)
첫 실행 전에 이 스킬의 런타임 종속성을 확인합니다:
- 핵심: 순수 표준 라이브러리 — 설치 불필요.
- 선택 사항:
PyYAML(설정이.yaml인 경우에만 필요; JSON 설정은 표준 라이브러리만으로 동작).
PyYAML이 없고 설정이 YAML인 경우, 사용자에게 알리고 pip install pyyaml을 설치할지 물어보세요. 사용자가 확인한 후에만 설치하세요. 명시적 동의 없이 전역 환경에 절대 설치하지 마세요.
- 설정 로드 (
config/examples/family.json참조; YAML 설정도PyYAML이 설치된 경우 지원). versions_dir에 최소 두 개의 버전 파일이 있는지 확인.python -m src.cli run --config <경로> [--concepts "A,B"]실행.- 전환 횟수를 보고하고 사용자에게
./evolution/evolution_<추적ID>.{md,json}파일을 안내.
사용 시기
- 시간 순서 또는 순차적으로 명명된 문서 버전 제품군을 시간 경과에 따라 비교해야 할 때.
- 사용자가 "문서 변경 추적", "버전 기록", "초안 간 변경 사항", "개념 계통"을 요청할 때.
- 명명된 개념(용어, 제목, 정의 등)이 초안 간에 언제 도입, 수정, 또는 제거되었는지 추적해야 할 때.
- 초안의 진화를 단일 종단 간 차이가 아닌 타임라인으로 보고해야 할 때.
사용 예시
# 설정을 검증하고 발견된 버전 파일을 확인
python -m src.cli validate --config config/examples/family.json
python -m src.cli versions --config config/examples/family.json
# 추적기 실행; 선택적으로 추적할 개념 이름 지정
python -m src.cli run --config config/examples/family.json --concepts "엔트로피,분배 함수"
보고서는 ./evolution/evolution_<추적ID>.{md,json}에 작성됩니다. 마크다운 타임라인은 사람이 읽기 위한 것이고, JSON은 프로그램 처리용입니다.
오류 처리
- 설정이 유효하지 않음 (
validate가 0이 아닌 종료 코드 반환) - 보고된 필드를 수정하고 재검증; 명명 규칙과versions_dir이 일반적인 원인입니다. - 발견된 버전이 2개 미만 - 실행이 중단됩니다;
version_naming규칙을 실제 파일 이름과 비교하여 다시 시도하세요. - 개념이 전혀 나타나지 않음 - 모든 버전에서 부재로 보고됩니다. 이는 유효한 결과이며 오류가 아닙니다.
- 예상치 못한 종료 코드 - 메시지를 그대로 보고하고, 수동으로 파일을 비교(diff)하지 마세요.
차이 분석 세분화
| 세분화 | 분할 규칙 |
|---|---|
line | 비어 있지 않은 줄 |
paragraph (기본값) | 빈 줄로 구분된 블록 |
sentence | 구두점으로 구분된 문장 |
한계
- 차이 분석은 구조적(difflib를 통한 블록 정렬)이며, 의미론적이지 않습니다. 개념은 해당 구절(대소문자 구분 없음)이 버전 텍스트에 정확히 나타날 때만 "존재"하는 것으로 간주합니다.
sequential/timestamp이외의 사용자 정의 명명 규칙은 지원되지 않습니다.