EEDGate - LLM 워크플로우의 자기 개선 평가 루프

프로젝트 소개

EEDGate(eddgate)는 LLM 워크플로우를 위한 자기 개선 평가 루프 엔진입니다.

워크플로우를 실행하고, 실패 패턴을 분석하고, 규칙을 자동 생성하고, 다음 실행에 적용하고, 회귀 테스트로 품질을 보장하는 이 전체 루프를 하나의 도구로 닫습니다.

1
run → analyze → test → run (improved) → ...

기간: 2026.03 - 진행 중
형태: 개인 프로젝트
기술 스택: TypeScript, Node.js, Ink (React TUI), neo-blessed, Zod, Commander.js
GitHub: github.com/dj258255/eddgate

왜 만들었나?

LLM을 활용한 다단계 작업(문서 요약, 코드 리뷰, 번역 등)을 반복하다 보면 항상 같은 문제에 부딪힙니다:

1. 결과 품질이 들쭉날쭉: 같은 프롬프트인데 어떤 날은 잘 되고, 어떤 날은 엉망
2. 실패 원인을 모름: 어떤 스텝에서, 왜 실패했는지 추적이 안 됨
3. 개선이 수동: 프롬프트를 고치고 “이번엔 나아졌겠지” 하고 기도
4. 회귀를 모름: 프롬프트 하나 바꿨는데 다른 데서 품질이 떨어져도 모름

Promptfoo는 평가만 하고, Braintrust는 모니터링만 하고, LangWatch는 추적만 합니다. 실패 분석 → 규칙 생성 → 실행 개선 루프를 닫는 도구가 없었습니다.

핵심 개념: 루프

단순히 “실행 → 결과 확인”에서 끝나지 않고, 실패가 다음 실행의 개선으로 자동 연결되는 것이 핵심입니다.

검증 게이트 (Validation Gates)

각 워크플로우 스텝 사이에 자동 품질 체크포인트가 삽입됩니다. 이전 스텝의 출력이 불량이면 다음 스텝으로 진행하지 않고 즉시 중단합니다.

2단계 검증 시스템:

Tier 1은 “필수 필드가 있는가”, “형식이 맞는가” 같은 결정론적 검사입니다. Tier 2는 “답변이 원문에 근거하는가(Groundedness)”, “질문에 적합한가(Relevance)” 같은 의미적 평가입니다.

TUI (풀스크린 터미널 UI)

eddgate 명령어만 실행하면 풀스크린 TUI가 열립니다. 모든 기능이 메뉴로 접근 가능합니다.

실행 대시보드

워크플로우 실행 중에는 라이브 오케스트레이션 대시보드가 표시됩니다:

실패 분석 & 규칙 자동 생성

워크플로우를 실행한 후 결과가 좋지 않을 때, analyze 명령으로 트레이스 파일을 분석합니다.

1
eddgate analyze -d traces

1
  105 failures in 2 patterns:
2

3
  C1 Eval gate failed at "validate_final" (avg score: 0.75, 103 times)
4
     103 occurrences (98%)
5
     Score range: 0.42 - 0.85
6
     Fix: lower threshold or improve prompt specificity
7
     Rule: validate_final_adjusted_threshold.yaml
8

9
  C2 Rate limit hit at "validate_final" (2 times)
10
     Fix: add delay between steps or reduce maxRetries

--generate-rules 플래그를 추가하면 실패 패턴을 기반으로 YAML 규칙이 자동 생성되고, 다음 실행에 자동 적용됩니다.

회귀 테스트

파이프라인이 잘 동작하는 상태를 스냅샷으로 저장하고, 이후 프롬프트나 설정을 변경한 뒤 기존 품질이 유지되는지 비교합니다.

1
eddgate test snapshot -d traces     # 베이스라인 저장
2
# ... 프롬프트 수정 ...
3
eddgate run my-workflow -i input.txt --trace-jsonl traces/new.jsonl
4
eddgate test diff -d traces         # 베이스라인 대비 비교

1
  REGRESSIONS (1):
2
    validate_final.evalScore
3
      before: 0.78
4
      after:  0.65
5
      → REGRESSION

CI에서 exit code 1을 반환하므로 GitHub Actions에 바로 연결할 수 있습니다.

내장 워크플로우

추가 기능

컨텍스트 윈도우 프로파일러

어떤 스텝이 토큰(= 비용)을 가장 많이 소모하는지 분석합니다. 검증 스텝이 48번 재시도하면서 ~10만 토큰을 낭비하는 것 같은 문제를 잡아냅니다.

