Knowledge · Taxonomy 디자인 컨셉

조사 결론

이 설계의 중심은 지능과 결정성을 분리하는 것이다. 사람이나 LLM은 taxonomy가 공개한 digest 안에서 후보 observations를 제안할 뿐이다. canonical 값 결정, alias 치환, 타입·cardinality· 참조 무결성 검증, 저장 허용 여부는 코드가 결정한다.

Schema & governance

projects/taxonomy

운영 JSON 번들, SemVer, vocabulary·alias·deprecated·entity model의 개정 규칙을 소유한다.

source of truthcontractgovernance

Search runtime

projects/taxonomy-query

번들을 입력으로 받아 digest·검증·인덱싱·tags/BM25/hybrid 검색·웹 챗을 실행한다.

consumerOpenSearchfeedback

핵심 디자인 컨셉

Closed 허용된 category·attribute·term만 선택한다. 자유 태그는 저장 계약 밖이다.

Orthogonal 분류·속성·객체를 분리해 blue_dress 같은 조합 폭발을 막는다.

Versioned 번들은 SemVer를 가지며 schema version이 검색 인덱스 이름에도 반영된다.

Validated LLM 출력은 신뢰하지 않는다. ERROR가 하나라도 있으면 저장을 거부한다.

Taxonomy와 Folksonomy의 관계

Folksonomy

누구나 임의 태그를 추가해 빠르지만 동의어·표기 변형·언어 차이가 누적된다.

framework · frameworks · 프레임워크

이 프로젝트의 선택

canonical term을 통제하고 alias가 입력 편의를 흡수한다. deprecated lifecycle로 과거 데이터도 수용한다.

aliases → canonical → lifecycle policy

세 축의 직교 모델

Category무엇인가 / 어디에 속하는가
계층 트리의 위치

Attribute + Vocabulary어떤 성질인가
타입과 허용값

Entity대상 속 어떤 객체인가
선택적 객체·관계 계층

단일 번들의 5계층

`TaxonomyFile` 구성과 책임
계층	질문	핵심 필드	불변식
Vocabulary	어떤 값을 허용하는가?	term, aliases, status, color_code	term 유일, active/deprecated lifecycle
Attribute	어떤 성질을 어떤 타입으로 기록하는가?	key, type, cardinality, vocab_ref	enum/color는 vocab_ref 필수, 나머지는 금지
Category	대상을 계층 어디에 놓는가?	parent_id, search_path, bindings	고아·자기참조·순환 금지, path 유일
Entity Model	대상 내부 객체와 관계를 따로 질의해야 하는가?	entity_types, relation_types	정의된 type과 유효 endpoint만 참조
Normalization / Rules	입력을 어떻게 canonicalize하고 진화시키는가?	unicode, alias order, deprecated policy, multi_category	명시된 순서·수용·경고 정책 적용

상속과 override

Category의 유효 attribute 계약은 root→현재 node 경로를 따라 계산된다. inherit_attributes=false면 누적 binding을 초기화하고, 자식 binding은 같은 key의 부모 binding을 덮어쓴다. override.allowed_terms는 넓은 vocabulary를 특정 category에서만 좁힌다.

Vocabulary: colors = [red, blue, green, ivory, ...]
Attribute: dominant_color → colors
Category: dress
  └─ binding dominant_color
       └─ allowed_terms = [red, blue, ivory]

LLM 태깅 파이프라인

LLM은 schema 작성자가 아니라 제안자다. 저장 경로는 항상 동일한 결정적 validator를 통과한다.

Validate taxonomy번들의 SemVer, ID, path, 참조, 순환, alias 충돌을 검사한다.
Build digest상속·override를 해석해 category별 유효 계약만 압축 제공한다.
Propose observations사람 또는 LLM이 category·attributes·entities·relations 후보를 만든다.
Normalize & validatealias, 타입, cardinality, required, deprecated, 관계 endpoint를 검사한다.
Persist통과한 canonical record만 frontmatter/sidecar 또는 검색 인덱스에 기록한다.

이중 방어 사전에는 digest와 JSON 구조로 선택지를 제한하고, 사후에는 buildTagRecord()로 다시 검증한다. ERROR가 있으면 record가 생성되지 않으며 파일은 바뀌지 않는다.

문서 태깅과 검색어 태깅의 차이

Document

문서 저장용 태깅은 category에 바인딩된 required attribute를 모두 요구한다.

Query

짧은 검색어는 모든 필수값을 알 수 없으므로 requireRequired: false로 부분 태깅을 허용한다.

거버넌스와 저장 경계

결정 권한과 데이터 변경 위치
행위	소유 프로젝트	저장 위치	규칙
term/category/attribute 개정	taxonomy	`projects/taxonomy/bundles/*.json`	SemVer, alias/deprecate 우선, 삭제로 하위 호환 파괴 금지
문서 frontmatter 태깅	taxonomy	`meta_tags:` namespace	기존 type/topics/status 보존, dry-run 기본, `--write` 명시
이미지 태깅	taxonomy	`.meta-tags.json` sidecar	원본 이미지 비파괴
검색용 태깅	taxonomy-query	untracked cache + OpenSearch	vault 파일을 수정하지 않음
운영 품질 피드백	taxonomy-query → taxonomy	untagged 사유, bench 결과	runtime은 schema를 직접 수정하지 않음

