모듈 4: Skills - hmeg-api RAG 시스템

학습 목표

Skill의 개념과 Commands/Subagents와의 차이를 이해한다
hmeg-api Skill의 RAG 구조를 설명할 수 있다
Google Gemini File Search 기반 벡터 스토어를 설정할 수 있다
할루시네이션 방지 메커니즘을 이해한다

Skill이란?

외부 도구(API, 스크립트, 서비스)를 Claude에서 호출할 수 있도록 래핑한 모듈입니다.

.claude/skills/
├── hmeg-api/          # HmEG API 문서 RAG 검색
│   ├── SKILL.md       # Skill 정의 (트리거/사용법)
│   ├── README.md      # 설정 및 사용 방법
│   ├── requirements.txt
│   └── scripts/
│       ├── setup_store.py   # 벡터 스토어 초기화/문서 업로드
│       └── search.py        # 문서 검색
├── custom/            # 사용자 정의 Skill 폴더
└── templates/         # Skill 템플릿

Commands vs Subagents vs Skills 비교

구분	파일 위치	역할
Commands	`.claude/commands/`	AI에 전달할 프롬프트 저장
Subagents	`.claude/agents/`	전문 AI 서브프로세스
Skills	`.claude/skills/`	외부 API/스크립트 연동

Skills의 특징: 파이썬 스크립트, 외부 API 등 Claude 외부의 실제 도구를 실행합니다.

왜 hmeg-api Skill이 필요한가?

문제: HmEG API 할루시네이션

HmEG는 사내 전용 3D 엔진입니다. Claude가 학습한 데이터에 없습니다.

Claude (Skill 없이):
"EGViewport에 박스를 추가하려면 다음처럼 하세요:
 viewport.AddMesh(new BoxMesh(1,1,1));"

실제 HmEG API:
 viewport.RootSpace.AddBox(width, height, depth)

이런 할루시네이션이 발생하면:

컴파일 오류
디버깅 시간 낭비
AI에 대한 불신

해결: RAG (Retrieval-Augmented Generation)

[사용자 질문] "EGViewport에 박스 추가 방법"
         |
         v
[검색] Google Gemini 벡터 스토어에서 관련 문서 섹션 검색
         |
         v
[검색 결과] "HmEG.md, Section 42: EGSpace.AddBox(double,double,double)"
         |
         v
[생성] 검색된 실제 API 기반으로 C# 코드 생성
         |
         v
[출력] 정확한 API 시그니처 + Citation(출처 명시)

hmeg-api Skill 아키텍처

HmEG.md (공식 API 문서, 5MB+)
         |
         v
[setup_store.py: 초기 설정]
  - 8,000자 단위로 청크 분할
  - Google Gemini Corpus에 업로드
  - 벡터 인덱스 생성
         |
         v
Google Gemini Corpus (벡터 스토어)
  - 수백 개의 문서 청크
  - 각 청크: 텍스트 + 임베딩 벡터
         |
         v
[search.py: 검색]
  - 쿼리를 벡터로 변환
  - 코사인 유사도로 상위 N개 섹션 검색
  - Gemini 2.0 Flash로 C# 코드 생성

설정 방법 (단계별)

Step 1: Google API Key 발급 및 설정

# Google AI Studio에서 API Key 발급
# https://aistudio.google.com/apikey
 
# Windows 환경변수 설정
set GOOGLE_API_KEY=AIzaSy...your-key-here
 
# 또는 .env 파일에 저장 (gitignore에 포함)
# .env
GOOGLE_API_KEY=AIzaSy...your-key-here

Step 2: Python 의존성 설치

pip install -r .claude/skills/hmeg-api/requirements.txt

requirements.txt 내용:

google-generativeai>=0.8.0

Step 3: 벡터 스토어(Corpus) 생성

cd .claude/skills/hmeg-api/scripts
 
python setup_store.py init

출력:

새 Corpus 생성 중: HmEG API Documentation
OK Corpus 생성 완료: corpora/corpus-abc123def456
ID가 .corpus_id에 저장되었습니다.

Step 4: HmEG 문서 업로드

HmEG.md가 5MB 이상이므로 분할이 필요합니다:

# 문서 분할 (PowerShell)
$content = Get-Content data\HmEG.md
$chunkSize = 25000  # 라인 단위
for ($i = 0; $i -lt $content.Count; $i += $chunkSize) {
    $part = $content[$i..([Math]::Min($i+$chunkSize-1, $content.Count-1))]
    $partNum = [Math]::Floor($i/$chunkSize) + 1
    $part | Set-Content "data\HmEG_part$partNum.md"
}

