service-catalog/agent/update_catalog/docs/design/03-llm-summarizer.md

LLM Summarizer + Docs Updater 설계

1. 개요

Structured Diff JSON과 Breaking Change 판단 결과를 입력받아 자연어 업그레이드 주의사항 문서를 생성하고, 해당 차트 버전의 CUSTOM-README.md에 반영한다.

LLM의 유일한 역할: Structured JSON → Markdown 문서 변환. Diff 생성이나 Breaking 판단은 수행하지 않는다.

---

2. LLM Summarizer

2.0 실행 조건

• generate_upgrade_doc은 항상 실행한다 (breaking 여부 무관).
• breaking=true → LLM을 사용하여 custom-values.yaml 수정 방법을 포함한 상세 가이드 생성.
• breaking=false → 템플릿 기반 간단 요약 생성 (LLM 미호출).

카탈로그는 신규 배포를 위한 차트 보관소이므로, breaking 여부와 무관하게 모든 업그레이드에 주의사항 기록이 필요하다.

2.1 입력

{
  "chart": "airflow",
  "from_version": "1.2.3",
  "to_version": "1.3.0",
  "values": { ... },
  "templates": { ... },
  "crd": { ... },
  "dependencies": { ... },
  "breaking": true,
  "severity": "high",
  "breaking_reasons": [
    {
      "type": "values_key_removed",
      "key": "ingress.enabled",
      "detail": "custom-values.yaml에서 사용 중인 key가 삭제됨 — 수정 필요"
    }
  ],
  "warnings": [
    {
      "type": "service_port_changed",
      "resource": "Service/airflow-webserver",
      "detail": "port changed from 8080 to 8081"
    }
  ],
  "docs_context": {
    "CUSTOM-README.md": "..."
  }
}

dip-catalog 구조에서는 버전 디렉토리 내 CUSTOM-README.md 내용을 docs_context로 제공한다.

2.2 Prompt 설계

당신은 Kubernetes Helm 업그레이드 주의사항 문서를 작성하는 전문가입니다.

두 Helm 차트 버전 간 변경점을 담은 Structured Diff JSON이 제공됩니다.
이 카탈로그는 신규 배포를 위한 것이며, custom-values.yaml 수정 필요 여부가 핵심입니다.

## 작업
1. 핵심 변경 사항을 평문으로 요약합니다.
2. custom-values.yaml 수정이 필요한 항목(breaking_reasons)을 상세히 설명합니다.
3. 신규 배포 시 참고할 주의사항(warnings)을 기록합니다.
4. 아래 형식의 간결한 Markdown 문서를 생성합니다.

## 규칙
- 입력 JSON에 없는 내용은 절대 추가하지 마세요.
- 추측하지 마세요.
- docs_context는 보조 설명에만 사용하고, diff에 없는 변경을 추가하지 마세요.
- errors가 있으면 분석이 불완전할 수 있음을 명시하세요.
- 배포 담당자가 바로 참고할 수 있도록 명확하게 작성하세요.

## 출력 형식
아래 Markdown 구조를 정확히 지키세요 (`## {to_version}` 헤더는 포함하지 마세요 — `update_docs_file`이 관리):

### 변경 요약
- from_version: <from_version>
- to_version: <to_version>
- <핵심 변경 사항 bullet points>

### custom-values.yaml 수정 필요 항목
<breaking=true면 항목별 수정 방법>
<breaking=false면 "없음">

### 배포 시 주의사항
<warnings가 있으면 나열>
<없으면 섹션 생략>

### 참고
- severity: <severity>
- breaking: <true/false>

---

Input:
<Structured Diff JSON>

2.3 토큰 예산 관리

대형 chart(airflow, kafka 등)는 Structured Diff JSON이 매우 클 수 있다.

전략	설명
중요도 기반 필터링	breaking_reasons와 changed 항목만 포함, unchanged는 제외
template diff 요약	리소스별 상세 diff 대신 변경된 리소스 목록만 전달
청크 분할	values / templates / crd를 각각 별도 LLM 호출 후 결과 합산
토큰 상한 설정	입력 JSON 최대 크기 제한 (예: 50,000 tokens), 초과 시 요약 버전 사용

2.4 출력 검증

