zioinfo-mail/.claude/skills/guardia-advanced-orchestrator/SKILL.md

---
name: guardia-advanced-orchestrator
description: >
  GUARDiA ITSM 고급 확장 오케스트레이터. 현재 667개 엔드포인트에서 다음 5개 영역으로 추가 확장한다:
  (1) CMDB 자동 발견 — SSH/SNMP/WMI 에이전트리스 인벤토리·의존성 자동 수집,
  (2) Text-to-SQL + 대화형 운영 어시스턴트 — 자연어로 ITSM 데이터 조회,
  (3) 구성 드리프트 감지 — 골든 구성 vs 실제 환경 비교·자동 교정,
  (4) 멀티클라우드 통합 — AWS/GCP/Azure/NCloud 단일 관제·비용 최적화,
  (5) 공공기관 특화 — 나라장터·공공API허브·ISP지원·행정망분리·K-Cloud.
  guardia-itsm 기존 패턴(FastAPI+SQLAlchemy+paramiko) 준수. 외부 API 완전 금지(공공API 제외).
  다음 상황에서 반드시 사용:
  (1) 'CMDB 자동 발견', '인벤토리 자동화', '서버 자동 등록', '의존성 맵';
  (2) '자연어 쿼리', 'Text-to-SQL', '운영 어시스턴트', '질문으로 조회';
  (3) '구성 드리프트', '설정 변경 감지', '골든 구성', '자동 교정';
  (4) '멀티클라우드', 'AWS 연동', '클라우드 비용 최적화', '클라우드 전환';
  (5) '나라장터', '공공 API', 'ISP 수립', '행정망', 'K-Cloud', '공공기관 특화';
  (6) 다시 실행, 업데이트, 수정, 보완.
---

# GUARDiA 고급 확장 오케스트레이터

**실행 모드:** 하이브리드
- Phase 1 (분석): 서브 에이전트 (itsm-dev — 기존 라우터 중복 분석)
- Phase 2~3 (구현): **에이전트 팀** (5명 병렬)
- Phase 4 (QA): 서브 에이전트 (cross-system-qa)

---

## 배경 및 근거

| 영역 | 현재 상태 | 확장 가치 |
|------|----------|---------|
| CMDB | 수동 등록만 | 자동 발견으로 커버리지 100% |
| 쿼리 | API/UI만 | 자연어로 운영자 직관적 접근 |
| 구성 관리 | 변경 감지 없음 | 드리프트 즉시 탐지·교정 |
| 클라우드 | NCloud만 | 공공기관 멀티클라우드 전략 대응 |
| 공공기관 | 기본 CSAP만 | 국내 공공 ITSM 시장 차별화 |

---

## Phase 0: 컨텍스트 확인

```
_workspace/ 존재:
- 없음 → 초기 구현 (Phase 1부터)
- 있음 + 특정 영역 요청 → 해당 에이전트만 재실행
- 있음 + 전체 → _workspace_prev/ 이동 후 재실행
```

---

## Phase 1: 충돌 분석 (서브 에이전트)

**itsm-dev** 서브 에이전트로 기존 라우터 중복 확인:

```
확인 항목:
1. autodiscovery → cmdb.py(17개 엔드포인트)와 겹치는 부분
2. nlquery → nlcmd.py, chatbot.py와 겹치는 부분
3. drift_detection → compliance.py, network_devices.py와 겹치는 부분
4. multicloud → ncloud.py와 겹치는 부분
5. narasajang → gateway.py, external_api.py와 겹치는 부분
```

산출물: `_workspace/phase1_conflict_analysis.md`

---

## Phase 2: 5개 영역 병렬 구현 (에이전트 팀)

**팀 구성:**
- 리더: orchestrator
- 팀원: cmdb-autodiscovery-dev, nlquery-dev, config-drift-dev, multicloud-dev, public-sector-dev

### 작업 할당

| 에이전트 | 라우터 | 산출물 |
|---------|--------|--------|
| cmdb-autodiscovery-dev | autodiscovery.py, snmp_discovery.py, dependency_map.py, config_inventory.py | `_workspace/autodiscovery_spec.md` |
| nlquery-dev | nlquery.py, op_assistant.py, query_history.py | `_workspace/nlquery_spec.md` |
| config-drift-dev | drift_detection.py, golden_config.py, auto_remediation.py | `_workspace/drift_spec.md` |
| multicloud-dev | multicloud.py, aws_connector.py, cost_optimizer.py, cloud_migration.py | `_workspace/multicloud_spec.md` |
| public-sector-dev | narasajang.py, public_api_hub.py, isp_support.py, network_zone.py, k_cloud.py, e_procurement.py | `_workspace/publicsector_spec.md` |

