예전에는 한 사람이 옷을 디자인하고, 만들고, 파는 것까지 전부 혼자 했습니다. 그런데 산업혁명이 일어나면서 역할이 나뉘었습니다. 디자인하는 사람, 만드는 사람, 파는 사람. 각자 자기 일만 전문적으로 하니까 품질도 올라가고 속도도 빨라졌습니다.
2026년, AI 에이전트 세계에서 똑같은 일이 벌어지고 있습니다. 그것이 바로 하네스 엔지니어링입니다.
프롬프트 엔지니어링 시대에는 AI에게 "이것도 해줘, 저것도 해줘"라고 한 번에 모든 걸 시켰습니다. 결과는 들쑥날쑥했습니다. 하네스 방식은 접근이 완전히 다릅니다. AI 에이전트가 일하는 환경 자체를 설계합니다. 무엇을 해야 하는지, 어디까지 할 수 있는지, 어떤 순서로 진행해야 하는지를 미리 정해두는 것입니다.
저는 지난 3개월간 직접 13개의 AI 에이전트를 만들고 운영하면서 이 방법론을 실전에 적용했습니다. 이론이 아니라 실제 경험을 바탕으로, 이것이 무엇이고 어떻게 시작할 수 있는지 정리했습니다.
하네스(Harness)는 원래 말을 제어하는 마구를 뜻합니다. 하네스 엔지니어링은 AI 에이전트라는 강력한 말에 고삐를 채워서, 원하는 방향으로 정확하게 달리게 만드는 기술입니다.
프롬프트 엔지니어링이 "좋은 질문을 하는 기술"이었다면, 하네스 엔지니어링은 "좋은 작업 환경을 만드는 기술"입니다. 구체적으로 말씀드리면 다음과 같습니다.
| 구분 | 프롬프트 엔지니어링 | 하네스 엔지니어링 |
|---|---|---|
| 대상 | 단일 대화 | 전체 작업 시스템 |
| 방식 | 좋은 질문 작성 | 환경·규칙·흐름 설계 |
| 결과물 | 1회성 답변 | 반복 가능한 파이프라인 |
| 재사용 | 매번 다시 작성 | 한 번 만들면 계속 사용 |
| 핵심 파일 | 없음 | CLAUDE.md, 에이전트 명세 |
핵심은 재사용성입니다. 산업혁명에서 공장 시스템이 한 번 갖춰지면 제품을 계속 찍어낼 수 있었던 것처럼, 에이전트 시스템을 한 번 구축하면 새로운 작업을 만들 때마다 기존 부품을 그대로 가져다 쓸 수 있습니다.
실전에서 적용하려면 다섯 가지 요소를 이해해야 합니다.
1. CLAUDE.md (작업 지시서)
프로젝트 루트에 놓는 마스터 문서입니다. AI 에이전트가 세션을 시작할 때 가장 먼저 읽는 파일이며, 프로젝트의 규칙, 금지 사항, 작업 순서, 저장 경로 등을 모두 담고 있습니다. 사람으로 치면 신입 사원에게 건네는 업무 매뉴얼과 같습니다.
2. 단일 책임 에이전트
하나의 에이전트는 하나의 일만 합니다. 뉴스를 수집하는 에이전트, 텍스트를 요약하는 에이전트, 텔레그램으로 발송하는 에이전트를 각각 따로 만듭니다. 산업혁명의 분업과 같은 원리입니다.
3. 명시적 인터페이스
각 에이전트가 어떤 입력을 받고 어떤 출력을 내는지 명확하게 정의합니다. 디자이너가 완성한 도면을 공장에 넘기듯, 에이전트 간에 주고받는 데이터 형식이 정해져 있어야 합니다.
4. 가드레일 (안전장치)
AI가 하면 안 되는 행동을 명시합니다. 예를 들어 ".env 파일 수정 금지", "settings.json 무단 수정 금지" 같은 규칙을 CLAUDE.md에 적어두면, 에이전트가 위험한 작업을 시도하지 않습니다.
5. 오케스트레이션 (조립)
개별 에이전트들을 순서대로 연결하여 하나의 파이프라인으로 만드는 과정입니다. 공장의 컨베이어 벨트처럼, A 에이전트의 출력이 B 에이전트의 입력으로 자동 전달됩니다.
이론만으로는 감이 잡히지 않으실 것입니다. 제가 GitHub에 공개한 실전 프로젝트(https://github.com/alice840126-ship-it/harness-engineering-guide)의 구조를 직접 보여드리겠습니다.
현재 운영 중인 에이전트는 13개입니다.
| 에이전트 | 역할 | 유형 |
|---|---|---|
| TelegramSender | 텔레그램 메시지 발송 | Python |
| NewsScraper | 뉴스 기사 수집 | Python |
| NewsAnalyzer | 뉴스 분석·분류 | Python |
| Summarizer | 텍스트 요약 | Python |
| ObsidianWriter | 옵시디언 노트 저장 | Python |
| BlogWriterNaver | 네이버 블로그 글 작성 | Claude 서브에이전트 |
| BlogImage | 블로그 이미지 생성 | Claude 서브에이전트 |
| NaverAnalyzer | 네이버 SERP 분석 | Claude 서브에이전트 |
| SerpAnalyzer | 구글 검색 분석 | Claude 서브에이전트 |
| ObsidianBlogSaver | 블로그 초안 저장 | Python |
| WebDataScraper | 동적 웹 데이터 수집 | Python (Playwright) |
| HtmlShareDeployer | 외부 공유 URL 생성 | Python |
| RealestateDataCollector | 부동산 실거래 데이터 | Python |
핵심은 이 에이전트들이 각각 독립적으로 작동한다는 점입니다. TelegramSender는 메시지를 보내는 일만 하고, NewsScraper는 뉴스를 긁어오는 일만 합니다. 산업혁명 시대의 분업 그대로입니다.
그리고 새로운 기능이 필요할 때, 처음부터 다시 만들 필요가 없습니다. 기존 에이전트를 조합하면 됩니다. 이것이 이 방법론의 진짜 힘입니다.
가장 잘 드러나는 예시가 블로그 작성 파이프라인입니다. 이 글도 실제로 이 파이프라인을 통해 작성되고 있습니다.
파이프라인 흐름:
Stage 1 (병렬 실행)
├── NaverAnalyzer → 네이버 상위 노출 글 분석, 키워드 밀도·글자 수 파악
└── SerpAnalyzer → 구글 PAA 질문 수집, 연관 검색어 파악
Stage 2
└── BlogWriterNaver → 분석 결과를 받아 SEO 최적화 블로그 글 작성
Stage 3
└── BlogImage → 본문에 맞는 이미지 생성
Stage 4
└── ObsidianBlogSaver → 옵시디언 볼트에 초안 저장
이 방법론 적용 이전이라면 어땠을까요? "네이버 블로그 글 써줘"라고 프롬프트 하나를 던지고, AI가 알아서 분석하고, 글 쓰고, 저장까지 다 하길 바라야 했습니다. 결과는 매번 달랐고, 품질도 일정하지 않았습니다.
하네스 방식을 적용하면 각 단계가 분리되어 있어서, NaverAnalyzer의 분석 로직을 개선하면 그 혜택이 모든 블로그 글에 자동 적용됩니다. BlogWriterNaver의 문체 규칙을 바꾸면 이후 모든 글에 즉시 반영됩니다. 한 곳을 고치면 전체가 좋아지는 구조입니다.
그리고 Stage 1에서 NaverAnalyzer와 SerpAnalyzer가 병렬로 실행됩니다. 두 에이전트가 서로 의존하지 않기 때문에 동시에 돌릴 수 있고, 시간이 절반으로 줄어듭니다. 이것도 단일 책임 원칙으로 에이전트를 분리했기 때문에 가능한 일입니다.
네이버 DataLab 기준으로 이 키워드의 검색량은 2026년 2월 0.08에서 3월 8.9, 4월 12.35로 급상승했습니다. 불과 두 달 만에 150배 이상 늘어난 것입니다.
이유는 명확합니다.
첫째, AI 에이전트의 보편화입니다. Claude Code, OpenAI Codex, Cursor 같은 에이전틱 코딩 도구가 개발자 사이에서 일상이 되었습니다. 단순히 코드를 생성하는 수준을 넘어, AI가 파일을 읽고 쓰고 명령을 실행하는 시대가 되면서 "어떻게 제어할 것인가"가 핵심 과제로 떠올랐습니다.
둘째, 프롬프트 엔지니어링의 한계가 드러났습니다. 한 줄짜리 프롬프트로 복잡한 작업을 시키면, AI는 맥락을 잃고 삽질합니다. 긴 대화를 이어가면 초반 지시를 잊어버리기도 합니다. 하네스 엔지니어링은 이런 문제를 구조적으로 해결합니다. CLAUDE.md 같은 영구 문서에 규칙을 적어두면, 에이전트가 세션을 시작할 때마다 자동으로 읽습니다.
셋째, 재사용의 경제성입니다. 기존에는 에이전트 A를 만들 때도 뉴스 수집 + 요약 + 발송을 처음부터 구현하고, 에이전트 B를 만들 때도 뉴스 수집 + 분석 + 저장을 처음부터 구현했습니다. 각 기능을 독립 에이전트로 만들어두면, 새 파이프라인은 기존 에이전트를 조합하는 것만으로 완성됩니다. 개발 시간이 절반 이하로 줄어듭니다.
"코딩을 해야 하는 거 아닙니까?"라는 질문을 많이 받습니다. 결론부터 말씀드리면, 핵심은 코딩이 아니라 설계입니다.
CLAUDE.md를 작성하는 것은 마크다운 문서를 쓰는 것과 같습니다. 코드를 한 줄도 모르더라도 다음과 같은 규칙을 적을 수 있습니다.
**작업 규칙**
- 모든 파일은 ~/Documents/에 저장할 것
- 데이터를 추측하지 말고 출처를 반드시 밝힐 것
- 작업 완료 후 결과를 텔레그램으로 보내줄 것
이것만으로도 AI 에이전트의 행동이 크게 달라집니다. 물론 Python 에이전트를 직접 만들려면 코딩 지식이 필요하지만, Claude Code 같은 도구를 사용하면 AI가 코드를 대신 작성해주기 때문에 진입 장벽이 훨씬 낮습니다.
시작 단계를 정리하면 이렇습니다.
Q. 하네스 엔지니어링과 프롬프트 엔지니어링의 차이는 무엇입니까?
프롬프트 엔지니어링은 AI에게 보내는 메시지 하나를 잘 쓰는 기술입니다. 하네스 방식은 AI가 일하는 전체 환경을 설계하는 기술입니다. 프롬프트가 "지금 이 질문에 잘 답해줘"라면, 하네스는 "앞으로 이 프로젝트에서 이렇게 일해줘"입니다. 후자가 상위 개념이며, 프롬프트 엔지니어링을 포함합니다.
Q. 하네스 엔지니어링은 왜 2026년에 갑자기 주목받습니까?
2025년 말부터 AI 에이전트가 단순 대화를 넘어 파일 시스템 접근, 코드 실행, API 호출까지 가능해졌기 때문입니다. 능력이 커지면 제어 기술도 함께 발전해야 합니다. 자동차가 빨라지면 브레이크와 핸들이 더 정교해져야 하는 것과 같습니다.
Q. 하네스 엔지니어링의 핵심 구성 요소는 무엇입니까?
CLAUDE.md(작업 지시서), 단일 책임 에이전트(분업), 명시적 인터페이스(입출력 정의), 가드레일(안전장치), 오케스트레이션(파이프라인 조립) — 이 다섯 가지입니다. 산업혁명의 매뉴얼, 전문 인력, 규격, 안전 규정, 생산 라인에 각각 대응하는 개념입니다.
Q. 바이브 코딩과 하네스 엔지니어링은 어떤 관계입니까?
바이브 코딩은 AI에게 자유롭게 코드를 생성하게 하는 방식입니다. 빠르게 프로토타입을 만들 때 유용하지만, 프로덕션 수준의 시스템에는 구조가 필요합니다. 하네스 방식은 바이브 코딩의 자유로움 위에 규칙과 구조를 얹어서, 안정적이고 반복 가능한 결과를 만들어냅니다.
Q. CLAUDE.md는 어떻게 작성합니까?
프로젝트의 목적, 작업 규칙, 금지 사항, 파일 저장 경로, 에이전트 간 역할 분담을 마크다운 문서로 작성합니다. 처음에는 간단하게 시작하고, 에이전트가 실수할 때마다 해당 규칙을 추가하면서 점점 정교하게 만들어가면 됩니다.
이 방법론은 AI를 더 똑똑하게 만드는 기술이 아닙니다. 이미 충분히 똑똑한 AI가 제대로 된 방향으로 일하게 만드는 기술입니다. 산업혁명이 기계의 성능이 아니라 공장 시스템의 설계로 세상을 바꿨듯, 하네스 엔지니어링은 AI 에이전트 시대의 새로운 설계 역량입니다.