• 금지 규칙: 입력 JSON에 없는 버전/리소스를 언급하면 실패 처리.
• 서식 검증: Markdown 구조가 규정과 다르면 1회 재생성, 실패 시 fallback 템플릿으로 대체.
• 요약 품질 기준: breaking_reasons 누락/허위 서술은 오류로 간주.

2.5 예상 출력 (breaking=true)

update_docs_file이 ## {to_version} 헤더를 추가하므로, LLM 출력은 ### 수준부터 시작한다.

### 변경 요약
- from_version: 1.2.3
- to_version: 1.3.0
- Image tag 1.2.3 → 1.3.0 업데이트
- CPU limit 기본값 추가 (all containers)
- 새 환경변수 `AIRFLOW__CORE__NEW_SETTING` 추가 (scheduler)

### custom-values.yaml 수정 필요 항목
- **`ingress.enabled` 키 삭제**: 차트에서 해당 key가 제거되었습니다.
  현재 custom-values.yaml에서 `ingress.enabled: true`로 설정하고 있는 경우,
  신규 방식(`ingress.create: true` 등)으로 수정이 필요합니다.

### 배포 시 주의사항
- **Service port 변경**: `airflow-webserver` port 8080 → 8081.
  Ingress, load balancer 설정 확인 필요.

### 참고
- severity: high
- breaking: true

2.6 예상 출력 (breaking=false)

템플릿 기반 fallback 출력 (LLM 미호출).

### 변경 요약
- from_version: 1.2.3
- to_version: 1.3.0
- Chart airflow 1.2.3 → 1.3.0 업데이트
- Values: +2 추가 / -0 삭제 / ~3 변경
- Templates: +0 추가 / -0 삭제

### custom-values.yaml 수정 필요 항목
없음

### 참고
- severity: warning
- breaking: false

---

3. Docs Updater 설계

3.1 역할

생성한 업그레이드 주의사항 Markdown을 해당 차트 버전의 CUSTOM-README.md에 반영한다. (CUSTOM-README.md는 배포에 관한 내용을 포함하는 문서로, 업그레이드 주의사항의 적합한 위치다.)

3.2 처리 방식

1. diff/breaking 결과로 업그레이드 주의사항 생성 (breaking=true면 LLM, 아니면 템플릿)
2. manifests/helm/<chart>/<to_version>/CUSTOM-README.md에 반영
   - "# Upgrade History" 섹션이 없으면 파일 끝에 추가
   - 해당 버전 항목이 이미 있으면 skip (idempotent)
3. 파일 저장

3.3 파일 구조 규칙

• 각 차트 버전 디렉토리의 CUSTOM-README.md에 업그레이드 주의사항을 추가한다.
• CUSTOM-README.md는 chart_updater가 이전 버전에서 carry-over하므로 기존 배포 내용은 유지된다.
• BUILD-README.md는 차트 메타 정보(repo, 설치 명령어 등)를 유지한다.
• 별도의 docs/upgrade.md는 생성하지 않는다.

3.4 중복 방지

이미 해당 버전 업그레이드 섹션이 존재하면 덮어쓰기 또는 스킵한다 (설정으로 제어).

---

4. Git PR Bot 설계

4.1 자동화 단계

1. 새 branch 생성: update-{chart}/{to_version}
2. 카탈로그 신규 버전 디렉토리 커밋 (manifests/helm/<chart>/<to_version>/)
3. CUSTOM-README.md 업그레이드 주의사항 섹션 포함
4. git commit
5. PR 생성

4.2 PR 메타데이터

PR 제목:

update {chart}: {from_version} → {to_version}

PR labels:

• needs-review (breaking=true 시) — 담당자 확인 권장
• auto-update (breaking=false 시) — 자동 업데이트, 검토 선택적

PR description:

## Helm Chart Update: {chart} `{from_version}` → `{to_version}`

**Severity**: `high`
**Breaking**: ✅ custom-values.yaml 수정 필요 (담당자 확인 권장)

### Breaking Changes
- `[values_key_removed]` ingress.enabled — custom-values.yaml에서 사용 중인 key 삭제

### Warnings
- `[service_port_changed]` Service/airflow-webserver — port 8080 → 8081

---
*Generated by update-catalog automation*

---

5. 관련 문서

• 02-breaking-change-rules.md — Breaking Change 입력 생성
• 04-skill-interface.md — generate_upgrade_doc, create_pr Skill