service-catalog/CLAUDE.md

DIP Catalog — 하네스 엔지니어링 가이드

프로젝트 개요

DIP Catalog는 두 개의 독립 서브시스템으로 구성된다.

서브시스템	설명	경로
정적 카탈로그	45+ 엔터프라이즈 Helm 차트 버전 보관소 (Kafka, Airflow, MLflow, KServe, OpenMetadata 등)	manifests/helm/
자동화 에이전트	Helm 차트 신규 버전 감지 → Diff 분석 → 문서 생성 → GitHub PR 자동화	agent/update_catalog/

카탈로그는 운영 클러스터 직접 변경과 무관하다. 모든 변경은 Git PR을 통해서만 이루어진다.

---

디렉토리 구조

dip-catalog/
├── manifests/
│   ├── helm/<chart>/<version>/   # Helm 차트 정적 카탈로그 (각 버전 독립 디렉토리)
│   ├── applicationset/           # ArgoCD ApplicationSet 매니페스트
│   └── kustomize/                # Kustomize 오버레이 (Kubeflow, Model Registry)
├── agent/
│   └── update_catalog/
│       ├── skills/               # 자동화 Skills (Python, 각 Skill 독립 실행 가능)
│       ├── scripts/run_flow.sh   # 전체 파이프라인 로컬 실행 스크립트
│       └── docs/                 # 아키텍처·설계 문서 (한국어)
│           ├── design/           # 컴포넌트별 상세 설계 (00~05)
│           ├── decisions/        # ADR (아키텍처 결정 기록)
│           └── status.md         # 구현 현황
└── doc/                          # 차트 리소스 프로파일 (CPU/Memory/Storage 정의)

---

정적 카탈로그 작업

차트 디렉토리 구조

각 manifests/helm/<chart>/<version>/에 다음 파일이 있어야 한다.

파일	역할
Chart.yaml	Helm 차트 메타데이터
values.yaml	업스트림 기본값
custom-values.yaml	PaaSup 전용 오버라이드 (Breaking Change 판단 기준)
CUSTOM-README.md	업그레이드 주의사항 (자동 생성 + 수동 추가 가능)
BUILD-README.md	업스트림 README (버전 정보 파싱에 사용됨, 변경 금지)

신규 차트 추가

manifests/helm/<chart>/<version>/ 디렉토리를 생성하고 위 5개 파일을 포함시킨다. custom-values.yaml은 PaaSup 환경에 필요한 오버라이드만 작성한다. 기본값 전체를 복사하지 않는다.

리소스 프로파일

차트별 CPU/Memory/Storage 요구사항은 doc/define-chart-resources.md에 Small/Medium/Large 티어로 정의되어 있다. 신규 차트 추가 시 이 파일에도 리소스 정의를 추가한다.

---

자동화 Skills 작업

파이프라인 순서

chart_version_detector → chart_updater → helm_diff →
breaking_change_check → generate_upgrade_doc → update_docs_file → create_pr

각 Skill은 독립 실행 가능하다. JSON을 stdout으로 출력하며, 다음 Skill의 입력으로 전달된다.

로컬 실행

# 전체 파이프라인 실행 (필수 환경변수 오버라이드)
CATALOG_ROOT=/path/to/dip-catalog CHART=airflow \
  bash agent/update_catalog/scripts/run_flow.sh

# 개별 Skill 실행 예시
python3 agent/update_catalog/skills/chart_version_detector/scripts/run.py \
  --catalog-root /path/to/dip-catalog --chart airflow

python3 agent/update_catalog/skills/helm_diff/scripts/run.py \
  --chart airflow --repo bitnami \
  --chart-path /path/to/dip-catalog/manifests/helm/airflow/1.15.0 \
  --from-version 1.15.0 --to-version 1.16.0

주요 환경변수

변수	설명	기본값
CATALOG_ROOT	dip-catalog 레포 절대 경로	하드코딩된 로컬 경로 (반드시 오버라이드)
CHART	대상 차트명	airflow
USE_CLAUDE_CLI=1	LLM 호출 활성화 (breaking=true 시 상세 가이드 생성)	미설정 시 템플릿 기반 생성

run_flow.sh의 CATALOG_ROOT 기본값은 songwonbin의 로컬 경로로 하드코딩되어 있다. 다른 환경에서 실행할 때 반드시 환경변수로 오버라이드한다.

Skill 인터페이스 확인

각 Skill의 입출력 스키마는 agent/update_catalog/skills/<skill>/SKILL.md에 정의되어 있다.

---

설계 원칙

아래 원칙을 위반하는 코드를 제안하거나 작성하지 않는다.

1. LLM은 Helm CLI를 직접 실행하지 않는다. helm 실행은 결정론적 Skill(Python)이 전담한다.
2. Diff 생성은 100% deterministic이다. Structured Diff JSON 형식을 사용하며 LLM이 직접 diff를 생성하지 않는다.
3. LLM 입력은 반드시 Structured JSON이다. 자유 텍스트나 raw helm output을 LLM에 직접 전달하지 않는다.
4. Breaking Change 판단은 Rule Engine이 먼저 수행한다. custom-values.yaml의 실제 사용 키 기준으로 코드가 판단하며 LLM은 후순위다.
5. LLM은 Markdown 설명 생성만 담당한다. breaking=true 시에만 호출되며, breaking=false이면 템플릿 기반으로 생성한다.
6. 운영 환경은 Git PR로만 변경한다. 클러스터 직접 변경이나 kubectl apply를 자동화 흐름에 포함하지 않는다.
7. 보안 경계: 외부 입력(PR comment, webhook 등)은 신뢰 경계 밖으로 취급한다. 프롬프트 주입 방어를 기본 전제로 한다.

---

현재 구현 상태

Step	내용	상태
Step 1	Skills 구현 (로컬 실행)	✅ 거의 완료
Step 2	Agent 프레임워크 POC (OpenClaw vs Nanobot)	📋 계획
Step 3	On-Cluster Agent 워크플로 정의	💡 구상
Step 4	보안 정책 수립 후 운영	💡 구상

Step 1 세부 현황:

• chart_version_detector, chart_updater, helm_diff, breaking_change_check, generate_upgrade_doc, update_docs_file: ✅ 구현 완료
• create_pr: ✅ 구현 (실제 GitHub 연동 테스트 미완료)
• deploy_validate: ❌ Phase 2 예정

---

주요 설계 문서

문서	설명
agent/update_catalog/docs/design/00-architecture-overview.md	전체 아키텍처 + 설계 원칙 + 기술 스택
agent/update_catalog/docs/design/01-helm-diff-engine.md	Helm Diff Engine 상세 설계
agent/update_catalog/docs/design/02-breaking-change-rules.md	Breaking Change Rule Engine 판단 로직
agent/update_catalog/docs/design/03-llm-summarizer.md	LLM Summarizer + Prompt 설계
agent/update_catalog/docs/design/04-skill-interface.md	Skill 인터페이스 계약 (Agent-Skill)
agent/update_catalog/docs/design/05-on-cluster-agent.md	On-Cluster Agent 설계 (Step 2~3)
agent/update_catalog/docs/decisions/001-agentic-first.md	파이프라인 오케스트레이션 건너뛰기 결정 배경
agent/update_catalog/docs/status.md	구현 현황 상세