# Helm Chart Upgrade 자동화 시스템

## 개요

Helm Chart 업그레이드 시 기존 버전과 신규 버전 간의 변경점을 **정형 데이터(Structured Diff JSON)**로 생성하고, LLM이 이를 해석하여 변경 요약·Breaking Change 분석·업그레이드 문서를 자동으로 생성하는 시스템이다.

> 핵심 원칙: LLM은 Diff 생성자가 아니라 **Diff 해석자(Summarizer)** 역할만 수행한다.

---

## 로드맵

| Step | 설명 | 상태 |
|------|------|------|
| **Step 1** | Skills 구현 (helm_diff · breaking_check · generate_doc · create_pr · deploy_validate) | 🔨 구현 중 |
| **Step 2** | Agent 프레임워크 POC (OpenClaw vs Nanobot — 클러스터 배포 후 결정) | 📋 계획 |
| **Step 3** | Agent 워크플로 정의 (Skills를 에이전트에 등록 + 스케줄/트리거 설정) | 💡 구상 |
| **Step 4** | 보안 정책 수립 후 운영 (RBAC · NetworkPolicy · Skill allowlist) | 💡 구상 |

> **결정**: 파이프라인 오케스트레이션 코드는 구현하지 않는다.
> Skills(핵심 로직)만 구현하고, 순서 제어는 Agent가 담당한다.
> → [결정 배경](decisions/001-agentic-first.md)

---

## 전체 아키텍처 흐름

```
[Step 1] Skills (독립 실행 가능한 개별 도구)
helm_diff → breaking_change_check → generate_upgrade_doc → update_docs_file → deploy_validate → create_pr

[Step 2~3] On-Cluster Agent (OpenClaw / Nanobot)
Agent가 위 Skills를 등록하여 워크플로로 오케스트레이션
트리거: Cron 스케줄 또는 K8s 이벤트
```

---

## 문서 구조

- [status.md](status.md) — 구현 진행 현황

### 설계 문서 (`design/`)

아키텍처 결정 사항과 컴포넌트 상세 설계를 담는다.
구현과 독립적으로 유지되며, 결정이 바뀔 때만 업데이트한다.

| 파일 | 설명 |
|------|------|
| [00-architecture-overview.md](design/00-architecture-overview.md) | 전체 아키텍처 + 설계 원칙 + 기술 스택 |
| [01-helm-diff-engine.md](design/01-helm-diff-engine.md) | Chart Version Detector · Helm Diff Engine · Values/Template/CRD Diff 설계 |
| [02-breaking-change-rules.md](design/02-breaking-change-rules.md) | Breaking Change Rule Engine 판단 로직 + 조건 정의 |
| [03-llm-summarizer.md](design/03-llm-summarizer.md) | LLM Summarizer · Prompt 설계 · BUILD-README 갱신 설계 |
| [04-skill-interface.md](design/04-skill-interface.md) | Skill 인터페이스 정의 (Agent-Skill 계약) |
| [05-on-cluster-agent.md](design/05-on-cluster-agent.md) | On-Cluster Agent 설계 (Step 2~3) + 보안 고려사항 |

### 구현 계획 (`implementation/`)

각 Step의 작업 목록과 실행 순서를 담는다.
작업이 진행되면서 자주 업데이트되며, 완료 후에는 참고용으로만 유지된다.

| 파일 | 설명 |
|------|------|
| [01-skills.md](implementation/01-skills.md) | Step 1 Skills 구현 태스크 목록 + 우선순위 + 완료 기준 |
| [02-agent.md](implementation/02-agent.md) | Step 2~4 Agent 구현 계획 (POC → 워크플로 → 보안) |

### 의사결정 기록 (`decisions/`)

중요한 아키텍처 결정 사항과 배경을 ADR(Architecture Decision Record) 형식으로 유지한다.

| 파일 | 설명 |
|------|------|
| [001-agentic-first.md](decisions/001-agentic-first.md) | 파이프라인 오케스트레이션 건너뛰고 Agent 직접 구현 결정 |

---

## 설계 원칙

1. **LLM은 Helm CLI를 직접 실행하지 않는다.**
2. **Diff 생성은 100% deterministic 해야 한다.**
3. **LLM 입력은 반드시 Structured JSON 형식이다.**
4. **Breaking Change 판단은 코드 기반 Rule Engine이 먼저 수행한다.**
5. **LLM은 설명 및 Markdown 생성만 담당한다.**
6. **각 컴포넌트는 독립적인 Skill로 노출한다.** (Agent가 호출하는 계약)
7. **운영 환경은 Git PR을 통해서만 변경한다.**

---

## 관련 문서

- [1.구조 설계(structure tool+llm summarizer).md](../1.구조%20설계(structure%20tool+llm%20summarizer).md) — 초기 설계 원본