‘프롬프트 잘 쓰기’가 한계에 부딪힌 지점
2~3년 전만 해도 AI 활용 개발의 화두는 ‘프롬프트를 어떻게 쓰느냐’였다. 그런데 코딩 도구가 자동완성(한 줄 제안)에서 에이전트(스스로 파일을 열고 명령을 실행하고 결과를 보고 다음 수를 두는 방식)로 넘어오면서, 프롬프트만으로는 설명되지 않는 영역이 커졌다. 같은 문장을 넣어도 어떤 도구는 테스트를 돌려 스스로 고치고, 어떤 도구는 첫 답에서 멈춘다. 차이는 지시문이 아니라 그 지시를 받아 ‘움직이는 판’ 자체에 있다. 이 판을 설계하는 일을 요즘 업계에서 ‘하네스(harness) 엔지니어링’이라 부른다. OpenAI가 코딩 에이전트 Codex를 소개하며 ‘에이전트 우선(agent-first)’ 개발을 강조한 뒤, 국내 개발자 사이에서도 이를 ‘하네스·컨텍스트·프롬프트’ 3층으로 나눠 이해하려는 논의가 이어지고 있다.
용어부터 짚으면 오해가 절반은 줄어든다. 하네스는 원래 말을 부리는 ‘마구(馬具)’를 뜻하고, 소프트웨어에서는 ‘테스트 하네스’처럼 대상을 감싸 실행·통제하는 틀을 가리키던 오래된 단어다. 에이전트 맥락의 하네스는 AI 모델 그 자체가 아니라, 모델이 파일을 읽고·셸을 실행하고·결과를 되받아 다음 행동을 정하게 만드는 실행 루프와 도구 연결 전체를 말한다. 가장 흔한 착각이 ‘하네스 엔지니어링 = 프롬프트 고급 기술’이라는 등호다. 프롬프트는 3층 중 가장 바깥의 지시문일 뿐이고, 하네스는 그 아래에서 에이전트가 무엇을 만질 수 있고 몇 번까지 재시도하며 언제 멈추는지를 규정하는 인프라에 가깝다. 모델을 아무리 좋은 걸로 바꿔도 하네스가 허술하면 같은 자리에서 헛돈다.
문제가 생기면 어느 층을 손봐야 하나 — 3층 진단 프레임
3층 구분의 진짜 쓸모는 개념 분류가 아니라 ‘고장 진단’에 있다. 하네스는 에이전트가 ‘무엇을 할 수 있는가'(도구·권한·실행 루프)를 정한다. 파일 쓰기를 허용할지, 셸 실행을 열지, 최대 몇 회 반복할지, 실패하면 어디서 사람에게 넘길지가 여기 속한다. 컨텍스트는 에이전트가 ‘무엇을 아는가’로, 관련 코드·문서·이전 대화·검색 결과처럼 모델에 실제로 주입된 정보다. 프롬프트는 ‘이번에 무엇을 시키는가’인 구체 지시다. 세 층을 분리하면 증상별로 원인 층이 대응된다.
실전 진단은 이렇게 갈린다. 에이전트가 엉뚱한 파일을 고쳤다면 대개 컨텍스트 문제다 — 고쳐야 할 코드를 애초에 보지 못한 것이라, 프롬프트를 아무리 다듬어도 낫지 않고 관련 파일을 컨텍스트에 넣어줘야 한다. 같은 실수를 반복하며 끝나지 않는다면 하네스 문제다 — 재시도·종료 조건이 없어 루프가 도는 것이라 프롬프트가 아니라 루프 설계를 손봐야 한다. 지시 자체를 오해했다면 그제야 프롬프트 문제다. 그래서 성능이 안 날 때 던질 질문의 순서는 (1) 필요한 컨텍스트가 실제로 들어갔는가 → (2) 실패 시 멈추고 넘기는 조건이 있는가 → (3) 지시가 모호하지 않은가 이다. 이 순서를 건너뛰고 ‘프롬프트만 계속 고치는’ 접근이 가장 흔한 시간 낭비다. 세 질문에 각각 담당 층이 있다는 감각만 잡아도 시행착오가 크게 준다.
Codex 같은 코딩 에이전트, 실제 경계는 어디인가
OpenAI는 Codex를 웹·앱 등 여러 형태로 확장하며 ‘에이전트가 여러 단계를 자율 수행’하는 방향을 밀고 있고, 자사 서비스 구축에도 Codex 하네스를 실제로 썼다고 소개한다. 여기서 마케팅과 현실의 경계를 그어야 한다. 코딩 에이전트가 확실히 이득을 내는 영역은 ‘정답 판정 기준이 코드로 존재하는’ 작업이다. 정해진 패턴의 리팩터링, 테스트 코드 생성, 실패한 테스트나 에러 로그를 기준으로 한 수정, 반복적인 문서화가 대표적이다. 이 작업들의 공통점은 결과가 맞았는지를 사람 판단 없이 기계가 채점할 수 있다는 것 — 그래서 에이전트가 스스로 돌려보고 고치는 루프가 성립한다. 반대로 요구사항 자체가 모호한 설계 결정, 도메인 지식이 필요한 트레이드오프, ‘지금 이 조직에서 무엇이 우선인가’ 같은 판단은 채점 기준이 없어 자동화가 잘 안 된다. 경계를 가르는 기준은 ‘어려워 보이는가’가 아니라 ‘정답을 기계가 검증할 수 있는가’다.
초보자가 가장 자주 넘어지는 지점은 ‘맡겨두면 알아서 완성된다’는 기대다. 실제로는 검증 루프 없는 자율 실행일수록 위험이 커진다. 에이전트는 그럴듯하지만 틀린 코드를 자신 있게 내놓을 수 있고, 그것이 테스트를 우회해 병합되면 디버깅 비용이 오히려 늘어난다. 사람이 처음부터 짰다면 안 했을 실수를, 겉보기 완성도가 높은 형태로 심어두기 때문에 발견도 늦다. 그래서 성숙한 팀일수록 하네스에 ‘자동 검증 게이트’를 박는다. 에이전트 변경분은 예외 없이 테스트·린트·리뷰를 통과하게 하고, 권한이 큰 작업(배포·삭제·외부 호출)일수록 사람 승인을 강제하는 식이다. 참고로 OpenAI의 ‘공부 모드(Study mode)’처럼 답을 바로 주지 않고 단계적으로 유도하는 설계도, 사람이 판단력을 놓지 않도록 일부러 마찰을 넣은 사례로 읽을 수 있다. 자율성과 통제는 반대말이 아니라, 하네스가 함께 설계해야 하는 한 쌍이다.
도입 전에 답해야 할 네 가지 질문 — 비용·보안·검증
도입 판단은 ‘좋다/나쁘다’가 아니라 조건 확인으로 접근해야 한다. 먼저 비용이다. 에이전트는 한 작업에 모델을 여러 번 호출하고, 파일을 읽고 결과를 되먹이며 컨텍스트를 반복 전송하기 때문에, 단순 자동완성 대비 토큰 소모가 몇 배로 뛸 수 있다. ‘한 번 물어보는’ 요금 감각으로 접근하면 청구서에서 놀란다. 그래서 처음부터 전면 자율로 가기보다, 반복성이 높고 검증이 쉬운 작업(테스트 생성, 정형 리팩터링) 한두 종류에 좁게 적용해 작업 단위로 비용과 효과를 측정하는 편이 안전하다. 보안에서는 셸 실행·파일 쓰기·외부 네트워크 권한을 기본적으로 닫고 필요한 만큼만 여는 최소권한 원칙이 핵심이다. 특히 외부에서 수집한 이슈 본문이나 문서를 그대로 프롬프트에 넣을 때, 그 안에 심긴 지시를 에이전트가 명령으로 실행해버리는 ‘프롬프트 인젝션’을 경계해야 한다. 대응은 프롬프트 문구를 다듬는 게 아니라 하네스 단에서 외부 데이터를 ‘사실·소재’로만 취급하도록 격리하고 권한을 좁혀 피해 반경을 줄이는 것이다.
6개월~2년 관점에서 무게중심은 ‘코드를 얼마나 빨리 쓰느냐’에서 ‘에이전트가 낸 결과를 얼마나 믿을 수 있게 검증·통제하느냐’로 이동할 가능성이 크다. 개발자에게 요구되는 역량도 문법 지식보다 시스템 설계·검증 설계·리뷰 판단 쪽으로 옮겨간다 — 코드를 생산하는 사람에서, 에이전트가 생산한 코드를 신뢰 가능한 상태로 만드는 사람으로. 그래서 도입 전 던질 네 질문은 이렇다. (1) 이 작업은 정답을 기계가 채점할 수 있는가, (2) 실패해도 되돌릴 안전장치(테스트·승인·롤백)가 있는가, (3) 권한은 필요한 최소로 닫았는가, (4) 비용을 작업 단위로 추적할 수 있는가. 네 가지가 안 갖춰졌다면 자율성 레벨을 올리기 전에 하네스부터 다지는 게 순서다. 이 순서를 뒤집는 순간, 도구는 생산성이 아니라 부채가 된다.
자주 묻는 질문
하네스 엔지니어링은 프롬프트 엔지니어링과 뭐가 다른가요?
프롬프트 엔지니어링이 ‘이번에 무엇을 시킬지’ 지시문을 다듬는 일이라면, 하네스 엔지니어링은 그 아래에서 에이전트가 어떤 도구를 쓰고·어떤 권한을 갖고·몇 번 재시도하며·실패 시 어떻게 멈추는지 실행 환경 전체를 설계하는 일입니다. 프롬프트는 하네스·컨텍스트·프롬프트 3층 중 가장 바깥층이라, 모델을 바꿔도 하네스가 허술하면 성능이 안 나옵니다.
에이전트가 자꾸 엉뚱한 파일을 고치는데 프롬프트를 어떻게 고쳐야 하나요?
이건 대개 프롬프트 문제가 아니라 컨텍스트 문제입니다. 고쳐야 할 코드를 에이전트가 애초에 보지 못한 상황이라, 지시문을 다듬어도 낫지 않습니다. 관련 파일·모듈을 컨텍스트에 명시적으로 넣어주는 것이 먼저입니다. 반대로 같은 실수를 반복하며 멈추지 못하면 그건 하네스(재시도·종료 조건)를 손봐야 할 신호입니다.
Codex 같은 코딩 에이전트가 개발자를 대체하나요?
정답을 기계가 채점할 수 있는 반복 작업(정형 리팩터링·테스트 생성·에러 로그 기반 수정 등)은 상당 부분 자동화됩니다. 하지만 요구사항이 모호한 설계 결정, 도메인 트레이드오프, 조직 우선순위 판단처럼 검증 기준이 없는 일은 여전히 사람 몫입니다. 오히려 검증과 통제를 설계하는 역량의 중요도가 올라갑니다.
에이전트에 자율 실행 권한을 주면 뭐가 위험한가요?
검증 게이트 없이 자율 실행하면 그럴듯하지만 틀린 코드가 겉보기 완성도 높은 형태로 병합돼, 오히려 디버깅 비용이 늘 수 있습니다. 셸 실행·파일 쓰기 권한을 기본적으로 닫고, 테스트·린트·사람 승인 같은 자동 검증 단계를 하네스에 넣으며, 배포·삭제처럼 위험이 큰 작업은 승인을 강제하는 것이 안전합니다.
외부에서 수집한 문서를 에이전트에 넣을 때 주의할 점은?
수집한 이슈 본문·문서 안에 심긴 지시를 에이전트가 명령으로 실행하는 프롬프트 인젝션 위험이 있습니다. 프롬프트 문구로 막으려 하지 말고, 하네스 단에서 외부 데이터를 ‘사실·소재’로만 취급하도록 격리하고 실행 권한을 최소화해 피해 반경 자체를 좁히는 설계가 핵심입니다.