SKILL.md vs Workflow vs Harness vs AI Pipeline

대상 독자: AI 시스템 아키텍처 및 LLM 활용에 관심 있는 개발자/엔지니어
분석 범위: Claude를 중심으로, 범용 LLM 생태계 전반
최종 업데이트: 2026년 5월 4일

이 문서는 AI 생태계의 빠른 변화에 따라 내용이 달라질 수 있습니다.

이번 문서에서는 claude 기반의 SKILL.md, workflow, harness, AI pipeline 대해서 다루겠습니다.
여러 용어가 범람하는 가운데, 스스로도 혼동되는 개념이 많아 정리해 보았습니다.

---

목차

1. 개요 및 핵심 구분
2. SKILL.md
3. Workflow
4. Harness
5. AI Pipeline
6. 4가지 개념 비교 매트릭스
7. Claude 전용인가? 범용인가?
8. Under the Hood: 내부 작동 원리
9. 실전 조합 패턴

---

1. 개요 및 핵심 구분

이 네 가지 개념은 서로 다른 추상화 계층 abstraction layer에 위치합니다.
혼동되는 이유는 모두 "AI가 더 잘 작동하게 하는 것"처럼 보이기 때문입니다.

┌───────────────────────────────────────────────────────────┐
│                      AI Pipeline                          │  ← 최상위 오케스트레이션
│  ┌────────────────────────────────────────────────────┐   │
│  │                   Harness                          │   │  ← 실행 환경 + 제어 레이어
│  │  ┌──────────────────────────────────────────────┐  │   │
│  │  │              Workflow                        │  │   │  ← 단계별 로직 흐름
│  │  │  ┌────────────────────────────────────────┐  │  │   │
│  │  │  │            SKILL.md                    │  │  │   │  ← 모델 행동 명세
│  │  │  └────────────────────────────────────────┘  │  │   │
│  │  └──────────────────────────────────────────────┘  │   │
│  └────────────────────────────────────────────────────┘   │
└───────────────────────────────────────────────────────────┘

각 개념의 스코프를 위 도표처럼 표현하면 이해가 쉽습니다.

요약:

개념	한 줄 정의
SKILL.md	모델이 특정 작업을 어떻게 수행해야 하는지 기술한 지식 문서
Workflow	작업 단계들의 순서와 조건 분기를 정의한 논리 흐름
Harness	AI 모델을 실행·테스트·제어하기 위한 실행 프레임워크
AI Pipeline	여러 AI/비AI 컴포넌트를 연결해 엔드-투-엔드 결과를 생산하는 아키텍처

---

2. SKILL.md

LLM 훈련 데이터에 없는 모델별, 라이브러리별 고유한 특징이나 사용법, 환경에 따른 제약사항 등을 모델이 참고할 수 있도록 구조화된 지식 문서로 전달

2.1 개념 정의

SKILL.md는 Claude의 컨텍스트 윈도우에 주입되는 구조화된 지식 문서입니다.
일종의 "작업 매뉴얼"로, 모델이 특정 도메인(예: DOCX 생성, PDF 조작, 프론트엔드 디자인)에서
올바른 판단을 내릴 수 있도록 환경별 제약, 검증된 패턴, 실패 사례를 담습니다.
개인적으로는 "단위의 컨텍스트"로 이해하고 있습니다.

2.2 구조 특성

---
name: skill-name
description: "트리거 조건 설명 (언제 이 스킬을 사용할지)"
license: ...
---

# 개요
## Quick Reference (테이블 형태)
## 상세 구현 패턴 (코드 예시)
## Critical Rules (실패 사례 / 금지 패턴)
## Dependencies

일반적인 마크다운 문서 형태로 정의되며, 마크다운 메타데이터 frontmatter에 skill과 관련된 이름, 설명 등을 정의합니다.

SKILL을 작성할 때의 유의해야 할 원칙은 다음과 같습니다:

• 컨텍스트 효율성: 모델이 시행착오 없이 바로 올바른 코드를 생성하도록 압축된 지식 제공
• 트리거 기반 로딩: 모든 작업에 로드하지 않고, 관련 작업에만 선택적으로 로드
• 실패 패턴 우선: "하지 말아야 할 것"을 명시적으로 포함 (예: // ❌ WRONG, CRITICAL:)
• 환경 특수성: 추상적 개념이 아닌 특정 라이브러리·버전·환경에서 검증된 패턴

2.3 SKILL.md가 해결하는 문제

문제 중심으로 SKILL.md의 역할을 정리하면 다음과 같습니다:

문제	SKILL.md 없을 때	SKILL.md 있을 때
라이브러리 quirk	모델이 훈련 데이터 기반 추측	검증된 패턴 직접 제공
환경 제약	반복 오류 후 수정	사전에 제약 조건 인지
출력 품질	일반적인 코드 생성	프로덕션 수준 출력
일관성	실행마다 다른 결과	재현 가능한 결과

2.4 예시: docx SKILL.md의 critical rule

// ❌ NEVER use unicode bullets
new Paragraph({ children: [new TextRun("• Item")] })

// ✅ CORRECT - use numbering config with LevelFormat.BULLET
const doc = new Document({
  numbering: { config: [{ reference: "bullets", levels: [...] }] }
})

이런 규칙은 docx-js 라이브러리의 실제 버그/quirk에서 도출된 것으로, 일반 LLM 훈련 데이터에는 포함되지 않은 정보입니다.

---

3. Workflow

SKILL이 "모델이 뭘 알아야 하는지"라면, workflow는 "모델이 뭘 해야 하는지"를 정의하는 일련의 절차입니다.

3.1 개념 정의

Workflow는 작업을 완료하기 위한 단계(step)들의 순서, 조건 분기, 반복 로직을 명시한 실행 논리입니다.
"무엇을 해야 하는가"보다 어떤 순서로, 어떤 조건에서 무엇을 해야 하는가를 다룹니다.

3.2 AI 컨텍스트에서의 Workflow 유형

자료를 조사해보니, workflow를 구성하는 유형이 여러가지가 있었습니다.

1. 프롬프트 체이닝으로 구성되는 프롬프트 기반의 Workflow
2. 에이전트가 스스로 작업을 수행하는 에이전트 기반의 Workflow
3. 멀티모달 AI가 나오면서 등장한 멀티모달 워크플로우

3가지로 크게 나눌 수 있습니다.

Type A - 프롬프트 체이닝 Workflow

[사용자 입력]
    ↓
[단계 1: 의도 분류 프롬프트]
    ↓
[조건 분기]
    ├─ 코드 관련 → [단계 2a: 코드 생성 프롬프트]
    └─ 문서 관련 → [단계 2b: 문서 생성 프롬프트]
         ↓
[단계 3: 검증 및 후처리]
    ↓
[최종 출력]

Type B - 에이전틱 Workflow (Claude에서의 구현)

타입 B, 에이전트 워크플로우는 Claude 내부 구현을 참조합니다.

# Claude의 내부 workflow 예시 (개념적 표현)
while task_incomplete:
    observation = observe_environment()
    action = model.decide(observation, memory)
    result = execute(action)
    memory.update(result)
    if validate(result): break

Type C - 멀티모달 Workflow

멀티모달: 텍스트 뿐만 아니라 이미지 등 다양한 입력형태를 처리할 수 있는 모델을 의미합니다.
Vision 모델, 오디오 모델 등이 예시입니다.

[이미지 입력]
    ↓
[Vision 모델: 내용 추출]
    ↓
[텍스트 모델: 분석/변환]
    ↓
[생성 모델: 출력 제작]

3.3 Workflow를 구성하는 요소

요소	설명	예시
Steps	개별 실행 단위	"PDF 읽기", "요약 생성"
Transitions	단계 간 이동 조건	성공 시 다음 단계, 실패 시 재시도
Branching	조건 분기	파일 타입에 따라 다른 파서 선택
Loops	반복 실행	품질 기준 충족까지 재생성
State	단계 간 공유 정보	이전 단계 결과, 사용자 컨텍스트
Error Handling	실패 복구 로직	재시도, 폴백, 중단

3.4 Workflow vs SKILL.md 관계

SKILL.md와 Workflow는 종종 함께 언급되지만, 역할이 다릅니다.

SKILL.md: "DOCX를 만들 때 테이블 너비는 DXA 단위로 설정해야 한다"
  → 이것은 '지식'

Workflow: "1) SKILL.md 읽기 → 2) 구조 설계 → 3) 코드 생성 → 4) 검증 → 5) 파일 출력"
  → 이것은 '실행 흐름'

SKILL.md는 Workflow의 한 단계(step) 안에서 참조되는 자료입니다.

---

4. Harness

Harness는 "단일 호출"을 위한 도구라기보다는, Workflow와 함께 또는 Workflow 외부에서 실행을 안정화하고 감싸는 인프라와 유사

지난 2~3개월 간 많이 화자되었던 하네스 Harness를 파악해보겠습니다.

4.1 개념 정의

Harness는 원래 소프트웨어 테스팅 용어로, AI 컨텍스트에서는 모델의 입출력을 제어하고, 실행을 감싸고(wrap), 테스트/평가/모니터링을 가능하게 하는 프레임워크를 의미한다-고 합니다. 즉 모델 자체가 아니라 모델 주변을 감싸는 실행 환경으로 이해했습니다.

4.2 Harness의 구성 요소

┌─────────────────────────────────────────────────────┐
│                    HARNESS                          │
│                                                     │
│  ┌─────────────┐    ┌──────────────┐                │
│  │  Input      │    │  Output      │                │
│  │  Validator  │    │  Parser      │                │
│  └──────┬──────┘    └──────┬───────┘                │
│         │                  │                        │
│  ┌──────▼──────────────────▼───────┐                │
│  │          MODEL CALL             │                │
│  │  (Claude / GPT / Gemini / etc.) │                │
│  └─────────────────────────────────┘                │
│                                                     │
│  ┌─────────────┐    ┌──────────────┐                │
│  │  Logging &  │    │  Retry &     │                │
│  │  Tracing    │    │  Fallback    │                │
│  └─────────────┘    └──────────────┘                │
│                                                     │
│  ┌──────────────────────────────────┐               │
│  │  Evaluation / Scoring Layer      │               │
│  └──────────────────────────────────┘               │
└─────────────────────────────────────────────────────┘

개인적으로는 하네스 구조를 유지하면서 모델을 교체하는 것이 가능해보여 흥미롭습니다.

4.3 실제 Harness 구현 예시

워크플로우와 마찬가지로 Harness도 구현 언어와 모델에 따라 다양한 예시가 있습니다.

다음은 몇 가지 예시입니다:

Claude 기반 Harness (JavaScript)

class ClaudeHarness {
  constructor(config) {
    this.model = config.model;
    this.maxRetries = config.maxRetries || 3;
    this.validators = config.validators || [];
    this.evaluators = config.evaluators || [];
  }

  async run(prompt, context = {}) {
    // 1. 입력 전처리
    const sanitized = this.sanitizeInput(prompt);

    // 2. 모델 호출 (재시도 포함)
    let response = null;
    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
      try {
        response = await this.callModel(sanitized, context);

        // 3. 출력 검증
        const valid = await this.validate(response);
        if (valid) break;
      } catch (err) {
        this.log('error', err, attempt);
        if (attempt === this.maxRetries - 1) throw err;
      }
    }

    // 4. 평가 및 스코어링
    const scores = await this.evaluate(response);

    // 5. 로깅
    this.log('success', { prompt, response, scores });

    return { response, scores };
  }
}