# 분할된 파일들 업로드
python setup_store.py upload --path ../../../../data/HmEG_part1.md
python setup_store.py upload --path ../../../../data/HmEG_part2.md
# ... 계속

Step 5: 검색 테스트

python search.py -q "EGViewport RootSpace"

출력 예시:

검색 쿼리: EGViewport RootSpace
5개의 관련 섹션을 찾았습니다.

1. API 설명: HmEG.EGViewport.RootSpace
   - EGSpace 타입의 루트 공간 속성
   - 3D 객체를 추가하는 진입점

2. C# 코드 예제:
   var rootSpace = viewport.RootSpace;
   var box = rootSpace.AddBox(1.0, 2.0, 3.0);
   viewport.ZoomExtents();

3. 출처: HmEG.md, Section 15

Claude에서 Skill 사용하기

SKILL.md 트리거 조건

---
name: hmeg-api-lookup
description: HmEG 라이브러리 문서를 Google File Search로 검색하여
             정확한 API 정보와 C# 코드를 생성합니다.
             HmEG 클래스/메서드 사용법, API 정보가 필요할 때 사용합니다.
---

호출 방법 1: 직접 호출

/hmeg-api

이후 검색하고 싶은 내용 입력

호출 방법 2: 자연어로 언급

사용자: "HmEG에서 Animation 클래스 사용법 알려줘"

Claude: (SKILL.md의 description 매칭)
        "hmeg-api Skill을 사용하여 검색합니다..."
        $ python search.py -q "Animation class usage"
        [검색 결과 기반으로 정확한 코드 생성]

호출 방법 3: execute-prp 중 자동 호출

/execute-prp PRPs/animation_prp.md

execute-prp 내부에서:
- [API 조회 필요: Animation Constructor] 마커 발견
- hmeg-api Skill 자동 호출
- 실제 API 정보 획득 후 코드 작성

RAG가 방지하는 할루시네이션 유형

유형 1: 존재하지 않는 클래스

// 할루시네이션
var mesh = new HmEGMesh();
 
// RAG 기반 (실제 API)
var shape = viewport.RootSpace.AddBox(1.0, 1.0, 1.0);

유형 2: 잘못된 메서드 시그니처

// 할루시네이션 (파라미터 순서 오류)
viewport.ImportModel(callback, path);
 
// RAG 기반 (실제 시그니처)
viewport.RootSpace.ImportModelByFile(path, callback, isUP_Y: true);

유형 3: 잘못된 네임스페이스

// 할루시네이션
using HmEG.Graphics;
 
// RAG 기반 (실제 네임스페이스)
using HmEG;
using HmEG.Animations;

Citation 시스템

검색 결과에는 반드시 출처(Citation)가 포함됩니다:

API 설명: EGViewport.RootSpace
출처: HmEG.md, Section 15 (API Reference - EGViewport Properties)

이 정보는 HmEG 공식 문서에서 검색되었습니다.

Citation의 역할:

개발자가 원본 문서를 직접 확인 가능
생성된 코드의 신뢰도 검증
AI가 “모르면 모른다고 말하게” 유도

Skill 확장: 새 문서 추가

다른 사내 라이브러리 문서도 추가할 수 있습니다:

# HmGeometry 문서 추가
python setup_store.py upload --path data/HmGeometry.md
 
# 기존 Corpus에 누적됨 (재생성 불필요)

# 검색 시 자동으로 모든 문서에서 검색
python search.py -q "Geometry intersection methods"

토큰 최적화 설계

hmeg-api Skill은 토큰 비용을 최소화하도록 설계되었습니다:

[전체 HmEG.md: 5MB+]
         |
         v (벡터 검색)
[관련 섹션 5개만 추출: ~5KB]
         |
         v (Gemini에 전달)
[응답 생성: 필요한 API 정보만]

전체 문서를 컨텍스트에 넣으면:

토큰 비용 수백 배 증가
응답 속도 저하
무관한 정보로 인한 정확도 저하

핵심 정리

hmeg-api Skill = 사내 API 문서를 AI가 실시간 검색하는 RAG 시스템
Google Gemini 벡터 스토어에 문서를 업로드하여 의미론적 검색
할루시네이션 방지: 학습 데이터가 아닌 실제 문서 기반 코드 생성
Citation: 출처 명시로 신뢰성 보장
execute-prp와 연동하여 구현 시 자동으로 정확한 API 사용
비용 최적화: 필요한 섹션만 추출하여 토큰 사용량 최소화

Ai 마법서

Explorer

04_skills