Knowledge Catalog — 메타데이터를 코드로 관리하고 에이전트로 보강하기

분석 기준: 83c83d62fbef41902d9a5e4d71873743f8a521cc. 공식 저장소의 문서·설정·소스를 대조했습니다. 이 글의 설치·실습 명령은 독자를 위한 예시이며, 분석 중 프로젝트 설치·빌드·모델 호출은 실행하지 않았습니다.

1프로젝트 한줄 요약

Google Cloud Knowledge Catalog와 연결되는 도구·에이전트·샘플 저장소입니다. 중심 도구 kcmd는 YAML·Markdown 메타데이터와 카탈로그 서비스를 양방향 동기화하고, enrichment 에이전트는 외부 문서 등에서 근거를 찾아 자산 설명을 보강합니다. 저장소 전체를 Gemini 문서 생성 에이전트 하나로 설명하기에는 범위가 넓습니다.

루트 README는 이 저장소의 내용이 공식 Google 제품은 아니라고 명시합니다. 관리형 Knowledge Catalog 서비스와 이 샘플 구현의 지원 범위를 구분합니다.

2왜 주목받는가

데이터 설명을 콘솔에서만 고치면 변경 검토와 재현이 어렵습니다. 메타데이터를 파일로 내려받아 Git diff·검토·배포 흐름으로 다루는 것이 이 도구의 핵심입니다. 테이블 의미를 사람이 읽는 설명으로만 끝내지 않고 에이전트가 사용할 카탈로그·semantic model·스킬로 연결합니다.

2026-10-30 전체 카탈로그 기준 검토에서 현재 구조를 확인했습니다. 특정 기능이 TrendShift 순위 상승을 일으켰다고 추정하지 않습니다.

3기술 스택 전체 지도

현재 mdcode package.json의 이름은 kcmd, 버전은 0.1.0이지만 CLI 소스의 version 표기는 1.0.0입니다. 둘이 일치한다고 설명하지 않습니다. 루트 Apache-2.0 안내와 package의 ISC 표기도 달라 실제 배포물별 고지를 확인해야 합니다.

4아키텍처 심화 분석

Cloud catalog / BigQuery metadata
              ↕ kcmd pull / push
       catalog.yaml + YAML entries + sidecar Markdown
              ↕ reviewed file changes
    enrichment agent ← MCP fileset / 조직 문서
              ↓
   개선된 설명·인용·카탈로그 또는 semantic model 배포

manifest는 scope와 가져올 entry·aspect, 다시 게시할 aspect를 구분합니다. pull은 스냅샷을 가져오고, push는 마지막 pull 이후 로컬 변경을 원격 상태와 비교하며 반영합니다. status로 로컬 변경을 확인할 수 있습니다. 강제 옵션은 충돌 보호를 우회할 수 있으므로 일반 예시에 넣지 않습니다.

Semantic model은 설명 파일 게시보다 넓은 작업입니다

semantic-model scope의 push는 Knowledge Catalog 항목뿐 아니라 배포 대상에 따라 BigQuery Graph·Spanner Graph의 DDL을 실행할 수 있습니다. --validate-only는 적용 없이 검증하는 옵션입니다. --no-kc·profile·deployment 옵션은 모델 구성에 따라 조합 제한이 있으므로 최신 CLI 정의를 확인합니다.

에이전트 실행과 파일 동기화를 분리합니다

toolbox/enrichment/src/agent/enrich/agent.ts는 ADK Agent와 Vertex AI의 gemini-2.5-flash를 구성합니다. 이 모델명은 해당 소스의 설정값입니다. 에이전트는 기존 메타데이터와 출처를 읽고 설명을 합성한 뒤 update_documentation 도구로 변경합니다. 도구 실행·원격 쓰기·모델 비용이 발생하는 경로이며 단순 로컬 파일 열람과 다릅니다.

5디렉토리 구조 해부

toolbox/
  mdcode/
    src/libts/       manifest·snapshot·sync·semantic 변환
    src/tool/        kcmd 명령·MCP server
    docs/            개념·semantic model 사용법
  enrichment/
    src/agent/       ADK 실행·도구·enrich agent
    src/tools/md/    문서 fileset MCP
okf/                기존 형식·자료
samples/            기능별 샘플

먼저 toolbox README에서 두 도구의 책임을 나누고, mdcode/src/tool/main.ts에서 옵션을 확인한 뒤 libts의 동기화·백엔드 코드를 따라갑니다. 기존 OKF 자료만으로 현재 CLI를 이해할 수는 없습니다.

6학습 포인트

• Metadata as Code: 데이터와 설명·정책의 변경 이력을 분리해 검토하는 구조를 배웁니다.
• 동기화 충돌: 로컬 수정과 원격 수정이 겹치는 경우 무조건 덮어쓰기보다 기준 스냅샷이 필요한 이유를 추적합니다.
• 도구 경계: 에이전트가 만든 설명을 로컬 파일에 남기는 단계와 원격 publish를 구분합니다.
• 다중 backend: 같은 semantic model이 서로 다른 graph DDL로 변환될 때 지원되지 않는 표현을 어떻게 처리하는지 봅니다.

7하드웨어·시스템 요구사항과 설치

로컬 소스 개발에는 npm·TypeScript·Bun 빌드 경로가 있습니다. Cloud 카탈로그 조회·게시에는 Google Cloud 프로젝트·서비스 접근 권한·gcloud 인증이 필요합니다. 보강 에이전트에는 Vertex AI 모델 접근도 필요합니다. GPU를 로컬에 설치하는 프로젝트는 아닙니다.

# 독자가 자신의 시험 환경에서 선택할 흐름
kcmd init --bigquery-dataset my-project.demo
kcmd pull
kcmd status
# 변경·권한·대상을 확인한 뒤에만 push를 선택

CLI는 gcloud에서 토큰을 얻습니다. 실제 운영 데이터셋 대신 시험 자산을 사용하고, 원격 조회·DDL·모델 호출의 비용과 권한을 구분합니다. 이 분석에서는 인증 설정·Cloud 자원·모델을 실행하지 않았습니다.

8직접 해볼 수 있는 실습 과제

1. 기초: 샘플의 catalog.yaml과 entry YAML·sidecar Markdown을 연결해 scope·aspect·본문을 구분합니다.
2. 중급: main.ts의 init·pull·status·push 옵션을 읽고 각각 로컬·원격 중 무엇을 바꿀 수 있는지 표로 만듭니다.
3. 중급: 자신의 시험 프로젝트에서 스냅샷을 만든 뒤 설명 한 줄을 바꾸고 status·diff를 검토합니다.
4. 심화: semantic-model push의 validate-only 경로와 실제 DDL 실행 경로를 비교합니다.
5. 심화: enrichment의 fileset 도구와 Agent 구성을 읽고 인용 없는 생성 설명을 검토하는 절차를 설계합니다.

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

• README.md
• toolbox/README.md
• toolbox/mdcode/README.md
• toolbox/mdcode/package.json
• toolbox/mdcode/src/tool/main.ts
• toolbox/enrichment/README.md
• toolbox/enrichment/src/agent/enrich/agent.ts