AI Agent Engineering · 2026

하네스 엔지니어링 완벽 가이드
모델이 아니라 '환경'이 성능을 결정한다

2026년 AI 에이전트 시대의 새로운 핵심 역량, 하네스 엔지니어링(Harness Engineering)을 정의부터 실전 예제까지 한 글로 정리합니다.

Agent = Model + Harness

에이전트는 모델과, 모델을 감싸는 환경의 합이다

1. 하네스 엔지니어링이란?

"하네스(Harness)"는 원래 말에 채우는 마구(馬具)를 뜻하는 단어입니다. 천 마력짜리 명마가 있어도 고삐와 안장이 없으면 원하는 방향으로 달리게 할 수 없죠. AI 에이전트도 마찬가지입니다. Claude든 GPT든 모델 자체는 이미 충분히 강력합니다. 문제는 그 힘을 어떻게 일관되고 안전하게 쓰느냐입니다.

하네스 엔지니어링이란, AI 에이전트가 복잡하고 긴 작업을 안정적으로 수행할 수 있도록 모델을 감싸는 환경 전체 — 규칙, 도구, 메모리, 피드백 루프 — 를 설계하는 방법론이다.

저장소 구조, CI 설정, 린터, 프로젝트 지침 문서, 외부 도구 연결까지 — 모델 바깥에서 동작하는 시스템 전체가 하네스입니다.

용어의 등장 배경

2026년 2월, HashiCorp 공동 창업자 미첼 하시모토가 블로그에서 "Engineer the Harness"라는 표현을 처음 사용
며칠 뒤 OpenAI가 공식 아티클로 개념을 정리하며 용어가 확산
이후 Martin Fowler가 패턴 언어로 체계화했고, Anthropic, Stripe, LangChain 등이 연이어 다루면서 업계 표준 어휘로 자리 잡음

2. 프롬프트·컨텍스트 엔지니어링과 뭐가 다른가?

구분	핵심 질문	초점
프롬프트 엔지니어링	"무엇을 물어볼까?"	한 번의 입력을 잘 쓰는 기술
컨텍스트 엔지니어링	"무엇을 보여줄까?"	모델에게 어떤 정보를 넣을지 관리
하네스 엔지니어링	"바깥의 시스템 전체를 어떻게 설계할까?"	구조, 제약, 피드백 루프, 운영 체계

프롬프트가 "질문 한 줄"이라면, 하네스는 에이전트가 올바르게 행동할 수밖에 없는 외부 환경을 만드는 일입니다. 좋은 셰프를 뽑는 것보다, 그 셰프가 매일 안정적으로 요리를 낼 수 있는 주방 운영 체계를 만드는 것에 가깝습니다.

3. 하네스의 핵심 구성 요소

① 컨텍스트 문서 (CLAUDE.md / AGENTS.md)

에이전트에게 건네는 온보딩 문서입니다. 신입 팀원에게 "우리 프로젝트는 이렇게 굴러갑니다"라고 알려주듯, 프로젝트 구조·컨벤션·금지 사항을 명시합니다.

② Rules (규칙)

"어떻게 해야 하는가"를 안내하는 행동 규칙입니다. 권한 설정(settings.json)이 무엇을 할 수 있는가를 통제한다면, Rules는 어떻게 해야 하는가를 안내합니다. 둘은 상호 보완적입니다.

③ Skills (스킬)

반복 작업의 노하우를 문서화해, 에이전트가 매번 처음부터 시행착오를 겪지 않게 하는 지식 축적 장치입니다.

④ 도구와 권한 (Tools & Permissions)

에이전트가 사용할 수 있는 도구(MCP, CLI, API)와 그 권한 범위를 정의합니다.

⑤ 피드백 루프 (Feedback Loop)

Martin Fowler는 피드백 루프를 두 가지로 분류했습니다.

가이드(Guide) — 작업 중에 방향을 잡게 하는 것: 린터, 타입 체커, 포맷터
센서(Sensor) — 작업 결과를 검증하는 것: 테스트, CI, 빌드 검사

코드 작성→ 린터가 즉시 지적→ 테스트가 검증→ 스스로 수정↺

이 순환이 하네스의 심장입니다.