위에서 살핀 하네스 구조를 자바스크립트로 표현한 예시입니다. 전처리에는 sanitize, 모델 호출에는 callModel, 출력 검증에는 validate, 평가에는 evaluate, 로깅에는 log 메서드를 사용하고 있습니다.
각 메서드의 내부 구현이 어떻게 되느냐-가 사실 핵심인 것으로 이해됩니다. 한편으로, 이 클래스를 보면 하네스가 LLM API의 '추상화 인터페이스'처럼 보입니다.

평가(Evaluation) Harness - LLM-as-Judge 패턴

class EvalHarness:
    def __init__(self, judge_model, test_cases):
        self.judge = judge_model
        self.test_cases = test_cases

    def run_eval(self, target_model):
        results = []
        for case in self.test_cases:
            # 타겟 모델 실행
            output = target_model.generate(case.input)

            # 판정 모델로 품질 평가
            score = self.judge.evaluate(
                input=case.input,
                output=output,
                expected=case.expected,
                rubric=case.rubric
            )
            results.append(score)

        return EvalReport(results)

이 예시 코드는 앞선 Workflow의 Evaluation 스텝을 구현한 것이라고도 볼 수 있습니다. OUTPUT을 평가하여 답변의 품질을 확인하는 역할을 하는 것으로 이해했습니다.
"비정형적", "확률적"인 LLM의 응답을 제어하기 위한 구조라는 생각이 들어 인상적입니다. 또한 이 Harness 패턴은 기존의 소프트웨어의 모듈화 패턴과 유사한 것 같아 친숙한 느낌을 받았습니다.

4.4 Harness의 주요 기능

