용어 확장 워크플로¶

이 문서는 현재 위키 문서에서 아직 독립 문서가 없는 확장 후보 용어를 찾고, 그 후보를 실제 문서 작업으로 연결하는 절차를 설명합니다.

목적¶

새 raw 소스를 넣지 않아도 기존 source, domain, comparison, synthesis 문서만으로 확장 여지를 찾기 위한 절차입니다. 첫 단계는 자동 추천이고, 실제 문서 생성은 사람 승인 뒤에 진행합니다.

기본 명령¶

Markdown 표로 후보를 보려면 아래 명령을 사용합니다.

python3 scripts/find_term_candidates.py

JSON 형식으로 받으려면 아래 명령을 사용합니다.

python3 scripts/find_term_candidates.py --format json --limit 20

운영 backlog 문서까지 함께 읽으려면 아래 명령을 사용합니다.

python3 scripts/find_term_candidates.py --include-docs --limit 20

보고서를 실제 운영 문서로 갱신하려면 아래 명령을 사용합니다.

python3 scripts/find_term_candidates.py --write --include-docs --limit 20

해석 규칙¶

추천 타입은 concept, entity, comparison, synthesis 중 하나입니다.
후보 강도는 strong 또는 weak입니다. 기본적으로 source를 포함해 2개 이상 문서에서 반복되거나 점수가 충분히 높은 후보만 strong으로 봅니다.
weak 후보는 entity -> concept -> comparison -> synthesis 우선순위로 재정렬해 사람이 먼저 검토할 엔티티/개념 후보를 위로 올립니다.
weak이면서 점수가 너무 낮은 후보는 기본 출력에서 제외해 단일 문장 조각 잡음을 줄입니다.
점수가 높을수록 여러 문서에서 반복되고 상위 문서에서 다시 언급된 용어입니다.
이미 독립 문서가 있는 용어는 기본적으로 후보에서 제거합니다.
첫 버전은 보수적으로 동작하므로, 중요한 용어가 빠질 수 있습니다.
--include-docs를 주면 현재는 루트 docs/ 아래 운영 메모 성격의 문서(*priorities*.md, *note*.md, *backlog*.md, *roadmap*.md)를 함께 읽어 backlog 성격의 용어를 후보에 포함합니다.
--write는 사람이 검토할 backlog 파일 term-expansion-candidates.md를 갱신합니다.
보고서 파일은 기존 상위 문서 제목의 축약 변형처럼 보이는 후보를 추가로 제외해, 직접 CLI 출력보다 더 보수적으로 큐레이션합니다.
보고서와 CLI 표 출력은 용어 컬럼에 한국어 표시명을 우선 사용하고, 필요할 때만 원문 키 컬럼에 영문 키를 따로 보여줍니다.
추출기는 기존 제목의 축약형, 번역된 제목 별칭, 조사나 접속어가 섞인 문장 조각, 단일 source에서만 나온 일반 명사·작업공간 토큰을 우선 제외하도록 보수적으로 동작합니다.

권장 흐름¶

후보 추출 명령 실행
상위 5~10개 후보 검토
실제로 독립 문서 가치가 있는 후보만 선택
concept, entity, comparison, synthesis 중 하나로 승격
관련 source, domain, index.md, log.md 갱신
make verify 실행

운영 메모¶

이 절차는 새 도메인 ingest를 대체하지 않습니다.
가장 좋은 사용 시점은 "현재 도메인을 더 깊게 파고들고 싶을 때"입니다.
추출 결과가 비어도 실패가 아니라, 현재 위키가 이미 비교적 촘촘하다는 신호일 수 있습니다.