4. 실전 예제 5가지

예제 1 · CLAUDE.md — 프로젝트 온보딩 문서

쿠팡 파트너스 링크로 홍보 스크립트를 생성하는 Streamlit 사이드 프로젝트를 가정한 예시입니다.

CLAUDE.md

# CLAUDE.md

## 프로젝트 개요
쿠팡 파트너스 링크를 입력받아 플랫폼별 홍보 스크립트를
자동 생성하는 Streamlit 앱.

## 아키텍처
- main.py   : Streamlit UI 레이어 (UI 로직만)
- brain.py  : Anthropic API 호출 및 프롬프트 로직
- UI와 로직을 절대 한 파일에 섞지 말 것

## 컨벤션
- Python 3.11, 타입 힌트 필수
- API 키는 반드시 .env 에서만 로드 (하드코딩 금지)
- 함수는 30줄 이내, 초과 시 분리

## 실행/검증 명령
- 실행: streamlit run main.py
- 린트: ruff check .
- 테스트: pytest tests/

## 금지 사항
- requirements.txt 임의 변경 금지 (변경 필요 시 먼저 보고)
- .env, secrets 관련 파일 절대 커밋 금지

이 문서 하나만 있어도 에이전트가 "어디에 어떤 코드를 넣어야 하는지" 매번 물어보거나 제멋대로 판단하는 일이 크게 줄어듭니다.

예제 2 · 권한 설정 — 무엇을 할 수 있는가

.claude/settings.json

{
  "permissions": {
    "allow": [
      "Bash(ruff check:*)",
      "Bash(pytest:*)",
      "Bash(git diff:*)",
      "Read(**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push:*)",
      "Read(.env)",
      "Write(.env)"
    ]
  }
}

린트와 테스트는 자유롭게 돌리되, 강제 삭제·푸시·시크릿 접근은 원천 차단합니다. 하네스는 속도를 늦추는 "브레이크"가 아니라, 사고 없이 완주하게 돕는 안전벨트입니다.

예제 3 · Rules — 어떻게 해야 하는가

rules/git-workflow.md

1. 작업 시작 전 반드시 새 브랜치를 생성한다 (feature/작업명)
2. 커밋 메시지는 Conventional Commits 형식을 따른다
   - feat: / fix: / refactor: / docs:
3. 커밋 전 반드시 ruff check 와 pytest 를 실행하고,
   실패하면 커밋하지 않고 원인을 먼저 고친다
4. 한 커밋에는 하나의 논리적 변경만 담는다

예제 4 · Skill — 반복 노하우의 문서화

skills/streamlit-deploy/SKILL.md

## 목적
Streamlit 앱을 배포 가능한 상태로 점검하는 절차

## 절차
1. requirements.txt 에 누락된 패키지가 없는지
   pip freeze 결과와 대조
2. st.secrets 사용 여부 확인 — 로컬 .env 코드가
   남아있으면 secrets.toml 방식으로 전환
3. 세션 스테이트 초기화가 조건문으로 감싸져 있는지 확인
   (if "key" not in st.session_state)
4. 위 항목 통과 후 배포 체크리스트를 출력하고 종료

배포 때마다 겪던 시행착오를 한 번 문서화해두면, 에이전트는 다음부터 같은 실수를 반복하지 않습니다.

예제 5 · 피드백 루프 — 스스로 고치게 만들기

.github/workflows/ci.yml

name: CI
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install -r requirements.txt
      - run: ruff check .        # 가이드: 스타일 즉시 검증
      - run: pytest tests/ -v    # 센서: 동작 결과 검증

에이전트가 만든 PR이 CI에서 실패하면, 그 실패 로그 자체가 다음 프롬프트가 됩니다. "고쳐줘"라고 사람이 말하기 전에 시스템이 먼저 말하게 만드는 것 — 이것이 하네스의 완성형입니다.

5. 왜 지금 중요한가?

모델의 상향 평준화 — 어떤 모델을 쓰든, 성능 차이보다 하네스 설계 차이가 결과물 품질을 더 크게 가릅니다.
작업의 장기화 — 에이전트가 몇 시간짜리 작업을 수행하는 시대에는 사람이 일일이 감독할 수 없으므로, 구조와 피드백 루프가 감독을 대신해야 합니다.
스케일 확장 — 공통 하네스가 있으면 에이전트를 여러 개로 늘리거나 서비스 규모를 키워도 동일한 안전 기준이 유지됩니다.

