Overview
우리는 흔히 AI에게 “이거 해줘"라고 말하면 다 될 것이라 생각합니다. 하지만 실제 프로젝트 현장에서 AI 에이전트는 엉뚱한 파일을 수정하거나, 보안상 위험한 명령을 실행하는 등 소위 ‘실행의 오류’를 범하곤 합니다. 이런 현상은 모델이 멍청해서가 아니라, 에이전트가 일할 수 있는 **‘틀’**이 제대로 갖춰지지 않았기 때문에 발생합니다.
본 가이드는 유튜브 강의 **[Harness Engineering: 안티그래비티에 앤트로픽 클로드 스킬 적용하기]**의 핵심 내용을 바탕으로, 안티그래비티 환경에서 **하니스 엔지니어링(Harness Engineering)**을 통해 에이전트를 어떻게 설계하고 통제하는지 상세히 안내합니다. 야생마에게 마구(Harness)를 채워 길들이듯, 에이전트의 힘을 목적에 맞게 집중시키는 기술을 배워보겠습니다.
Background / Problem: 왜 하니스 엔지니어링이 필요한가?
1. 야생마를 길들이는 ‘마구(Harness)‘의 지혜
‘하니스(Harness)‘의 원뜻은 말이나 동물에게 씌우는 마구입니다. 단순히 동물을 묶어두는 것이 목적이 아니라, 동물의 강력한 힘이 제멋대로 흩어지지 않고 원하는 방향으로 움직여 수레를 끌게 만드는 제어 장치입니다.
2. 프롬프트만으로는 부족한 이유
모델에게 아무리 좋은 프롬프트를 주어도 아래와 같은 한계에 부딪힙니다.
- 통제 불능: 에이전트가 어떤 문서를 참고해야 할지, 어디까지 수정해도 될지 알 수 없습니다.
- 일관성 부재: 매 세션마다 가이드라인을 다시 가르쳐야 하며, 이는 곧 토큰 비용의 급증으로 이어집니다.
- 검증 실패: 결과물이 테스트를 통과했는지 확인하지 않고 다음 단계로 넘어가 시스템을 망가뜨릴 수 있습니다.
따라서 하니스 엔지니어링은 AI를 단순히 똑똑한 존재로 보는 것이 아니라, 제대로 일하도록 제어 장치와 작업 환경을 설계하는 일이라고 정의할 수 있습니다.
Solution / Implementation: 안티그래비티 하니스의 구성 요소와 워크플로우
안티그래비티는 **에이전트 매니저(Agent Manager)**와 에디터/브라우저가 통합된 환경에서 다음의 4가지 핵심 요소를 통해 하니스를 구축합니다.
1. 하니스 핵심 구성 요소 (Core Components)
| 구성 요소 | 역할 | 상세 내용 |
|---|---|---|
| Rules (규칙) | 법전 및 헌법 | gemini.md나 .agents/rules/에 저장되어 항상 지켜야 할 원칙 정의 |
| Skills (스킬) | 전문 기술 패키지 | skill.md를 통해 데이터 분석, 웹 작성 등 전문 노하우를 모듈화 |
| MCP | 외부 도구 연결 | DB, GitHub, 외부 API를 에이전트와 물리적으로 연결하는 장치 |
| Workflows | 자동화 명령 | 슬래시(/) 명령어로 호출되는 고정된 작업 절차 (예: 주간 리포트 생성) |
2. 프로그레시브 디스클로저(Progressive Disclosure) 기술
안티그래비티 하니스의 가장 큰 기술적 강점은 토큰을 아끼는 지능형 로딩에 있습니다.
- 단계적 노출: 스킬의 전체 내용을 처음부터 다 읽지 않고,
YAML Front-matter에 적힌description만 먼저 스캔합니다. - 필요 시 로딩: 작업 맥락에 따라 해당 스크립트가 정말 필요할 때만 전체 컨텍스트를 메모리에 로드하여 지연 시간을 최소화하고 비용을 최대 90% 절감합니다.
3. 하니스 실행 단계 (Execution Flow)
에이전트 세션이 시작되면 아래와 같은 순서로 하니스가 작동합니다.
- 룰 로드: 시스템 룰(글로벌) → 워크스페이스 룰(로컬) 순으로 불러옵니다.
- 스킬 식별: 현재 작업에 필요한 스킬의
description을 매칭합니다. - MCP 연결: 깃허브나 DB 등 필요한 외부 도구의 승인 절차를 거칩니다.
- 아티팩트 생성: 위 과정이 끝나면 에이전트가 종합하여 **임플리멘테이션 플랜(Plan)**과 **태스크(Task)**를 생성합니다.
심화: 문제 해결 및 주의사항 (Troubleshooting)
작업 도중 에이전트가 말을 듣지 않거나 설정이 꼬였을 때의 해결 방법입니다.
⚠️ 필수 체크리스트 (Common Mistakes)
| 오류 상황 | 원인 | 해결 방법 |
|---|---|---|
| 스킬이 활성화되지 않음 | 폴더명 단수형 사용 | 반드시 .agents/ (복수형 s) 폴더인지 확인 |
| 글로벌 룰이 적용 안 됨 | 경로 탐색 오류 | 점재미나이(.gemini) 글로벌 경로가 올바른지 체크 |
| MCP 연결 실패 | 인증/토큰 이슈 | 패키지 매니저(npx/mpx) 사용 및 API 키 값 재설정 |
심화: 스킬과 MCP의 효율적 활용 (Advanced Techniques)
1. 가성비 중심의 모델 운용
- 혼합 사용: 메인 작업은
Claude 3.7 Sonnet이나Gemini 2.0 Pro로, 단순 작업은Flash모델이나제미나이 CLI를 활용하여 비용 효율을 극대화하세요. - 인라인 룰(Inline Rule): 에이전트가 지침을 까먹었을 때 채팅창에 직접 “한국어로 답변해줘"라고 입력하면 즉시 기억이 보정됩니다.
2. 스킬 크리에이터 활용
- 직접 스킬을 짜기 어렵다면, 기존의 워크플로우를 에이전트에게 전달하며 **“이를 스킬로 변환해줘”**라고 요청하세요. 프로페셔널한 영어 스킬로 자동 변환되어 성능이 더 좋아집니다.
FAQ: 궁금해할 만한 질문들 (Frequently Asked Questions)
Q1. 스킬은 많을수록 좋은가요?
아닙니다. 너무 많은 스킬이 로드되면 에이전트가 불필요한 정보 과부하로 인해 오히려 멍청해질 수 있습니다. 내 업무에 꼭 필요한 스킬만 선별하여 등록하는 것이 중요합니다.
Q2. 글로벌 룰과 로컬 룰이 충돌하면 어떻게 되나요?
기본적으로 안티그래비티는 두 룰을 모두 합쳐서 참조하지만, 특정 상황에서는 로컬 워크스페이스의 룰이 현재 작업 맥락에 더 가깝게 작용하도록 설계되었습니다.
Key Takeaways
- Harness defined: 하니스는 단순한 속박이 아니라 힘을 목적지로 이끄는 제어 환경입니다.
- Structure: 룰(Rule), 스킬(Skill), MCP, 워크플로우의 4단 계층을 이해하고 설계하세요.
- Token Strategy: 프로그레시브 디스클로저를 활용해 토큰 효율을 극대화하세요.
- Maintenance: 에이전트의 실수(Gachas)를 스킬 문서에 기록하여 지속적인 통제력을 확보하세요.
References
마치며
하니스 엔지니어링은 AI 모델을 똑똑하게 만드는 일이 아니라, AI가 똑똑하게 일할 수밖에 없는 ‘구조’를 만드는 일입니다. 모델의 성능에만 의존하기보다, 여러분의 워크스페이스에 최적화된 하니스를 구축해보세요. 야생마 같던 AI가 어느덧 여러분의 가장 든든한 날개가 되어 있을 것입니다.