본문
AI 에이전트를 안전하게 운영하는 기술, 하네스 엔지니어링 (Harness Engineering)
헉쉬,, "AI한테 그냥 시키면 되는 거 아닌가요~?🤔" 라고 생각하신 적 있으신가요?
맞는 말이기도 하지만, 실제로 AI 에이전트를 서비스에 붙여보면 생각보다 많은 것들을 제어해야 합니다. 원하지 않는 입력이 들어오거나, 모델이 엉뚱한 답변을 내놓거나, 에이전트가 허용 범위를 벗어난 행동을 하는 상황들이 생기거든요.
이번 글에서는 AI 에이전트를 안전하고 신뢰성 있게 운영하기 위한 설계 개념인 하네스 엔지니어링(Harness Engineering) 을 소개하고, 직접 만든 샘플 프로젝트를 통해 어떻게 구현할 수 있는지 살펴보겠습니다 🥸
하네스 엔지니어링이 뭔가요?
하네스(Harness) 라는 단어는 원래 자동차의 와이어 하네스(Wire Harness) 에서 왔습니다. 자동차 내부의 수많은 전선을 하나의 묶음으로 정리해서, 신호가 정해진 경로로만 흐르도록 제어하는 부품이에요.
AI/LLM 맥락에서 하네스 엔지니어링도 같은 개념입니다. AI 모델이나 에이전트 시스템을 감싸는 외부 제어 구조를 설계해서, 입력과 출력, 그리고 실행 흐름 전체를 안전하게 관리하는 것이죠.
한 줄 요약: "AI가 마음대로 못 놀게 울타리 치고, 그 안에서 잘 노는지 측정하는 구조 전체"
하네스의 세 가지 역할
하네스는 크게 입력 제어 / 출력 제어 / 실행 제어 세 레이어로 구성됩니다.
식당에 비유하면 이렇게 이해할 수 있어요:
1) 입력 제어: 문지기 역할
손님이 주문을 넣기 전에 "이상한 주문은 아닌지", "개인정보가 포함되진 않았는지" 먼저 확인합니다. AI한테 전달되기 전에 나쁜 내용이나 불필요한 정보를 미리 걸러내는 거예요.
2) 출력 제어: 서빙 전 검수 역할
음식이 나오기 전에 "제대로 만들어졌는지", "주문한 것과 맞는지" 확인하는 단계예요. AI가 답변을 내놓았을 때 "엉뚱한 말은 아닌지", "형식에 맞는지" 한 번 더 체크합니다.
3) 실행 제어: 주방 규칙 역할
요리사가 메뉴판에 있는 음식만 만들 수 있듯이, AI 에이전트도 허용된 작업만 수행하도록 범위를 제한합니다. "이 AI는 조회만 할 수 있고, 삭제는 할 수 없어" 같은 규칙이 여기에 해당해요.
흐름으로 보면 요렇게~
[ 사용자 입력 ]
↓
[ 🚪 입력 제어 ] ← "이상한 내용은 없나요?"
↓
[ AI 에이전트 ]
↓
[ 📋 출력 제어 ] ← "답변이 올바른가요?"
↓
[ 사용자 응답 ]
실습
이론은 이 정도로 하고, 샘플 프로젝트로 넘어가 볼게요 🙂
샘플 프로젝트: Self-Routing Multi-Agent System
GitHub: https://github.com/i-am-shuan/my-skill-agent
이 프로젝트는 SKILL.md 파일 하나만 추가하면 새 에이전트가 자동으로 활성화되는 멀티 에이전트 시스템입니다. 하네스 엔지니어링의 핵심 개념인 "실행 제어"를 SKILL.md 기반으로 구현했어요.
사용자: "이 코드 좀 봐줘"
↓
[Orchestrator Agent] — skills/ 디렉토리 스캔 → "code-review" 선택
↓
[Executor Agent] — code-review/SKILL.md를 system prompt로 주입 → 리뷰 생성
↓
사용자: 🔍 코드 리뷰 결과 수신
빠른 시작
git clone https://github.com/i-am-shuan/my-skill-agent.git
cd my-skill-agent
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
export ANTHROPIC_API_KEY="sk-ant-..."
python main.py
실행하면 대화형 CLI가 뜨고, 자연어로 요청하면 됩니다:
💬 입력 > 이 글 요약해줘: 인공지능은 컴퓨터 과학의 한 분야로...
🤖 선택된 스킬: [summarize]
──────────────────────────────────────────────────
📋 요약
- 인공지능은 컴퓨터 과학의 핵심 분야로 기계 학습을 포함
- 딥러닝 기술 발전으로 자연어 처리 및 이미지 인식이 비약적으로 향상
- 의료, 금융, 제조 등 다양한 산업 분야에서 실용적으로 활용 중
💡 한 줄 결론: AI는 특정 분야를 넘어 전 산업의 핵심 인프라로 자리잡고 있다.
──────────────────────────────────────────────────
아키텍처
1. 기본 흐름 (SKILL.md 기반 라우팅)
아래는 사용자가 "이 코드 리뷰해줘"라고 입력했을 때의 전체 흐름입니다.
사용자 입력 ("이 코드 리뷰해줘")
↓
load_skills()
└─ skills/**/SKILL.md 자동 탐색 및 로드
└─ summarize / translate / code-review 스킬 인식
↓
Orchestrator Agent [1st API call]
└─ 스킬 목록 + 사용자 입력 → Claude API
└─ 최적 스킬 결정: "code-review"
↓
선택된 스킬: code-review (SKILL.md 내용 추출)
↓
Executor Agent [2nd API call]
└─ SKILL.md → system prompt 주입
└─ 사용자 입력 → user message
└─ Claude API 호출 → 결과 생성
↓
결과 반환 { selected_skill, result }
Orchestrator와 Executor를 두 개의 독립된 Agent로 분리한 것이 핵심입니다.
- Orchestrator: "무엇을 할지"만 결정 (라우팅 전용, 1st API)
- Executor: "실제로 수행" (SKILL.md 기반 실행, 2nd API)
이렇게 분리하면 각 단계에서 독립적인 검증과 제어, 즉 하네스가 가능해집니다 😎
2. 외부 데이터소스 연결 (MCP 확장) - 확장 개념
DB와 같은 데이터소스가 필요할 때는 MCP(Model Context Protocol) 레이어를 추가할 수 있어요
💡 DB 자격증명은 MCP 서버 내부 .env에서만 관리됩니다. Agent 레이어에는 노출되지 않아요. 이것 자체가 하네스 엔지니어링의 입력 제어 원칙 적용이에요
3. 전체 메시지 시퀀스 (10단계) - 확장 개념
① 사용자 → Orchestrator 자연어 요청
② Orchestrator 1st API call (라우팅: 스킬+도구 결정)
③ Orchestrator → Executor 스킬+도구 결정 전달
④ Executor 2nd API call (SKILL.md → system prompt 주입)
⑤ Executor → MCP dispatcher tool_use 블록 전달
⑥ dispatcher → MCP server tools/call (JSON-RPC)
⑦ MCP server → DB SQL / DSL 실행
⑧ DB → MCP server tool_result (rows) 반환
⑨ MCP server → Executor 결과 컨텍스트 주입
⑩ Executor → 사용자 자연어 최종 응답
LLM API는 총 두 번 호출됩니다. 1st call은 라우팅 전용이라 max_tokens=50으로도 충분하고, 2nd call에서 SKILL.md가 system prompt로 주입되어 실제 작업이 수행되어요.
👉 참고: 추가 결제 없는 Anthropic API 연동: Claude Pro 구독으로 API Key 발급하기
SKILL.md
SKILL.md는 에이전트가 어떤 상황에서, 어떤 방식으로 동작해야 하는지를 마크다운으로 정의한 파일입니다. 코드가 아닌 파일이기 때문에, 개발자가 아닌 사람도 에이전트의 동작 범위를 조절할 수 있어요.
# code-review / SKILL.md
## Purpose
코드를 분석하여 버그, 보안 취약점, 코드 품질을 리뷰합니다.
## Trigger
- "코드 리뷰", "버그", "개선점"
- 코드 블록이 포함된 입력과 함께 피드백을 요청하는 경우
## Instructions
1. 코드 전체를 읽고 언어와 목적을 파악한다
2. 버그, 보안, 성능, 가독성 순서로 검토한다
3. 심각도를 🔴 Critical / 🟡 Warning / 🟢 Suggestion으로 분류한다
## Output Format
🔍 코드 리뷰 결과
...
새 에이전트를 추가하는 방법은 딱 두 단계입니다. 폴더를 만들고, 그 안에 SKILL.md를 작성하는 것이 전부예요.
별도의 코드 수정이나 에이전트 등록 작업이 필요 없고, load_skills()가 실행될 때 자동으로 새 스킬을 탐색해서 Orchestrator에 반영합니다.
# Step 1. 스킬 폴더 생성
mkdir skills/sentiment-analysis
# Step 2. SKILL.md 작성 (Purpose / Trigger / Instructions / Output Format)
cat > skills/sentiment-analysis/SKILL.md << 'EOF'
# Sentiment Analysis Skill
## Purpose
텍스트의 감정(긍정/부정/중립)을 분석합니다.
## Trigger
- "감정 분석", "sentiment", "긍정인지 부정인지"
## Instructions
1. 텍스트 전체의 어조와 단어를 분석한다
2. 긍정/부정/중립 비율을 계산한다
3. 핵심 감정 키워드를 추출한다
## Output Format
😊 감정 분석 결과
- 전체 감정: [긍정 / 부정 / 중립]
- 핵심 키워드: [키워드1, 키워드2]
EOF
이 두 단계만 완료하면, 다음 실행부터 바로 사용할 수 있습니다:
python main.py "이 리뷰 감정 분석해줘: 정말 별로였어요..."
# 🤖 선택된 스킬: [sentiment-analysis]
💡오케스트레이터 코드는 단 한 줄도 수정하지 않아도 되어요. SKILL.md의 Trigger 섹션이 곧 라우팅 기준이 되기 때문에, 트리거 키워드를 구체적으로 작성할수록 Orchestrator의 선택 정확도가 높아집니다.
마치며
하네스 엔지니어링은 'AI를 얼마나 자유롭게 두느냐'가 아니라, '얼마나 안전한 울타리를 제공하느냐'의 문제입니다.
AI 에이전트를 실제 서비스에 투입하는 순간, "입력은 안전한가?", "출력은 정확한가?", "권한은 적절한가?"라는 현실적인 고민에 직면하게 됩니다. 이번에 살펴본 SKILL.md 기반의 구조는 복잡한 코드 수정 없이도 AI의 행동 방침을 정의하고 제어할 수 있는 가장 직관적인 '하네스'의 구현체라고 할 수 있어요.
AI가 제멋대로 튀지 않으면서도 제 실력을 발휘할 수 있도록 돕는 견고한 설계, 그것이 신뢰받는 AI 서비스를 만드는 첫걸음이 아닐까요?
꽤 매력적인 작업이죠? 🙂
댓글