에이전트 시대의 경쟁력은 더 똑똑한 모델이 아니라, 더 나은 하네스에서 나온다.

6. 오늘 시작하는 법 (비개발자도 가능)

하네스의 원리는 코딩 없이도 적용할 수 있습니다.

작업 지침 문서 하나 만들기 — 프로젝트 루트에 CLAUDE.md(또는 AGENTS.md)를 만들어 규칙 5줄만 적어보기
검증 체크리스트 만들기 — 결과물을 받았을 때 확인할 항목을 목록화
작업 이력 기록하기 — 잘된 방식과 실패한 방식을 남겨서 다음 작업의 Skill로 축적
권한의 경계 긋기 — "절대 하면 안 되는 일" 목록부터 정의

이 네 가지가 곧 하네스의 축소판입니다. 프롬프트 한 줄을 다듬는 시간에, 에이전트가 일하는 환경을 다듬어 보세요.

저작자표시 비영리 변경금지 (새창열림)

'AI_공부' 카테고리의 다른 글

루프 엔지니어링 완벽 가이드 (0)	2026.07.06
GitHub Copilot vs Codex vs Claude Code 비교 (0)	2026.06.22
[Claude] 클로드 스킬 완전정복 7편 : 클로드 스킬, 나만의 업무에 이렇게 쓴다 — 총정리 (1)	2026.06.18
[Claude] 클로드 스킬 완전정복 6편 : UI 디자인도 클로드랑? — 프론트엔드 스킬 체험기 \| (0)	2026.06.18
[Claude] 클로드 스킬 완전정복 5편 : 인스타 경쟁 계정, 클로드가 분석해드립니다 (0)	2026.06.18

NextGen AI

하네스 엔지니어링 완벽 가이드 — Agent = Model + Harness

하네스 엔지니어링 완벽 가이드
모델이 아니라 '환경'이 성능을 결정한다

1. 하네스 엔지니어링이란?

용어의 등장 배경

2. 프롬프트·컨텍스트 엔지니어링과 뭐가 다른가?

3. 하네스의 핵심 구성 요소

① 컨텍스트 문서 (CLAUDE.md / AGENTS.md)

② Rules (규칙)

③ Skills (스킬)

④ 도구와 권한 (Tools & Permissions)

⑤ 피드백 루프 (Feedback Loop)

4. 실전 예제 5가지

예제 1 · CLAUDE.md — 프로젝트 온보딩 문서

예제 2 · 권한 설정 — 무엇을 할 수 있는가

예제 3 · Rules — 어떻게 해야 하는가

예제 4 · Skill — 반복 노하우의 문서화

예제 5 · 피드백 루프 — 스스로 고치게 만들기

5. 왜 지금 중요한가?

6. 오늘 시작하는 법 (비개발자도 가능)

'AI_공부' 카테고리의 다른 글

티스토리툴바

하네스 엔지니어링 완벽 가이드 — Agent = Model + Harness

1. 하네스 엔지니어링이란?

용어의 등장 배경

2. 프롬프트·컨텍스트 엔지니어링과 뭐가 다른가?

3. 하네스의 핵심 구성 요소

① 컨텍스트 문서 (CLAUDE.md / AGENTS.md)

② Rules (규칙)

③ Skills (스킬)

④ 도구와 권한 (Tools & Permissions)

⑤ 피드백 루프 (Feedback Loop)

4. 실전 예제 5가지

예제 1 · CLAUDE.md — 프로젝트 온보딩 문서

예제 2 · 권한 설정 — 무엇을 할 수 있는가

예제 3 · Rules — 어떻게 해야 하는가

예제 4 · Skill — 반복 노하우의 문서화

예제 5 · 피드백 루프 — 스스로 고치게 만들기

5. 왜 지금 중요한가?

6. 오늘 시작하는 법 (비개발자도 가능)

'AI_공부' 카테고리의 다른 글

관련글

티스토리툴바