Harness, Scaffold, 그리고 정확히 이해해야 할 AI Agent 용어들

이는 입문자뿐만 아니라 최신 발전 사항을 따라잡으려는 실무자들에게도 매우 혼란스러울 수 있습니다. ICLR 2026 이후, 저희 중 한 명(@ariG23498)이 이러한 혼란을 잘 포착한 질문을 게시했습니다:

"에이전트 (Agent) 문맥에서 'harness'와 'scaffold'라는 용어가 무엇을 의미하나요? ICLR에 있는 동안 많은 설명을 들었지만, 왜 하나의 설명으로 수렴되지 않는지 이해할 수 없었습니다."

이 용어집 (Glossary)은 명확하고 일관된 설명 없이 계속해서 등장하는 용어들을 정립하려는 저희의 시도입니다. 이 용어집은 해당 분야의 모든 용어를 담은 포괄적인 사전이 아닙니다. 대신, 자주 혼동되거나, 서로 다른 방식으로 재사용되거나, 당연하다고 여겨지지만 실제로는 그렇지 않은 개념들에 집중합니다.

이 용어들 중 대부분은 에이전트를 구축하거나, 배포하거나, 혹은 Claude Code, Codex, 또는 Hermes Agent와 같은 도구를 사용할 때 모두 등장합니다. 마지막 섹션은 모델 학습 (Training)에 특화된 개념들을 다루며, 이는 해당 분야에서 작업하는 경우에 더 관련이 있습니다.

이 용어들 중 상당수는 아직 보편적으로 수용되는 정의가 없으며, 서로 다른 프레임워크가 동일한 단어를 다르게 사용하기도 합니다. 여기서의 목표는 하나의 정답인 어휘를 강요하는 것이 아니라, 논의를 더 쉽게 따라갈 수 있도록 실용적인 멘탈 모델 (Mental model)을 제공하는 것입니다.

시작해 보겠습니다.

• 모델 (Model)
• 스캐폴딩 (Scaffolding)
• 하네스 (Harness)
• 에이전트 (Agent)
• 컨텍스트 엔지니어링 (Context Engineering)
• 정책 (Policy)
• 도구 사용 (Tool Use)
• 기술 (Skills)
• 하위 에이전트 (Sub-agents)
• 학습 (Training)
• 더 알아보기 (Learn More)

모델 (Model)은 LLM (Large Language Model)을 의미합니다. 텍스트를 입력받아 텍스트를 출력합니다 (예: Claude, Qwen, GPT, Kimi, DeepSeek 등...). 모델 자체는 호출 간의 메모리 (Memory)가 없으며, 루프 (Loop)도 없습니다. 모델은 도구를 호출하려는 의도를 표현할 수 있지만, 실제로 이를 실행하기 위해서는 하네스 (Harness)가 필요합니다. 모델은 하나의 프롬프트 (Prompt)에 답하고 멈춥니다. 이를 스캐폴딩 (Scaffolding)과 하네스 (Harness)로 감싸면 에이전트 (Agent)가 됩니다.

모델 주변의 동작 정의 계층 (behavior-defining layer): 시스템 프롬프트 (system prompt), 도구 설명 (tool descriptions), 모델의 응답이 파싱 (parsing)되는 방식, 단계별로 무엇을 기억하는지 (컨텍스트 관리 (context management)) 등이 포함됩니다. 이는 훈련 (training) 중이든 추론 (inference) 중이든, 모델이 세상을 어떻게 바라보고 그 안에서 어떻게 행동할지를 결정합니다.

Claude Code, Codex, Antigravity CLI와 같은 제품들은 이 전체를 하네스 (harness)라고 부릅니다. Claude Code의 자체 문서에는 다음과 같이 직접적으로 명시되어 있습니다: "Claude Code는 Claude를 둘러싼 에이전트적 하네스 (agentic harness) 역할을 합니다." 이것이 광범위한 용례입니다. 즉, 하네스는 모델이 아닌 모든 것을 의미합니다. 스캐폴드 (scaffold)와 하네스의 구분은 훈련 파이프라인 (training pipeline)에서처럼 이들을 별도로 고려해야 할 때 가장 중요합니다. 또한 하네스가 의존하는 모든 인프라(훅 (hooks), 런타임 설정 (runtime configuration), 심지어 디렉토리 구조까지)를 포괄하기 위해 "스캐폴드"라는 용어가 더 넓은 의미로 사용되는 것도 들을 수 있을 것입니다.

