도메인 ingest 패턴

이 문서는 새 실제 프로젝트 문서를 위키에 들일 때 어떤 최소 문서 세트를 만들지 정리합니다. 현재 저장소에서는 chemical과 timebooks 사례를 통해 이 패턴이 검증되었습니다.

기본 흐름

새 도메인 ingest는 아래 순서를 따릅니다.

1. raw/imports/에 원문 보관본 추가
2. wiki/source-*.md 소스 요약 생성
3. 핵심 concept 1개 이상 생성 또는 기존 개념 확장
4. 핵심 entity 1개 이상 생성 또는 기존 엔티티 확장
5. 의미 있는 comparison 1개 이상 추가
6. 필요하면 도메인 전체를 묶는 synthesis 문서 추가
7. index.md, log.md 갱신

최소 문서 세트

새 도메인을 처음 들일 때는 보통 아래 조합이 가장 안정적입니다.

• raw/imports/<domain>.md
• wiki/source-<domain>.md
• wiki/concept-<core-idea>.md
• wiki/entity-<system-or-product>.md
• wiki/comparison-<main-tradeoff>.md
• 필요하면 wiki/synthesis-<domain-view>.md

문서가 제품 README보다 기능 명세에 가깝다면 concept와 entity를 보안, 인증, 데이터 모델, 운영 제어 같은 구조 축에 맞춰 잡습니다.

어떤 문서를 소스로 우선 볼 것인가

도메인 ingest에서 같은 저장소 안에 여러 Markdown 문서가 있다면 아래 우선순위를 따릅니다.

1. README.md, PROJECT_STATUS.md, spec.md
2. HANDOFF.md, PROJECT_HANDOFF.md, *_HANDOFF*.md
3. CHANGELOG.md
4. TODO.md

각 문서군의 용도는 다르게 봐야 합니다.

• README, PROJECT_STATUS, spec: 도메인의 기본 source로 가장 적합합니다.
• HANDOFF: 현재 상태, 읽기 순서, 핵심 결정, 남은 이슈가 압축돼 있어 source 또는 synthesis 보강용 소스로 적합합니다.
• CHANGELOG: 최근 변경점과 검증 명령, 영향 파일을 빠르게 파악하는 데 유용합니다. 전체 누적본을 그대로 요약하기보다 최근 섹션만 선택적으로 ingest하는 편이 좋습니다.
• TODO: 구현 전 계획과 미진행 항목이 섞여 있으므로 기본 source로는 쓰지 않습니다. 후보 발굴과 운영 메모 보강용 참고 문서로만 사용합니다.

언제 확장하는가

• 소스가 다른 도메인과 분명히 다른 핵심 개념을 가지면 새 concept를 만듭니다.
• 소스가 명명된 시스템, 제품, 운영 계층을 소개하면 entity를 만듭니다.
• 소스가 설계 선택의 trade-off를 분명히 드러내면 comparison을 만듭니다.
• 도메인 문서가 4~6개 이상으로 늘어나면 synthesis 문서로 상위 요약을 만듭니다.

현재 사례

• chemical: 제품 가치, BFF 인증, 테넌트 격리, 배포/보안 구조를 함께 다룸
• timebooks: 학습 탐색, 정렬 에지, 리뷰, 정책, 분석, 운영 포털을 함께 다룸

운영 원칙

• 새 문서는 기존 도메인 묶음과 상호 링크를 가져야 합니다.
• 각 source 문서는 최소 하나 이상의 concept, entity, comparison 문서로 직접 연결돼야 합니다.
• raw/imports/에 넣은 보관본마다 대응하는 wiki/source-*.md 문서가 있어야 합니다.
• HANDOFF, CHANGELOG를 raw로 보관할 때는 "현재 상태"와 "최근 변경"을 설명하는 보조 source로 취급하고, 기존 README/spec source와 역할을 섞지 않습니다.
• TODO는 구현 계획과 미확정 항목이 많으므로 raw로 보관하더라도 직접적인 사실 source보다 후보 발굴용 참고 자료로만 읽습니다.
• source 문서의 updated를 바꿨다면 같은 날짜의 log.md 항목에서 해당 파일이 언급돼야 합니다.
• concept, entity, comparison은 같은 변경에서 함께 갱신하더라도, freshness 기준점은 source 문서 하나로 유지합니다.
• index.md는 frontmatter 기준 정렬을 유지합니다.
• ingest 후에는 반드시 python3 scripts/verify_wiki.py를 실행합니다.