하네스 엔지니어링이란? AI 에이전트를 덜 망가뜨리는 실전 방법

AI 에이전트가 "다 만들었습니다"라고 말했는데 막상 브라우저를 열면 버튼이 안 눌리고 테스트는 터지는 경우가 있습니다. 이때 바로 더 비싼 모델을 찾기보다 먼저 봐야 할 것이 하네스입니다. 하네스 엔지니어링은 AI가 일하는 도구, 지침, 검증 루프를 설계해 결과가 실제 작업으로 이어지게 만드는 방법입니다.

예전 AI 활용은 질문을 잘 쓰는 쪽에 가까웠습니다. 프롬프트를 다듬고, 필요한 문맥을 넣고, 답변 형식을 지정하면 좋은 답을 얻을 수 있었습니다. 그런데 요즘 AI 에이전트는 답변만 하지 않습니다. 파일을 읽고, 코드를 고치고, 명령어를 실행하고, 웹을 검색하고, 브라우저까지 만집니다.

그래서 질문이 바뀌었습니다. "어떻게 물어볼까?"보다 "어떤 작업 환경에서 일하게 만들까?"가 더 중요해졌습니다. 최근에는 이런 관점을 하네스 엔지니어링이라고 부르는 흐름도 나옵니다.

 

AI 에이전트가 프로젝트 지침, 도구 연결, 테스트 결과, 브라우저 확인 과정을 거치며 작업하는 모습을 표현한 일러스트

 

 

 

하네스 엔지니어링을 한 문장으로 말하면

하네스 엔지니어링은 AI 모델 주변의 도구, 규칙, 작업 순서, 검증 장치를 설계하는 일입니다.

여기서 하네스는 에이전트 프로그램 자체일 수도 있고, 그 안에 붙는 MCP, 스킬, 프로젝트 지침 파일일 수도 있습니다. 모델을 새로 훈련시키는 게 아니라, 모델이 덜 헤매고 덜 거짓 완료를 하도록 작업장을 정리하는 쪽에 가깝습니다.

코딩 에이전트에게 "이 기능 만들어줘"라고만 하면 모델은 코드를 수정하고 스스로 끝났다고 판단할 수 있습니다. 하네스가 잘 잡혀 있으면 완료 기준이 달라집니다.

• 관련 파일을 먼저 찾는다.
• 수정 후 테스트나 린트를 실행한다.
• 로컬 서버를 띄우고 브라우저에서 실제 동작을 확인한다.
• 실패 로그를 읽고 다시 고친다.
• 반복되는 프로젝트 규칙은 지침 파일로 계속 참고한다.

 

이런 절차가 들어가면 AI의 완료 기준이 "말"에서 "검증 결과"로 이동합니다. 하네스 엔지니어링의 실전 가치는 여기서 나옵니다.

 

 

 

 

프롬프트 엔지니어링과 다른 점

프롬프트 엔지니어링은 모델에게 말을 잘 거는 기술입니다. 하네스 엔지니어링은 모델이 실제 일을 할 환경을 설계하는 기술입니다.

프롬프트는 질문, 역할, 출력 형식을 주로 만집니다. 하네스는 도구, 파일 접근, 검증 루프, 작업 절차를 만집니다. 프롬프트가 틀리면 답이 흐리거나 엉뚱해지는 경우가 많고, 하네스가 약하면 "했다고 말했는데 결과가 깨지는" 문제가 자주 생깁니다.

둘 중 하나만 필요한 것은 아닙니다. 다만 AI가 파일을 직접 고치고 외부 서비스를 호출하는 순간부터는 프롬프트만으로 통제하기 어려운 영역이 생깁니다. 말로 "꼭 확인해"라고 쓰는 것보다, 확인할 수밖에 없는 도구와 절차를 붙이는 편이 더 안정적입니다.

 

 

 

 

하네스는 네 군데에서 만질 수 있다

가장 큰 하네스는 Cursor, Claude Code, Codex 같은 에이전트 프로그램 자체입니다. 이런 도구들은 모델에게 파일 읽기, 파일 수정, 터미널 실행, 검색 같은 권한을 주고, 그 권한을 어떤 순서로 쓸지 안내합니다.

사용자 입장에서 현실적으로 만질 수 있는 지점은 보통 네 가지입니다.

 