앞선 예시에서 Evaluate, Scoring, Logging, Validation 등의 스텝이 있었습니다.
Harness에서 일반적으로 사용되는 모듈(기능)은 다음과 같다고 합니다:

기능	설명	비고
Wrapping	모델 호출을 함수로 추상화	API 변경에 대한 격리
Retry Logic	실패 시 자동 재시도	Rate limit, 일시적 오류 처리
Validation	출력 형식/내용 검증	JSON 스키마, 정책 준수 등
Evaluation	품질 측정 및 점수화	LLM-as-Judge, 휴리스틱
Logging	입출력 추적	디버깅, 감사
Cost Tracking	토큰 사용량 모니터링	비용 최적화
A/B Testing	모델/프롬프트 비교	성능 개선

결과적으로

1. LLM을 호출하기 전 프롬프트를 최적화/전처리
2. 응답을 평가/검증
3. Cost를 트래킹

등의 역할을 수행하는 모듈의 집합으로 이해하였습니다.
결국 LLM의 입/출력을 효율적으로 제어하기 위한 아키텍처 패턴이라는 생각이 듭니다.

---

5. AI Pipeline

5.1 개념 정의

AI 파이프라인(AI Pipeline)이란, 여러 컴포넌트(AI 모델, 데이터 처리 단계, 외부 서비스 등)를 연결하여 엔드-투-엔드로 복잡한 작업을 자동화하는 아키텍처를 의미합니다.
가장 높은 추상화 수준에서 "시스템 전체"를 다룬다는 특징이 있다고 합니다.

5.2 AI Pipeline의 유형

한동안 자주 화자되었던 용어들이 등장합니다. 앞선 Workflow, Harness의 LLM I/O를 최적화 수단임을 바탕으로 이해했습니다.

RAG (Retrieval-Augmented Generation) 파이프라인

[사용자 쿼리]
    ↓
[임베딩 모델: 쿼리 벡터화]
    ↓
[벡터 DB: 유사 문서 검색]
    ↓
[재순위화(Reranker)]
    ↓
[LLM: 검색 결과 기반 응답 생성]
    ↓
[출력 후처리]

"쿼리 벡터화", "백터 DB 검색", "재순위화" + "검색 결과 기반 응답"이 RAG의 주요 특징으로 보입니다.
모든 용어가 생소하여 간략히 정리하였습니다:

• 임베딩 모델: 텍스트를 벡터로 변환하는 모델
• 백터 DB: 벡터를 저장하고 검색하는 DB
• 재순위화: 검색된 결과를 바탕으로 순위를 재조정하는 역할
• 검색: LLM이 외부 지식을 활용할 수 있도록 문서를 검색하는 역할

RAG에서 핵심은 외부 지식을 LLM이 활용할 수 있도록 문서를 검색하는 역할로 이해했습니다. 여기서 검색은 전통적인 DB 검색이 아니라, 벡터 유사도 검색을 사용한다고 합니다.
내용이 깊어질 것같아 추후 별도 페이지로 정리할 예정입니다.

Multi-Agent Pipeline

[오케스트레이터 에이전트]
    ├─→ [리서치 에이전트] → 웹 검색 → 결과 반환
    ├─→ [코드 에이전트] → 코드 작성/실행 → 결과 반환
    └─→ [편집 에이전트] → 최종 문서 작성
         ↓
    [통합 및 최종 출력]

여러 에이젼트를 병렬적으로 배치하여 작업을 수행하는 파이프라인입니다.
각 에이젼트는 **자신만의 전문 분야(Domain)**와 **도구(Tool)**를 가지며,
이를 앞서 살펴본 워크플로우로 연결하여 복잡한 작업을 수행하는 방식입니다.

예를 들어, Kimi의 문서 분석의 경우 다음과 같은 멀티에이전트 파이프라인이 동작한다고 합니다.

데이터 처리 Pipeline

[원시 데이터 수집]
    ↓
[ETL (Extract, Transform, Load)]
    ↓
[AI 모델 추론 (배치/스트리밍)]
    ↓
[결과 저장 및 서빙]
    ↓
[모니터링 및 피드백 루프]

LLM에 실시간으로 대기하다가 응답하는 게 아니라, 대량의 데이터를 한꺼번에 처리하는 방식입니다.
데이터 처리 파이프라인은 배치Batch 처리에 초점을 맞춘 구조로 이해했습니다.

5.3 Pipeline의 핵심 특성

데이터 흐름 지향성 (Data Flow Oriented)

Source → Transform → Model → Aggregate → Sink

