# 하네스란

에이전트가 지속적으로 올바른 작업을 수행하도록 돕는 하네스의 기본 개념을 소개합니다.

원본 URL: https://abc.noco.kr/harness-basics/overview

> 삽화: 안전한 작업 격리 환경에서 가벼운 과제를 실행하고 테스트로 검증하는 첫 실습

[하네스](/glossary#harness)는 [에이전트](/glossary#agent)가 작업하는 환경 전체다. 모델이 무엇을 읽고, 무엇을 실행할 수 있고, 결과를 어떻게 검증할지 정하는 주변 장치를 묶은 것이다. 같은 모델이라도 어떤 하네스를 붙이느냐에 따라 작업 결과가 달라진다.

## 하네스의 정의

하네스는 다음을 결정하는 환경이다.

- 어떤 [컨텍스트](/glossary#context)를 언제 제공할 것인가.
- 어떤 프롬프트와 함께 전달할 것인가.
- 어떤 도구를 실행할 수 있게 할 것인가.
- 무엇을 금지하고 어떤 권한을 줄 것인가.
- 결과를 어떤 기준으로 검증할 것인가.

모델은 기본 능력이고, 하네스는 그 능력을 작업에 맞게 쓰게 하는 장치다. 프롬프트 한 줄을 잘 다듬는 일보다 필요한 정보와 도구와 검증을 어떻게 배치할지가 결과를 더 크게 좌우한다.

하네스가 비어 있으면 같은 설명을 계속 반복하게 된다.

- 룰이 없으면 같은 주의를 작업마다 다시 말한다.
- 스킬이 없으면 긴 절차를 매번 프롬프트에 붙여 넣는다.
- 검증이 없으면 잘못된 결과를 사람이 직접 찾아야 한다.

## 맡기고 고치는 순서

하네스를 처음부터 완벽하게 설계하려 들 필요는 없다. 과정을 전부 이해한 뒤 시작하기보다, 지금 할 수 있는 형태로 맡기고 결과를 보고 고치는 편이 빠르다.

- 맡길 작업을 정해 런타임에 그대로 요청한다.
- 결과와 막힌 지점을 확인한다.
- 반복될 내용만 룰·스킬·문서로 남긴다.
-  모든 기능을 미리 익히려 하지 않는다. 도구가 바뀌는 속도가 배우는 속도보다 빠르므로, 필요할 때 확인해 필요한 만큼만 하네스에 반영한다.

```mermaid
flowchart LR
  A[작업 맡기기] --> B[결과 검토]
  B --> C[반복되는 문제 찾기]
  C --> D[룰·스킬·문서·테스트에 반영]
  D --> A
```

같은 지적이 두 번 나오면 문장 하나를 만들어 하네스에 넣는다. 예를 들어 ‘빌드 없이 커밋하지 않는다’는 룰 한 줄로, ‘릴리스 배포 절차’처럼 긴 순서는 스킬 하나로 만든다. 다음 작업부터는 같은 설명을 반복하지 않아도 된다.

런타임에게 하네스 초안 자체를 맡길 수도 있다. 예를 들어 프로젝트 폴더에서 이렇게 요청한다.

```text
이 저장소의 빌드·테스트·커밋 절차를 정리해 AGENTS.md 초안을 만들어 줘.
지금 확인한 내용만 적고, 확실하지 않은 항목은 '확인 필요'로 표시해.
```

초안은 그대로 쓰지 않고 검토한다. 확인되지 않은 내용이 사실처럼 남는 것을 막는 절차다.

## 하네스를 이루는 요소

| 요소 | 하는 일 | 자세히 |
| --- | --- | --- |
| 룰 | 매 작업에 항상 적용되는 짧은 규칙 | [룰](/harness-basics/rules) |
| 스킬 | 필요할 때만 읽는 절차 문서 | [스킬](/harness-basics/skills) |
| 문서 | 요구사항·설계·결정 기록 | [문서](/harness-basics/docs) |
| 메모리 | 세션 사이에 남는 개인 기억 | [메모리](/harness-basics/memory) |
| 권한·샌드박스 | 실행 범위와 승인 경계 | [보안](/harness-basics/security), [세팅](/harness-basics/settings) |
| 훅 | 이벤트 시점의 자동 실행 | [훅](/harness-advanced/hooks) |
| MCP | 외부 서비스를 도구로 연결 | [MCP](/harness-advanced/mcp) |
| 서브에이전트 | 작업을 나눠 맡기는 보조 에이전트 | [서브에이전트](/harness-advanced/subagents) |
| 검증 | 테스트·빌드·린트로 결과 확인 | [검증](/harness-advanced/verification) |

모두 처음부터 갖출 필요는 없다. 반복되는 문제가 생길 때마다 해당 요소를 하나씩 추가한다.

| 반복되는 문제 | 먼저 손볼 요소 |
| --- | --- |
| 같은 실수를 매번 다시 지적한다 | 룰 |
| 매번 같은 절차를 길게 설명한다 | 스킬 |
| 결정 이유가 사라져 다시 논의한다 | 문서 |
| 깨진 결과가 뒤늦게 발견된다 | 검증 |

요소를 늘리는 것 자체가 목적은 아니다. 문제가 줄어드는지로 효과를 확인한다.

## 시작 순서

세팅을 먼저 하고, 룰과 검증으로 기본을 잡은 뒤 스킬과 문서를 더한다.

1. [세팅](/harness-basics/settings): 권한 범위를 좁히고 화면을 정리한다. 사고를 막는 안전장치가 먼저다.
2. [룰](/harness-basics/rules): 커밋·배포·금지 사항처럼 매번 적용할 것만 짧게 적는다.
3. [검증](/harness-advanced/verification): 타입 오류처럼 테스트로 잡을 수 있는 것은 자동 확인에 맡긴다.
4. [스킬](/harness-basics/skills): 룰에 넣기엔 긴 절차를 분리한다.
5. [문서](/harness-basics/docs): 결정과 과정을 기록해 다음 작업이 읽을 양을 줄인다.

이후에는 필요할 때 [훅](/harness-advanced/hooks), [MCP](/harness-advanced/mcp), [서브에이전트](/harness-advanced/subagents), [Effort](/harness-advanced/effort) 같은 심화 요소를 더한다. 작업 순서와 분할은 [herdr 오케스트레이션](/practice/herdr)에서 다룬다.

## 프롬프트보다 환경 구성

프롬프트와 컨텍스트가 없어진 것은 아니다. 매번 사람이 요청 문장을 미세하게 조정하기보다, 룰·스킬·문서·테스트로 필요한 정보를 구조화해 관리하는 비중이 커졌다는 뜻이다. 프롬프트·컨텍스트·모델의 구분은 [컨텍스트와 프롬프트](/concepts/context-prompt)에서 다룬다.

::: details 보충: 에이전트 프레임워크를 직접 쓰는 경우
LangChain, LangGraph, Pydantic AI, Spring AI 같은 프레임워크로 에이전트를 직접 만들 수도 있다. 이미 있는 코딩 에이전트에 일을 맡기는 경우에는 거의 필요하지 않다. 다만 앱 안에서 RAG, 컨텍스트 관리, 프롬프트 템플릿을 다룰 때는 이런 도구가 여전히 유용하다. [RAG](/glossary#rag)는 검색으로 찾은 자료를 컨텍스트에 넣는 방식이다.
:::