조작 지점	언제 쓰면 좋은가	주의할 점
AGENTS.md 같은 지침 파일	프로젝트 구조, 실행 명령, 금지 규칙을 반복해서 알려야 할 때	너무 길면 모델이 놓칠 수 있음
스킬	발표 자료, 문서 작성, 배포 점검처럼 반복 작업의 품질 기준이 있을 때	추상 조언보다 체크 절차가 효과적
MCP	GitHub, 브라우저, DB, 문서 도구처럼 외부 기능을 직접 써야 할 때	권한이 커지므로 필요한 것만 붙이는 게 좋음
에이전트/SDK 개조	역할별 에이전트, 코드 수정 방식, 평가 루프까지 직접 통제하고 싶을 때	코딩과 실험 비용이 급격히 올라감

 

처음부터 에이전트를 직접 만들 필요는 없습니다. 대부분은 지침 파일 정리, MCP 하나 추가, 검증 명령 강제만으로도 체감이 납니다. MCP 쪽부터 보고 싶다면 2025년에 꼭 써야 할 7가지 Model Context Protocol(MCP) Server처럼 실제 서버 후보를 먼저 훑어보는 편이 빠릅니다.

 

프롬프트만으로 끝내는 작업과 지침, 도구, 테스트, 브라우저 확인을 거치는 AI 에이전트 작업 흐름을 비교한 다이어그램

 

 

제일 먼저 고칠 곳은 검증 루프다

AI가 가장 자주 사고 치는 지점은 "확인하지 않고 완료했다고 말하는 것"입니다. 파일은 고쳤는데 빌드는 안 되고, 빌드는 되는데 브라우저에서 깨지고, 브라우저는 뜨는데 버튼을 누르면 콘솔 에러가 나는 식입니다.

이 문제를 프롬프트로만 막으려 하면 한계가 있습니다. "반드시 확인해"라는 지시는 긴 작업 중간에 희미해질 수 있습니다. 반대로 하네스에 검증 루프가 들어가면 확인이 선택이 아니라 절차가 됩니다.

예를 들면 이런 흐름입니다.

1. 수정할 파일을 찾는다.
2. 코드를 바꾼다.
3. 테스트나 린트를 실행한다.
4. 로컬 서버를 띄운다.
5. 브라우저에서 실제 화면을 확인한다.
6. 실패 로그를 읽고 다시 수정한다.

 

이 루프가 들어가면 "완료"라는 말의 무게가 달라집니다. AI가 그럴듯하게 설명했는지가 아니라, 실제로 버튼이 눌렸는지, 에러가 사라졌는지, 테스트가 통과했는지가 기준이 됩니다.

핵심은 AI에게 더 세게 말하는 것이 아닙니다. 실패했을 때 다시 볼 증거를 남기고, 그 증거를 확인해야만 완료할 수 있게 만드는 것입니다.

 

 

 

코드 수정 방식도 하네스다

코딩 에이전트가 코드를 고치는 방식도 성능에 영향을 줍니다. 어떤 에이전트는 git diff처럼 변경분을 출력하게 하고, 어떤 에이전트는 원문 일부를 찾아 새 코드로 교체하게 합니다. 또 어떤 오픈소스 에이전트는 각 줄에 식별자를 붙여 모델이 어느 줄을 바꾸는지 더 정확히 말하게 만듭니다.

이 차이는 작아 보이지만 실제 파일 수정에서는 꽤 큽니다. 모델이 "이 근처를 바꾸면 됩니다"라고 말하는 것과, 에이전트가 바로 적용할 수 있는 수정 명령을 내놓는 것은 다릅니다. 하네스가 수정 포맷을 잘 잡아주면 모델의 답변이 실제 변경으로 이어질 가능성이 올라갑니다.

그래서 에이전트 성능을 볼 때 모델 이름만 보면 안 됩니다. 어떤 도구를 붙였는지, 수정 결과를 어떻게 적용하는지, 실패했을 때 다시 시도하는 루프가 있는지도 같이 봐야 합니다. 아예 에이전트 구조를 직접 만지는 쪽이 궁금하다면 Claude Agent SDK란? 개념부터 TypeScript 예제, 원격 실행까지 한 번에 정리 같은 글이 다음 단계가 될 수 있습니다.

 

 

 

초보자는 이렇게 시작하면 된다

가볍게 시작하려면 반복 실패를 하나만 고르세요. 하네스 엔지니어링은 거대한 시스템을 만드는 일이 아니라, 자주 터지는 실패를 줄이는 작은 장치를 붙이는 일부터 시작합니다.