상태 관리 전략

# Stateless Pipeline (각 단계가 독립적)
def stateless_pipeline(input_data):
    step1_result = transform(input_data)
    step2_result = model_inference(step1_result)
    return postprocess(step2_result)

# Stateful Pipeline (상태 누적, 에이전트 기반)
class StatefulPipeline:
    def __init__(self):
        self.memory = []
        self.context = {}

    def run(self, input_data):
        self.context.update(analyze(input_data))
        result = self.model.generate(input_data, self.context)
        self.memory.append(result)
        return result

5.4 Pipeline vs Workflow의 핵심 차이

파이프라인을 조금 더 상위 개념으로, 워크플로우를 포함하는 개념으로 이해했습니다.

Workflow = 논리 흐름 설계도 (What to do, in what order)
Pipeline = 실제 데이터 이동 경로 + 컴포넌트 연결 (How data flows through components)

비유:
  Workflow = 레시피 (순서와 조건)
  Pipeline = 주방 설비 연결 (가스관, 배수관, 조리 기구 배치)

---

6. 4가지 개념 비교 매트릭스

마지막으로 복습 차원에서 앞서 살펴본 4가지 개념을 비교해보겠습니다.

6.1 핵심 속성 비교

속성	SKILL.md	Workflow	Harness	AI Pipeline
추상화 수준	최하위	중간	중간-상위	최상위
주요 역할	지식 제공	실행 흐름 정의	실행 환경 제어	시스템 통합
위치	모델 컨텍스트 내	애플리케이션 로직	모델 호출 레이어	시스템 아키텍처
변경 주체	프롬프트 엔지니어	개발자/아키텍트	인프라/ML 엔지니어	시스템 아키텍트
런타임 가시성	모델에게만	실행 엔진에게	프레임워크	전체 시스템
재사용 단위	도메인별 문서	태스크별 플로우	모델 독립적	비즈니스 솔루션

6.2 관심사 분리 (Separation of Concerns)

SKILL.md   → "이 도메인에서 어떤 패턴이 올바른가?"     (Domain Knowledge)
Workflow   → "어떤 순서로 무엇을 해야 하는가?"         (Execution Logic)
Harness    → "어떻게 안정적으로 실행하고 측정하는가?"   (Reliability & Observability)
Pipeline   → "어떻게 구성 요소들을 연결해 가치를 만드는가?" (System Integration)

6.3 장애(Failure) 발생 시 책임 소재

장애 유형	책임 레이어	수정 위치
모델이 잘못된 코드 패턴 사용	SKILL.md	문서 내 규칙 추가
단계 순서가 잘못됨	Workflow	흐름 재설계
모델 API 오류 처리 안 됨	Harness	재시도/폴백 로직
컴포넌트 간 데이터 포맷 불일치	Pipeline	인터페이스 계약 수정

---

7. Claude 전용인가? 범용인가?

2024년에 Cursor를 사용하며 rules.md라는 패턴에 익숙했었는데, Claude에서 SKILL.md라는 비슷한 개념을 사용하여 혼동이 있었습니다.
그렇다면 SKILL.md는 Claude에서만 사용할 수 있는 것인지, 다양한 모델에 일반적으로 통용되는 개념인 것인지 의문이 들어 내용을 정리했습니다.
결론적으로, 용어는 다르지만 공유하는 개념과 주된 목적(LLM I/O 최적화 및 결과 품질 향상)은 범용적이라는 것을 알 수 있습니다.

7.1 SKILL.md: Claude 생태계 특화

Claude 전용인 이유:

• 컨텍스트 윈도우 주입 방식은 Claude의 system prompt / tool description 메커니즘에 최적화
• Anthropic의 Claude Code / claude.ai 인터페이스에서 파일 경로(/mnt/skills/) 기반으로 동작
• SKILL.md의 description 필드는 Claude의 도구 선택 로직과 연동

유사 개념 (타 모델):

플랫폼	유사 메커니즘	차이점
OpenAI GPT	Custom Instructions, System Prompt	파일 기반 구조화 없음
Google Gemini	System Instructions	동적 로딩 없음
LangChain	PromptTemplate + Few-shot examples	코드 레벨 구현
LlamaIndex	Node postprocessors, Context augmentation	데이터 파이프라인 중심

결론: SKILL.md의 개념(구조화된 지식 주입)은 범용이나, 구현(파일 명명, 로딩 트리거, 경로 규약)은 Claude/Anthropic 전용-- 이라고 합니다.