1
eddgate analyze -d traces --context

A/B 프롬프트 테스트

두 프롬프트 버전을 같은 입력에 대해 교차 실행하고 Welch’s t-test로 통계적 유의성을 검정합니다.

1
eddgate advanced ab-test \
2
  --workflow document-pipeline \
3
  --prompt-a templates/prompts/analyzer.md \
4
  --prompt-b templates/prompts/analyzer.v2.md \
5
  -i input.txt -n 3

자동 프롬프트 개선

실패 패턴을 기반으로 LLM이 프롬프트 수정안을 생성하고, TUI에서 원본/수정안을 나란히 비교한 뒤 승인/수정/건너뛰기를 선택합니다.

크로스런 메모리

이전 실행에서 어떤 스텝이 실패했고, 어떤 점수를 받았는지를 자동 저장합니다. 다음 실행 때 이 정보가 시스템 프롬프트에 주입되어 AI가 이전 실수를 피하게 됩니다.

API 서버

1
eddgate serve --port 3000

POST /run으로 워크플로우를 시작하고 GET /runs/:id로 결과를 폴링합니다. 외부 시스템(웹 앱, 슬랙 봇, 크론 잡)에서 트리거할 수 있습니다.

RAG 파이프라인

문서를 Pinecone MCP를 통해 인덱싱하고, 근거 기반 질의응답을 수행합니다. 환각 점수(Groundedness)로 답변 품질을 자동 검증합니다.

아키텍처

5개 핵심 모듈:

CI/CD 연동

1
name: eddgate loop
2
on:
3
  push:
4
    paths: ['templates/prompts/**', 'templates/workflows/**']
5

6
jobs:
7
  eval:
8
    runs-on: ubuntu-latest
9
    steps:
10
      - uses: actions/checkout@v4
11
      - uses: actions/setup-node@v4
12
        with: { node-version: 22 }
13
      - run: npm ci && npm run build
14
      - run: node dist/cli/index.js doctor --ci -w templates/workflows
15
      - run: node dist/cli/index.js test diff -d traces
16
      - run: node dist/cli/index.js advanced gate --results eval-results.json --rules templates/gate-rules.yaml

test diff는 회귀 시 exit code 1, gate는 임계값 미달 시 exit code 1을 반환하여 CI가 머지를 차단합니다.

설치 및 시작

1
npm install -g eddgate
2
eddgate              # TUI 실행

요구사항: Node.js 20+, Claude CLI (아무 구독) 또는 ANTHROPIC_API_KEY

1
# CLI 모드
2
eddgate init                          # 프로젝트 스캐폴딩
3
eddgate doctor                        # 환경 점검
4
eddgate run document-pipeline -i input.txt   # 워크플로우 실행
5
eddgate analyze -d traces             # 실패 패턴 분석
6
eddgate test snapshot -d traces       # 베이스라인 저장
7
eddgate test diff -d traces           # 회귀 검출

워크플로우 정의 예시

1
name: "My Pipeline"
2
config:
3
  defaultModel: "sonnet"
4
  topology: "pipeline"
5
  onValidationFail: "block"
6

7
steps:
8
  - id: "analyze"
9
    type: "classify"
10
    context:
11
      identity:
12
        role: "analyzer"
13
        constraints: ["output JSON"]
14
      tools: []
15
    validation:
16
      rules:
17
        - type: "required_fields"
18
          spec: { fields: ["topics"] }
19
          message: "topics required"
20

21
  - id: "generate"
22
    type: "generate"
23
    dependsOn: ["analyze"]
24
    evaluation:
25
      enabled: true
26
      type: "groundedness"
27
      threshold: 0.7
28
      onFail: "block"

YAML 워크플로우 파일 하나로 스텝, 의존성, 검증 규칙, 평가 기준을 선언적으로 정의합니다.

테스트

Vitest 기반 219개 테스트로 핵심 모듈을 검증합니다:

• workflow-engine: 토폴로지 정렬, 순환 감지, 병렬 실행, 비용 예산
• tier1-rules: Zod 스키마 검증 규칙
• normalize-score: 0-1 / 0-100 점수 정규화
• trace-emitter: 이벤트 버퍼링, 비동기 에러 처리
• context-builder: 실행 컨텍스트 조합
• rag-pipeline: 청킹, 다양성 리랭킹

Mock LLM 어댑터를 사용하여 결정론적 테스트를 보장합니다.