프로젝트 맥락을 자꾸 놓친다면 AGENTS.md부터 만듭니다. 폴더 구조, 실행 명령어, 테스트 명령어, 금지할 작업, 자주 틀리는 규칙을 적습니다. 프로젝트가 커지면 한 파일에 전부 몰아넣기보다 역할별 문서로 나누는 편이 낫습니다.

반복 작업 품질이 흔들린다면 스킬로 뺍니다. 예를 들어 AI가 발표 자료를 만들 때 글자를 너무 작게 만든다면 "최소 폰트 크기", "렌더링 후 시각 확인", "한 슬라이드에 문장 몇 줄 이하" 같은 기준을 절차로 만듭니다. 매번 채팅창에서 혼내는 것보다 재사용되는 지침으로 만드는 편이 안정적입니다.

외부 서비스 작업이 많다면 MCP를 붙입니다. GitHub 작업이 많으면 GitHub MCP, 브라우저 확인이 중요하면 브라우저 관련 MCP, 문서나 데이터베이스 작업이 많으면 그에 맞는 MCP가 후보가 됩니다. 다만 MCP는 능력과 권한을 같이 늘립니다. 많이 붙이는 것보다 필요한 작업에 정확히 붙이는 게 낫습니다.

코딩 결과가 자주 깨진다면 검증 루프를 완료 조건으로 넣습니다. "끝나면 테스트해"가 아니라 "테스트, 빌드, 브라우저 확인까지 끝나야 완료"로 바꾸는 식입니다. 사람이 기억할 일을 하네스가 기억하게 만드는 것이 핵심입니다.

 

 

 

 

하네스도 만능은 아니다

하네스 엔지니어링이 결과를 꽤 개선할 수는 있지만, 모든 문제를 해결하지는 못합니다. 특히 Markdown 지침으로 에이전트를 교육하는 방식은 결국 긴 문맥을 모델에게 읽히는 일입니다. 지시가 너무 많아지면 모델은 일부를 놓칩니다.

직접 에이전트를 개조하는 쪽으로 가면 난이도도 올라갑니다. 에이전트 구조를 알아야 하고, 도구 호출 방식을 설계해야 하고, 정말 좋아졌는지 평가할 실험도 필요합니다. 모델마다 잘 맞는 하네스가 다를 수도 있습니다.

그래서 실전 기준은 간단합니다. 내가 반복해서 겪는 실패를 하나 고르고, 그 실패를 줄이는 가장 작은 하네스를 붙이면 됩니다. 코드가 자꾸 깨지면 브라우저 확인 루프를, 프로젝트 맥락을 자꾸 놓치면 구조 문서를, 외부 서비스 작업이 많으면 MCP를 붙이는 식입니다.

 

 

 

 

결론: AI를 혼내지 말고 작업장을 고쳐야 한다

하네스 엔지니어링은 거창한 단어처럼 보이지만, 실제로는 우리가 이미 하던 일을 더 체계적으로 부르는 말에 가깝습니다. AI에게 매번 "제대로 해", "확인해", "이 규칙 지켜"라고 말하는 대신, 그 규칙과 확인 절차를 에이전트의 작업 환경에 넣는 것입니다.

비싼 모델을 쓰는 것도 방법입니다. 하지만 AI가 같은 실수를 반복한다면 먼저 하네스를 봐야 합니다. 도구를 제대로 붙였는지, 지침이 재사용 가능한 형태인지, 완료 기준이 말이 아니라 검증 결과인지 확인해 보세요.

모델을 바꾸기 전에 작업장을 바꾸는 것. 그게 하네스 엔지니어링을 실전에서 써먹는 가장 현실적인 출발점입니다.

 

 

 

FAQ

 

하네스 엔지니어링을 하려면 코딩을 알아야 하나요?

깊게 들어가면 코딩 지식이 필요합니다. 하지만 처음에는 AGENTS.md 같은 지침 파일을 만들거나, MCP를 설치하거나, 테스트 명령을 작업 절차에 넣는 것만으로도 시작할 수 있습니다.

 

좋은 모델을 쓰면 하네스는 필요 없나요?

필요합니다. 좋은 모델도 확인하지 않은 작업은 틀릴 수 있습니다. 하네스는 모델의 지능을 대체하는 것이 아니라, 그 지능이 실제 결과로 이어지도록 작업 조건을 잡아주는 역할입니다.