7.2 Workflow: 완전 범용

모든 LLM 플랫폼에서 동일한 개념이 적용된다.

# OpenAI
from openai import OpenAI
client = OpenAI()

def workflow_step1(input):
    return client.chat.completions.create(model="gpt-4o", messages=[...])

# Anthropic (Claude)
import anthropic
client = anthropic.Anthropic()

def workflow_step1(input):
    return client.messages.create(model="claude-opus-4-6", messages=[...])

# 워크플로 로직 자체는 동일

주요 Workflow 프레임워크들은 모두 멀티 모델을 지원합니다:

• LangChain: OpenAI, Anthropic, Google, Cohere 등
• LlamaIndex: 동일
• Prefect / Airflow: LLM 워크플로 오케스트레이션
• Temporal: 내구성 있는 AI 워크플로

7.3 Harness: 범용 (단, 구현은 모델별)

Harness의 개념은 소프트웨어 테스팅에서 유래한 범용 패턴입니다.

모델별 Harness 구현 차이:

# Claude Harness
class ClaudeHarness(BaseHarness):
    def call(self, prompt, **kwargs):
        return anthropic_client.messages.create(
            model="claude-sonnet-4-6",
            max_tokens=1024,
            messages=[{"role": "user", "content": prompt}]
        )

# GPT Harness
class GPTHarness(BaseHarness):
    def call(self, prompt, **kwargs):
        return openai_client.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": prompt}]
        )

범용 Harness 도구들:

• Promptfoo: 멀티 모델 프롬프트 테스트 harness
• Evals (OpenAI): GPT 특화 evaluation harness
• Braintrust: 모델 불가지론적(model-agnostic) evaluation
• Langsmith: LangChain 기반 harness

7.4 AI Pipeline: 완전 범용 (인프라 수준)

AI Pipeline은 특정 모델이나 플랫폼에 독립적인 아키텍처 패턴입니다.

모델 불가지론적 Pipeline 예시:

# Prefect 기반 AI Pipeline (모델 무관)
pipeline:
  - name: ingest
    type: data_loader
    source: s3://bucket/data

  - name: preprocess
    type: transform
    steps: [tokenize, normalize]

  - name: inference
    type: model_call
    provider: ${MODEL_PROVIDER}  # claude / gpt / gemini 교체 가능
    model: ${MODEL_NAME}

  - name: postprocess
    type: transform
    steps: [parse_output, validate]

  - name: store
    type: data_sink
    destination: postgres://db/results

---

8. Under the Hood: 내부 작동 원리

추가적으로 앞서 살펴본 내용들이 내부에서 어떻게 작동하는지 궁금하여 조사해보았습니다.
관련된 논문, 공식 문서를 참조하여 원문과 함께 읽어보면 좋을듯 싶습니다.

8.1 SKILL.md의 작동 원리

메커니즘: Retrieval-Augmented Prompting

SKILL.md는 본질적으로 동적 system prompt 확장-이라고 합니다.

[사용자 요청 분석]
    ↓
[관련 SKILL.md 파일 식별]
    ↓
[파일 내용을 컨텍스트에 삽입]
    ↓
[모델 호출 시 해당 지식이 "기억"처럼 작동]

왜 효과적인가?

LLM의 in-context learning 능력에 기반하기 때문입니다.
모델은 컨텍스트 내 정보를 즉시 활용할 수 있으며, 특히 훈련 데이터에 없는 최신 패턴이나 환경별 quirk를 주입하는 데 효과적입니다.

참고: Anthropic - Prompt Engineering Guide
참고: In-Context Learning (Brown et al., 2020, GPT-3 논문)

컨텍스트 윈도우 경제학:

총 컨텍스트: 200K tokens (Claude Sonnet 4.6)
   ├─ System Prompt: ~2K tokens
   ├─ SKILL.md 주입: ~3-8K tokens (필요시)
   ├─ 사용자 대화 기록: ~5-20K tokens
   └─ 남은 공간: 출력 + 추가 컨텍스트

SKILL.md는 필요할 때만 로드되어 컨텍스트를 효율적으로 사용한다고 합니다.

참고: Anthropic - Long Context Tips

---

8.2 Workflow의 작동 원리

메커니즘: Directed Acyclic Graph (DAG) 실행

대부분의 워크플로 엔진은 내부적으로 DAG를 구성하여 실행 순서를 결정한다고 합니다.