Claude Code나 Codex와 같은 일부 제품은 제공업체의 모델과 밀접하게 결합되어 있습니다. 반면 Antigravity CLI나 Hermes Agent와 같은 다른 제품들은 어떤 모델이든 연결하여 사용할 수 있게 해줍니다.

에이전트 내부의 실행 계층 (execution layer): 모델을 호출하고, 도구 호출 (tool calls)을 처리하며, 언제 멈출지를 결정합니다. 하네스는 에이전트를 실제로 작동하게 만드는 요소입니다. 위에서 정의한 스캐폴드는 모델이 작업하는 기반, 즉 모델의 지침 (instructions), 도구 (tools), 형식 (format)을 의미합니다.

**하네스 엔지니어링 (Harness engineering)**은 이 계층을 잘 설계하는 학문입니다. 에이전트가 언제 멈춰야 하는지, 오류를 어떻게 처리할지, 그리고 에이전트가 경로를 벗어나지 않도록 유지하는 가드레일 (guardrails)은 무엇인지 등을 결정합니다. 이는 훈련과 추론 모두에 적용됩니다. Addy Osmani의 글과 OpenAI의 Codex 구축 사례 모두 추론 측면에서 이 내용을 다루고 있습니다.

평가 (evaluation) 시점에는 동일한 패턴이 **평가 하네스 (eval harness)**로 나타납니다. 훈련 데이터를 수집하는 대신, 모델 체크포인트 (model checkpoint)에서 고정된 시나리오 세트를 실행하고 가중치 (weights)를 업데이트하는 대신 지표 (metrics)를 기록합니다.

이 용어는 에이전트 (agent)가 관찰 (observation)을 받아 행동 (action)을 반환하는 단순한 함수인 강화학습 (reinforcement learning)에서 유래되었습니다. 환경 (environment)은 그 행동을 받아 새로운 관찰을 반환하며, 이 루프 (loop)가 반복됩니다. 이 루프는 여전히 LLM 에이전트 (LLM agents)가 작동하는 방식의 핵심입니다.

LLM 세계에서 이 용어는 확장되었습니다. 에이전트 (agent)는 단순히 응답하는 것이 아니라 행동할 수 있게 해주는 모델 (model)과 그 주변의 모든 것을 의미합니다. 이는 가공되지 않은 텍스트 생성 (raw text generation)을 정보를 받아들이고, 무엇을 할지 결정하며, 그 결과에 따라 행동하는 루프 내에서 작동할 수 있는 무언가로 변화시킵니다.

코딩 에이전트 (coding agent)를 구체적인 예로 들어보겠습니다. 시스템 프롬프트 (system prompt), 도구 설명 (tool descriptions), 그리고 모델이 따르는 출력 형식 (output format)이 스캐폴딩 (scaffolding)을 형성합니다. 모델을 호출하고, 도구 호출 (tool calls)을 처리하며, 언제 멈출지를 결정하는 루프가 하네스 (harness)입니다. 훈련 (training) 시점에 하네스는 이러한 루프 중 다수를 병렬로 실행하고 그 결과를 모델 업데이트를 위해 다시 피드백합니다.

커뮤니티에서는 보통 **에이전트 (Agent) = 모델 (Model) + 하네스 (Harness)**라고 정의합니다 (참고로 @Vtrivedy10과 Will Brown의 트윗 내용입니다). 당신이 모델이 아니라면, 당신은 하네스입니다. 대부분의 혼란을 야기하는 하네스 (harness)와 스캐폴딩 (scaffold) 사이의 미묘한 차이는 위의 두 섹션에서 다루고 있습니다.

사람들이 Claude Code, Codex 또는 Cursor와 같은 제품에 대해 이야기할 때, 그들은 특정 모델 위에 구축되어 함께 설계되고 최적화된 특정 하네스 (harness)를 지칭하는 것입니다. 동일한 기반 모델을 사용하는 두 제품이라도 하네스 (harness)가 서로 다른 선택을 하기 때문에 완전히 다르게 느껴질 수 있습니다. 또한 동일한 하네스에 더 나은 모델을 교체하는 것만으로도 경험이 달라집니다. 모델 (model), 하네스 (harness), 그리고 제품 (product)은 세 가지 서로 다른 것입니다.

