Move directory

2026-03-06 17:08:31 +09:00
parent 4d99258344
commit 21addb6e88
73 changed files with 0 additions and 0 deletions
@@ -0,0 +1,99 @@
+# ADR 001: 파이프라인 오케스트레이션 건너뛰고 Agent 직접 구현
+
+**상태**: 채택 (2026-03-03)
+
+---
+
+## 배경
+
+초기 설계는 다음 3단계 로드맵이었다:
+
+```
+Phase 1: 정적 분석 파이프라인
+         (MCP Tools + Python 오케스트레이션 코드)
+         ↓
+Phase 2A: GitHub Actions로 배포 검증 추가
+         ↓
+Phase 2B: On-Cluster AI Agent (OpenClaw/Nanobot)
+```
+
+이 구조에서 Phase 1은 두 가지를 포함하고 있었다:
+1. **MCP Tools** — `helm_diff`, `breaking_check` 등 핵심 로직
+2. **파이프라인 오케스트레이션 코드** — Tools를 순서대로 호출하는 Python 코드
+
+---
+
+## 결정
+
+**파이프라인 오케스트레이션 코드는 구현하지 않는다.**
+
+MCP Tools(핵심 로직)만 구현하고, 순서 제어는 처음부터 Agent(OpenClaw/Nanobot)가 담당하도록 한다.
+
+수정된 로드맵:
+
+```
+Step 1: MCP Tools 구현 (오케스트레이션 없이)
+        ↓
+Step 2: Agent 프레임워크 POC (OpenClaw vs Nanobot)
+        ↓
+Step 3: Agent 워크플로에 MCP Tools를 Skills로 연결
+        ↓
+Step 4: 보안 정책 수립 후 운영
+```
+
+---
+
+## 이유
+
+### 낭비가 되는 코드
+
+파이프라인 오케스트레이션 코드는 Phase 2B에서 Agent 워크플로 정의로 대체된다.
+
+```python
+# 이 코드는 Phase 2B에서 쓸모없어진다
+diff = helm_diff(...)
+breaking = breaking_check(diff)
+doc = generate_doc(diff, breaking)
+pr = create_pr(doc)
+```
+
+처음부터 Agent를 목표로 한다면 이 코드를 작성하고 나중에 버리는 것은 낭비다.
+
+### MCP Tools는 낭비가 아니다
+
+반면 MCP Tools 자체(helm_diff, breaking_check 등의 구현 로직)는 Agent에서도 그대로 사용된다.
+버려지는 코드가 없다.
+
+### K8s 클러스터 보유
+
+Staging K8s 클러스터가 이미 있으므로 On-Cluster Agent를 바로 구성할 수 있다.
+"클러스터 없이 로컬 파이프라인으로 먼저 검증"이라는 이유가 성립하지 않는다.
+
+### 테스트 용이성
+
+개별 MCP Tool은 파이프라인 없이도 독립적으로 단위 테스트 가능하다.
+
+---
+
+## 결과
+
+- 구현 시간 단축: 파이프라인 오케스트레이션 코드 작성 + 나중에 Agent로 재작성하는 이중 작업 제거
+- Agent 프레임워크 선택이 중요해짐: Step 2 POC로 검증 후 결정 필요
+- 중간 산출물 없음: 파이프라인이 없으므로 MCP Tools 완성 전까지는 E2E 동작 확인 불가
+  → POC 단계에서 단일 Tool 호출부터 점진적으로 검증
+
+---
+
+## 대안으로 고려했던 것
+
+### 파이프라인 먼저 구현 후 Agent로 전환
+
+- 장점: 중간 단계에서 E2E 동작 확인 가능, 디버깅 용이
+- 단점: 파이프라인 오케스트레이션 코드가 버려짐 (낭비), 구현 기간 길어짐
+- **기각 이유**: K8s 클러스터가 이미 있어 이 중간 단계가 불필요
+
+### GitHub Actions Phase 2A 추가
+
+- 장점: 배포 검증을 클러스터 없이 CI에서 먼저 구현 가능
+- 단점: Agent에서 동일 기능을 다시 구현해야 함 (이중 작업)
+- **기각 이유**: `deploy_validate` MCP Tool로 직접 구현, Agent가 조건부 호출
@@ -0,0 +1,50 @@
+# ADR 002: dip-catalog 디렉토리 기반 Helm Chart 구조를 기준으로 설계
+
+**상태**: 채택 (2026-03-03)
+
+---
+
+## 배경
+
+대상 카탈로그는 GitHub 레포 내 `manifests/helm/<chart>/<version>/` 구조로 관리된다.
+각 버전 디렉토리는 완전한 Helm chart 구조를 포함하며, 추가 문서와 기본 배포 values가 존재한다.
+
+- `README.md`, `BUILD-README.md`, `CUSTOM-README.md` (버전 디렉토리 내)
+- `custom-values.yaml` (배포 시 기본 values)
+
+이 구조는 일반 Helm repo/index 기반 감지 방식과 다르므로, 감지/입력/문서 생성 방식을 조정해야 한다.
+
+---
+
+## 결정
+
+1. **버전 감지는 디렉토리 기반**으로 수행한다.
+   - `manifests/helm/<chart>/` 하위 버전 디렉토리 변화 또는 git diff로 신규 버전 감지
+2. **helm_diff 입력에 `chart_path`를 추가**하고 dip-catalog에서는 이를 우선 사용한다.
+3. **`custom-values.yaml`을 기본 values_override로 적용**한다.
+4. **README/BUILD/CUSTOM 문서를 요약하여 LLM 입력 컨텍스트(`docs_context`)로 제공**한다.
+   - 단, 컨텍스트는 “참고용”으로만 사용하고 diff에 없는 변경을 생성하지 않는다.
+
+---
+
+## 이유
+
+- 레포 구조가 Helm repo/index.yaml 방식이 아니므로 기존 감지 방법이 부정확하다.
+- 동일 chart라도 버전 디렉토리마다 커스텀 문서 및 기본 values가 존재해,
+  업그레이드 문서 생성에 중요한 맥락이 된다.
+
+---
+
+## 결과
+
+- MCP Tool 인터페이스 및 설계 문서에 `chart_path`, `docs_context` 반영
+- LLM Summarizer는 문서 컨텍스트를 참고하되, Structured Diff JSON을 우선한다
+
+---
+
+## 대안으로 고려했던 것
+
+### Helm repo/index 기반 감지 유지
+- 장점: 기존 설계 재사용 가능
+- 단점: dip-catalog 구조에는 적용 불가
+- **기각 이유**: 실제 운영 구조와 불일치