# LangGraph 내부 원리 (개념적)
class WorkflowGraph:
    def __init__(self):
        self.nodes = {}    # 각 단계 (노드)
        self.edges = {}    # 단계 간 전이 (엣지)

    def execute(self, initial_state):
        state = initial_state
        current_node = self.entry_point

        while current_node != END:
            # 현재 노드(단계) 실행
            result = self.nodes[current_node](state)
            state = {**state, **result}

            # 다음 노드 결정 (조건부 분기)
            next_node = self.edges[current_node](state)
            current_node = next_node

        return state

Chain of Thought vs Workflow:

Chain of Thought: 모델 내부에서 단계적 추론 (단일 호출)
Workflow: 여러 모델 호출을 코드 레벨에서 연결 (다중 호출)

CoT: "생각해봐 → 분석해 → 결론내려" (프롬프트 내)
Workflow: step1() → step2() → step3() (코드 내)

참고: LangGraph - Stateful Multi-Actor Applications
참고: Anthropic - Building Effective Agents
참고: Chain-of-Thought Prompting (Wei et al., 2022)

---

8.3 Harness의 작동 원리

메커니즘: Decorator / Middleware 패턴

Harness는 소프트웨어 공학의 Decorator 패턴을 AI 호출에 적용하는 방법이라고 합니다.

# Middleware 체인으로서의 Harness
class HarnessMiddlewareChain:
    def __init__(self, model_fn):
        self.model_fn = model_fn
        self.middlewares = []

    def use(self, middleware):
        self.middlewares.append(middleware)
        return self

    def __call__(self, input):
        # 미들웨어 체인 실행 (양방향: 전처리 → 모델 → 후처리)
        handler = self.model_fn
        for middleware in reversed(self.middlewares):
            handler = middleware(handler)
        return handler(input)

# 사용
harness = HarnessMiddlewareChain(claude_call)
    .use(RateLimiter(rpm=60))
    .use(InputValidator(schema=my_schema))
    .use(OutputParser(format="json"))
    .use(CostTracker(budget=10.0))
    .use(Logger(level="INFO"))

Evaluation Harness의 핵심: LLM-as-Judge

┌──────────────────────────────────────────────────────┐
│                  EVALUATION HARNESS                  │
│                                                      │
│  Test Case: {input, expected_output, rubric}        │
│       ↓                                              │
│  Target Model: generates actual_output              │
│       ↓                                              │
│  Judge Model (강력한 LLM):                           │
│    - input을 이해했는가?                              │
│    - expected와 semantically 일치하는가?              │
│    - rubric의 기준을 충족하는가?                      │
│       ↓                                              │
│  Score: {accuracy: 0.85, relevance: 0.92, ...}      │
└──────────────────────────────────────────────────────┘

참고: Promptfoo - LLM Testing & Evaluation
참고: Braintrust - AI Evaluation Platform
참고: LLM-as-Judge (Zheng et al., 2023)

---

8.4 AI Pipeline의 작동 원리

메커니즘: 스트림 처리 + 이벤트 기반 아키텍처

현대 AI Pipeline은 전통적인 데이터 파이프라인 패턴위에 LLM을 통합한 형태라고 볼 수 있습니다.

[데이터 소스]
    ↓ (Kafka / Kinesis / Queue)
[스트림 처리 레이어]
    ↓
[Feature Engineering]
    ↓
[LLM 추론 클러스터]  ←→  [벡터 DB]
    ↓
[결과 후처리]
    ↓
[서빙 레이어 / 캐싱]
    ↓
[모니터링 & 피드백]

벡터 임베딩 Pipeline의 핵심 수학:

문서 → 임베딩 모델 → 고차원 벡터 (예: 1536차원)
쿼리 → 임베딩 모델 → 쿼리 벡터

유사도 = cos(문서 벡터, 쿼리 벡터)
       = (A·B) / (|A| × |B|)

가장 유사한 상위 K개 문서 검색 → LLM에 컨텍스트로 주입

Tool Use / Function Calling의 내부 원리:

[LLM]: "날씨 정보가 필요해"
    ↓
[Tool Decision]: get_weather(location="Seoul") 호출
    ↓
[실제 API 호출]: OpenWeatherMap API
    ↓
[결과 반환]: {"temp": 22, "condition": "cloudy"}
    ↓
[LLM]: 결과를 통합하여 최종 응답 생성

이 Tool Use 메커니즘이 Pipeline에서 AI가 외부 시스템과 상호작용하는 핵심입니다.