Deprecated lifecycle

기존 term은 즉시 삭제하지 않고 deprecated로 전환한다. accept_input, store_as_canonical_if_possible, warn_on_use가 과거 입력 수용·canonical 치환·경고를 각각 결정한다. 현행 두 운영 번들은 모두 입력 수용과 경고를 활성화한다.

현행 운영 번들

knowledge.json · v2.0.0

7 vocab · 45 terms

15 attributes · 29 categories · entity model 없음

지식 문서
- 유형별 가이드
  - 프레임워크 문서
  - 도구 문서
  - 개념 문서
- 상태별 개요
- 주제별 탐색
- 워크플로우 과정

background.json · v2.0.0

6 vocab · 36 terms

10 attributes · 18 categories · 5 entity types · 4 relation types

배경 사진
- 자연
  - 하늘
  - 산과 언덕
  - 숲과 나무
  - 바다와 강
- 도시
- 실내
- 추상

두 번들은 같은 스키마를 사용하지만 도메인 복잡도에 따라 Entity Model 채택 여부가 다르다. 지식 문서는 문서 전체 metadata로 충분해 entity model이 없고, 배경 사진은 장면 속 객체·관계가 필요해 고급 계층을 사용한다.

검색 런타임 컨셉

Version isolation

스키마별 인덱스

taxo-<slug>-v<version> 규칙으로 schema version이 바뀌면 새 인덱스를 사용한다.

Privacy / footprint

원문 전체 미저장

현재 인덱스에는 summary와 앞 800자의 excerpt만 저장하고, 웹 챗은 로컬 vault 원문을 읽는다.

Resilience

검색 강등

Hybrid에서 태그 유추가 실패하면 BM25로 자동 강등해 검색 전체 실패를 막는다.

세 검색 모드

검색 전략과 실패 시 동작
모드	질의	LLM	실패 시
tags	canonical category/attribute term 중심	기본 필요	태그 유추 실패로 종료
bm25	title/summary/excerpt 텍스트	불필요	그대로 실행
hybrid	BM25 + 태그 match boost	기본 필요	BM25로 강등

현재 구현 기준 정정 2026-07-15 초기 design spec은 인덱스에 본문 전체를 저장한다고 적었지만, v0.4.0 코드의 현재 매핑은 summary와 excerpt만 가진다. 이 문서는 현재 코드와 프로젝트 README를 기준으로 정리했다.

현재 상태와 확정된 한계

2026-07-20 조사 시점
항목	상태	사실
스키마·거버넌스	paused	방법론·번들·태깅 스킬·dry-run 파일럿까지 완료. vault 전량 적용은 범위 밖으로 이관.
검색 런타임	implemented	인덱싱, tags/BM25/hybrid, bench, 로컬 웹 챗과 에이전트 스킬 구현 완료.
기존 topics 마이그레이션	not done	현재 `wiki/topics`와 frontmatter `topics`는 계속 사용 중이며 `meta_tags` 전량 기록은 하지 않았다.
최신 bench	backlog	기존 hybrid P@5 0.27 / MRR 0.82는 전문 body 인덱스 시점 수치다. summary/excerpt 스키마 기준 재실행은 남아 있다.

근거 맵

Vault 내부 진실원과 현재 TypeScript 구현만 사용했다. 외부 일반론은 추가하지 않았다.

wiki/taxonomy-meta-tagging.md:13–92 — 일반 설계 원칙
projects/taxonomy/README.md:20–65 — 역할·경계·프로젝트 결정
taxonomy-builder-spec.md:17–180 — 5계층과 검증 규칙
projects/taxonomy/bundles/knowledge.json — 지식 문서 운영 taxonomy
projects/taxonomy/bundles/background.json — Entity Model 포함 예시
projects/taxonomy-query/README.md:20–46, 91–109 — 런타임 경계와 현행 상태
src/types.ts:104–223 — TaxonomyFile·MetaTags·Digest 계약
src/digest.ts:12–104 — 상속·override 해석
src/tag.ts:29–197 — 타입·term·entity 검증
src/cli-main.ts:129–205 — digest/tag 저장 게이트
src/search/ingest.ts:29–135 — 캐시·LLM·인덱싱
src/search/mapping.ts:7–39 — 현재 OpenSearch 매핑

조사 방법

Vault 운영 규칙과 query output template을 먼저 확인하고, project README·wiki 개념 문서·운영 번들을 읽었다. CodeGraph로 TaxonomyFile, buildDigest, buildTagRecord, ingestDocs, buildIndexMapping의 구조와 호출 관계를 추적했다. 번들 통계는 JSON 원본에서 직접 집계했다.