**팀원 간 인터페이스 조율 (SendMessage):**
- cmdb-autodiscovery-dev → config-drift-dev: 발견 데이터 스키마
- config-drift-dev → public-sector-dev: CSAP 체크 항목 목록
- multicloud-dev → public-sector-dev: K-Cloud API 인터페이스
- nlquery-dev → 전체: DB 스키마 컨텍스트 문서

---

## Phase 3: DB 모델 + main.py 등록

```python
# workspace/guardia-itsm/models.py 신규 모델 추가
from models import (
    CMDBAutoDiscovery, ServiceDependency,    # 자동 발견
    QueryHistory, ConversationSession,       # NL 쿼리
    GoldenConfig, DriftResult, AutoRemediation, # 드리프트
    MultiCloudConfig, CloudCostRecord,       # 멀티클라우드
    ProcurementRecord, NetworkZone,          # 공공기관
)

# workspace/guardia-itsm/main.py 라우터 등록
from routers import (
    autodiscovery, snmp_discovery, dependency_map, config_inventory,  # CMDB
    nlquery, op_assistant, query_history,                              # NL
    drift_detection, golden_config, auto_remediation,                  # 드리프트
    multicloud, aws_connector, cost_optimizer, cloud_migration,        # 클라우드
    narasajang, public_api_hub, isp_support, network_zone, k_cloud,   # 공공
)
```

---

## Phase 4: QA

```
검증 항목:
1. 신규 라우터 임포트 오류 없음
2. 에이전트리스 원칙 — 대상 서버 소프트웨어 설치 없음
3. Text-to-SQL — SELECT만 허용, DML 차단
4. 드리프트 자동 교정 — 승인 게이트 누락 없음
5. 공공 API — API Key 암호화 저장 확인
6. 민감 데이터(ip_addr, ssh_user) API 응답 미노출
```

---

## 데이터 흐름

```
_workspace/
├── phase1_conflict_analysis.md   ← Phase 1 충돌 분석
├── autodiscovery_spec.md         ← CMDB 자동 발견 API 스펙
├── nlquery_spec.md               ← NL 쿼리 엔진 스펙
├── drift_spec.md                 ← 드리프트 감지 스펙
├── multicloud_spec.md            ← 멀티클라우드 스펙
└── publicsector_spec.md          ← 공공기관 특화 스펙
```

---

## 확장 로드맵

상세 로드맵: `references/advanced-roadmap.md`

---

## 에러 핸들링

| 에러 | 처리 |
|------|------|
| SNMP 응답 없음 | 타임아웃 5초, 재시도 2회 후 SKIP |
| Text-to-SQL DML 감지 | 즉시 거부, 감사 로그 기록 |
| 드리프트 자동 교정 실패 | 롤백 실행, SR 생성 |
| AWS API 인증 실패 | 설정 페이지로 안내 |
| 나라장터 API 장애 | 캐시 데이터 반환, 알림 발송 |

---

## 테스트 시나리오

**정상 흐름 (CMDB 자동 발견):**
1. "CMDB 자동 발견 기능 추가해줘"
2. Phase 1: cmdb.py와 충돌 없음 확인
3. Phase 2: autodiscovery.py, snmp_discovery.py 구현
4. Phase 3: DB 모델 + main.py 등록
5. Phase 4: QA — 에이전트리스 원칙 확인
6. "✅ CMDB 자동 발견 API 추가 완료"

**정상 흐름 (Text-to-SQL):**
1. "이번 달 HIGH 우선순위 미처리 SR 목록 자연어로 조회 가능하게"
2. nlquery.py 구현 (SELECT만 허용 검증)
3. Ollama SQL 생성 → 실행 → 결과 반환

---

## should-trigger

- "CMDB 자동 발견", "서버 자동 등록", "인벤토리 자동화"
- "자연어 쿼리", "운영 어시스턴트", "Text-to-SQL"
- "구성 드리프트", "설정 변경 감지", "골든 구성"
- "멀티클라우드", "AWS 연동", "클라우드 비용 최적화"
- "나라장터", "공공 API", "ISP 수립", "K-Cloud"
- "다시 실행", "수정", "보완"

## should-NOT-trigger

- "Kubernetes 관리" → kubernetes.py (이미 구현)
- "Jira 동기화" → jira_sync.py (이미 구현)
- "KPI 대시보드" → kpi_engine.py (이미 구현)
- "SR 처리" → guardia-orchestrator