참고: Anthropic - Tool Use (Function Calling)
참고: Attention Is All You Need (Vaswani et al., 2017)
참고: Pinecone - Vector Database Fundamentals
참고: Apache Kafka - Stream Processing

---

8.5 MCP (Model Context Protocol)의 역할

MCP는 이 모든 개념의 표준화 레이어입니다.
Claude의 Tool Use와 외부 서비스 연결을 표준 프로토콜로 통일합니다.

┌────────────────────────────────────────────────┐
│                    Claude                      │
│  SKILL.md ──→ 지식 레이어                      │
│  Workflow ──→ 실행 로직                        │
│  Harness  ──→ 안정성 레이어                    │
│               ↕                                │
│          MCP Protocol                          │
│               ↕                                │
├────────────────────────────────────────────────┤
│  Gmail MCP  │  Drive MCP  │  Calendar MCP  │...│
└────────────────────────────────────────────────┘

참고: Anthropic - Model Context Protocol
참고: MCP 공식 사이트

---

9. 실제 조합 패턴

앞서 살펴본 모든 패턴을 조합하여, 단계별로 LLM Input과 Output이 실제 사용 환경에서 어떻게 상호작용하는지 알아봅니다:

9.1 Claude Code 작업 예시: DOCX 생성

사용자: "분기별 보고서를 Word 파일로 만들어줘"
    ↓
[Pipeline]: 문서 생성 파이프라인 시작
    ↓
[Harness]: Claude API 호출 준비, 재시도 로직 활성화
    ↓
[Workflow Step 1]: SKILL.md 읽기 결정 (docx 태스크 감지)
    ↓
[SKILL.md]: docx 라이브러리 패턴, critical rules 로드
    ↓
[Workflow Step 2]: 문서 구조 설계
    ↓
[Workflow Step 3]: 코드 생성 (SKILL.md 지식 활용)
    ↓
[Harness]: 출력 검증 (파일 생성 성공 여부)
    ↓
[Pipeline]: 파일을 /outputs/에 저장 및 사용자에게 전달

9.2 멀티 에이전트 연구 시스템

# Pipeline 레벨 (전체 오케스트레이션)
research_pipeline = Pipeline([
    WebSearchAgent(harness=ClaudeHarness()),    # Harness로 안정성 보장
    SummarizationAgent(skill="research_writing.md"),  # SKILL.md로 품질 보장
    FactCheckAgent(workflow=verification_flow),  # Workflow로 절차 보장
    ReportAgent(skill="docx_generation.md")
])

# Workflow 레벨 (팩트체크 단계)
verification_flow = Workflow([
    Step("extract_claims"),
    Step("search_each_claim"),
    ConditionalBranch(
        condition="claim_supported",
        true_path=Step("mark_verified"),
        false_path=Step("flag_disputed")
    ),
    Step("generate_report")
])

9.3 요약: 언제 어떤 레이어를 수정할까?

증상	수정할 레이어	구체적 조치
모델이 잘못된 라이브러리 API 사용	SKILL.md	올바른 패턴과 금지 사례 추가
작업 단계가 누락되거나 순서가 틀림	Workflow	DAG 재설계
API 오류 시 앱이 충돌함	Harness	재시도/폴백 로직 추가
전체 시스템 처리량(throughput)이 낮음	Pipeline	병렬 처리, 배치 처리 도입
새 도메인 지식이 필요함	SKILL.md	새 .md 파일 작성
새 외부 서비스 연동 필요	Pipeline + MCP	MCP 서버 연결

---

참고 자료 모음

Anthropic 공식 문서

• Anthropic Docs 메인
• Claude - Building Effective Agents
• Tool Use (Function Calling)
• Model Context Protocol
• Prompt Engineering Overview
• Long Context Tips

프레임워크 및 도구

• LangChain 공식 문서
• LangGraph - Stateful Workflows
• LlamaIndex 공식 문서
• Promptfoo - LLM Testing Harness
• Braintrust - AI Evaluation
• Prefect - Workflow Orchestration

핵심 논문

• GPT-3 & In-Context Learning (Brown et al., 2020)
• Chain-of-Thought Prompting (Wei et al., 2022)
• Attention Is All You Need (Vaswani et al., 2017)
• LLM-as-Judge (Zheng et al., 2023)
• ReAct: Reasoning + Acting in LLMs (Yao et al., 2022)
• Toolformer: LLMs Can Teach Themselves to Use Tools (Schick et al., 2023)

---

이 문서는 AI 생태계의 빠른 변화에 따라 내용이 달라질 수 있습니다.