에이전트의 컨텍스트 윈도우 (context window)에 들어갈 내용을 설계하는 것: 모델이 각 단계에서 보는 것, 시스템 프롬프트 (system prompt), 도구 설명 (tool descriptions), 대화 기록 (conversation history), 검색된 지식 (retrieved knowledge) 등이 이에 해당합니다. 이는 단 한 번의 결정으로 끝나지 않습니다. 모델이 실행됨에 따라 이전의 턴 (turns)이 향후 호출될 내용의 형태를 결정하며, 하네스 (harness)는 실행 전반에 걸쳐 이를 능동적으로 관리합니다. 이는 훈련 (training)과 추론 (inference) 모두에 적용되지만, 잘못 설계했을 때 발생하는 비용은 매우 다릅니다. 훈련 단계에서는 모델이 보는 내용이 학습되는 내용을 결정합니다. 이를 잘못 설계하면 모델을 다시 훈련시켜야 합니다. 반면 추론 단계에서는 단지 텍스트일 뿐이므로, 프롬프트를 변경하고 다시 배포하기만 하면 됩니다. HF 컨텍스트 엔지니어링 코스 (HF Context Engineering Course)에서 이 내용을 심도 있게 다룹니다.

메모리 (memory) 또한 이 그림의 일부입니다. **단기 메모리 (Short-term memory)**는 단일 실행 동안 컨텍스트 윈도우에 남아 있는 것들, 즉 대화 기록, 도구 결과, 이전의 추론 과정을 의미합니다. **장기 메모리 (Long-term memory)**는 세션 전반에 걸쳐 지속되며, 외부에 저장되었다가 필요할 때 검색된 후 관련성이 있을 때 다시 컨텍스트로 주입됩니다.

정책 (policy)은 에이전트가 따르는 행동 양식입니다. 어떤 상황이 주어지든, 가능한 각 행동을 취할 확률을 정의합니다. LLM 시스템에서 이 정책의 일부는 모델 가중치 (weights)에 학습되지만, 행동은 주변의 스캐폴딩 (scaffolding)과 하네스 (harness)에도 의존합니다. 동일한 모델이라도 프롬프트, 도구, 메모리, 그리고 실행 루프 (execution loop)에 따라 매우 다르게 행동할 수 있습니다. 정책은 에이전트가 아닙니다. 정책은 행동을 정의하며, 에이전트는 환경 내에서 작동하는 전체 시스템을 의미합니다. 체크포인트 (checkpoint)를 스캐폴딩과 하네스로 감싸서 배포하면, 그 행동이 곧 정책이 되는 에이전트를 얻게 됩니다.

에이전트가 자신 외부로 확장하는 방법: API, 코드 인터프리터 (code interpreters), 데이터베이스, 웹 검색, 파일 시스템 등이 있습니다. 모델은 구조화된 형식으로 도구를 사용하려는 의도 (intent)를 표현합니다. 현대적인 추론 API (inference APIs)는 이를 일급 객체 (first-class object)로 노출합니다. 즉, 하네스가 호출을 직접 수신하여 적절한 함수로 라우팅 (routing)합니다. 결과는 다시 컨텍스트로 피드백되어 루프가 계속됩니다.

다단계 작업 (multi-step tasks)을 가능하게 하는 재사용 가능한 구조화된 지식 패키지입니다. **도구 (tool)**가 특정 동작("이 명령어를 실행해")이라면, **기술 (skill)**은 목표를 달성하는 데 필요한 모든 것을 하나로 묶은 것입니다("이 버그를 조사하고, 가설을 세운 뒤, 수정 사항을 작성해"). 기술은 에이전트 간에 이식 가능하며 필요할 때 로드됩니다. 도구, 기술, 그리고 서브 에이전트 (sub-agent) 사이의 경계는 프레임워크에 따라 달라집니다. HF Context Engineering 코스에서는 기술 (skill)을 심도 있게 다룹니다.

특정 하위 작업 (subtask)을 처리하기 위해 다른 에이전트에 의해 호출되는 에이전트입니다. 자체적인 모델과 스캐폴드 (scaffold)를 가지며, 독립적으로 추론하고 결과를 반환합니다. 호출하는 에이전트는 그것이 내부적으로 어떻게 작동하는지 알 필요가 없습니다. 이것이 **서브 에이전트 (sub-agent)**를 도구 (tool) (함수 호출)나 기술 (skill) (패키징된 지식)과 구분 짓는 점입니다. 즉, 서브 에이전트는 스스로 추론하고, 도구를 사용하며, 더 나아가 다른 서브 에이전트를 호출할 수 있습니다.

위의 용어들은 학습 (training) 중이든 배포 (deploying) 중이든 상관없이 적용됩니다. 이 네 가지는 에이전트가 작업을 수행하고, 점수를 받고, 모델의 가중치 (weights)가 업데이트되는 학습 과정에 특화된 것입니다. LLM을 위한 모든 강화학습 (RL) 학습 시스템은 동일한 파이프라인을 중심으로 구축됩니다:

환경 (environment)은 상호작용할 수 있는 모든 것을 의미합니다. 즉, 동작 (action)을 입력으로 받아 내부 상태 (state)를 업데이트하고 관찰 (observation)을 반환하는 상태 유지 객체 (stateful object)입니다. LLM 문맥에서 동작 (action)은 일반적으로 도구 호출 (tool calls)입니다. 파일 시스템이 간단한 예시입니다: touch foo.txt라는 동작은 파일을 생성함으로써 상태를 업데이트하며, 관찰 (observation)은 업데이트된 파일 목록이 될 수 있습니다. 정의는 프레임워크마다 다를 수 있습니다.

최근 이와 관련된 전용 가이드를 게시했으므로, 여기서 내용을 압축하기보다는 유형, 프레임워크 및 예시에 대한 완전한 분석이 담긴 'The Ultimate Guide to RL Environments'를 참조하시기 바랍니다.

트레이너 (trainer)는 에이전트를 더 나아지게 만드는 요소입니다. 트레이너는 많은 에이전트 에피소드 (episodes)를 실행하고, 결과를 채점하며, 이를 사용하여 내부 모델의 가중치 (weights)를 업데이트합니다. TRL의 GRPOTrainer가 구체적인 예시입니다. 이는 에피소드 생성, 보상 채점 (reward scoring), 가중치 업데이트를 처리하는 단일 클래스입니다.

Rollout(롤아웃)은 시작부터 끝까지 에이전트가 실행되는 전체 과정을 의미합니다. 즉, 에이전트가 각 단계에서 무엇을 보았고, 무엇을 수행했으며, 어떤 보상을 받았는지를 포함합니다. 문맥에 따라 trajectory(궤적) 또는 *trace(추적)*라고도 불립니다. 이는 강화학습 (RL) 알고리즘이 학습하는 데 사용하는 가공되지 않은 데이터입니다.

보상 (Reward)은 훈련 알고리즘에 모델이 개선되고 있는지 여부를 알려주는 점수입니다. 이는 verifiable(검증 가능한) (테스트 통과/실패, 정답 일치 여부) 방식이거나, learned(학습된) (인간의 선호도, LLM-as-judge) 방식일 수 있으며, sparse(희소한) (에피소드 끝에 단 하나의 점수 부여) 방식 또는 dense(조밀한) (각 단계마다 점수 부여) 방식일 수 있습니다. Trainer(트레이너)는 실제로 내부 모델의 가중치 (weights)를 업데이트하기 위해 이 보상을 사용합니다. 각 유형에 대한 자세한 분석은 Adithya의 가이드에 있는 Reward Architecture (보상 아키텍처) 섹션을 참조하십시오.

**Rubrics(루브릭)**는 보상을 단일 숫자가 아닌, 가중치가 부여된 명시적인 차원들로 분해합니다. OpenEnv과 Verifiers는 루브릭을 결합 가능한 객체(WeightedSum, Sequential, Gate)로 구현합니다.

• @Vtrivedy10: The Anatomy of an Agent Harness: harness 구성 요소에 대한 상세한 분석과 각 요소가 존재하는 이유
• Agent Harness Engineering: Agent = Model + Harness라는 수렴된 프레임워크와 코딩 에이전트 예시
• Harness Engineering: leveraging Codex in an agent-first world: scaffolding, 피드백 루프, 추론 시의 컨텍스트 관리를 포함하여 Codex 에이전트만으로 제품을 구축한 실제 사례
• Tool Schema Rendering Atlas (evalstate): 도구 스키마가 모델 전반에 걸쳐 어떻게 프롬프트 텍스트가 되는지, 제공자 템플릿이 적용된 후 각 모델이 실제로 무엇을 보게 되는지 보여줌
• Simon Willison's How coding agents work blog: 코딩 에이전트가 harness로서 어떻게 작동하는지에 대한 블로그
• AI Engineer talks like Harnesses in AI: A Deep Dive: harness란 무엇이며 어떻게 구축하는가
• The Ultimate Guide to RL Environments: 프레임워크별 비교 및 어휘 번역
• Continually improving our agent harness: Cursor가 제품으로서 harness를 반복 개선하는 방법
• lm-evaluation-harness: 표준적인 평가 harness

만약 정의가 부정확하다고 느껴지거나 저희가 놓친 용어를 발견하신다면, 여러분의 의견을 듣고 싶습니다.

이 포스트를 검토해 주신 Pedro Cuenca, Quentin Gallouédec, Shaun Smith, 그리고 Adithya S Kolavi 님께 감사드립니다.