AI 앱은 프롬프트가 아니라 하네스로 완성된다

목차

1. 하네스 엔지니어링이란 정확히 무엇인가?
2. 왜 AI 앱은 프롬프트만으로 제품이 되지 않을까?
3. 프롬프트·컨텍스트·하네스 엔지니어링은 어떻게 다를까?
4. 좋은 하네스는 어떤 층으로 이루어질까?
5. 매번 답이 바뀌는 LLM을 어떻게 테스트할까?
6. RAG와 에이전트는 무엇을 따로 평가해야 할까?
7. 어떤 도구를 선택해야 할까?
8. 오늘 바로 만들 수 있는 최소 하네스는 무엇인가?
9. 보안과 개인정보 리스크는 어디서 통제해야 할까?
10. 하네스 성숙도는 어떻게 올릴까?
11. 어디까지 믿고, 어디부터 의심해야 할까?
12. FAQ: 하네스 엔지니어링에 대해 자주 묻는 질문은?
13. 결론: AI 제품의 품질은 어디서 완성되는가?

---

결론부터 말하면, 앞으로 AI 제품의 품질은 “어떤 모델을 썼는가”보다 “그 모델을 어떤 하네스 안에서 일하게 했는가”로 갈린다. 프롬프트는 여전히 중요하다. 하지만 프롬프트만으로는 회귀 테스트, 권한 통제, 비용 폭주, 환각, RAG 실패, 다중 에이전트 루프를 막을 수 없다.

이 글은 특정 벤더의 제품 소개가 아니다. “하네스 엔지니어링”이라는 표현은 OpenAI의 Codex 사례를 계기로 더 눈에 띄었지만, 실제 문제는 특정 제품에 묶이지 않는다. Anthropic, LangSmith, Langfuse, Braintrust, Ragas가 서로 다른 방식으로 같은 질문을 다룬다. 모델이 답을 잘 만드는 것만으로 충분한가, 아니면 답이 만들어지고 검증되고 운영 실패가 다시 테스트로 돌아오는 환경까지 설계해야 하는가.

이 글은 그 질문에서 시작한다. 하네스 엔지니어링을 유행어로 소비하지 않고, AI 앱을 실제 제품으로 운영하기 위한 개발 방법으로 분해한다.

하네스 엔지니어링이란 정확히 무엇인가?

하네스 엔지니어링은 AI 모델을 둘러싼 실행 구조를 설계하는 일이다. 여기서 하네스는 모델이 무엇을 읽고, 어떤 도구를 쓰고, 어떤 권한으로 실행하고, 실패를 어떻게 기록하고, 다음 배포에서 같은 실수를 반복하지 않게 만드는지까지 포함한다.

하네스는 모델 바깥의 제품 설계다

전통적인 테스트 하네스는 테스트 대상 코드를 실행하기 위한 더미, 드라이버, 픽스처(fixture), 검증 코드를 뜻했다. LLM 시대의 하네스는 범위가 더 넓다. 모델 자체는 확률적으로 텍스트와 행동 후보를 만든다. 하네스는 그 후보가 제품 환경에서 안전하고 반복 가능하게 실행되도록 주변을 묶는다.

조금 더 쉽게 말하면, 모델은 엔진이고 하네스는 차체, 계기판, 브레이크, 안전벨트, 정비 기록에 가깝다. 엔진 출력만으로는 고속도로를 달릴 수 없다. 방향을 잡는 조향 장치, 속도를 제한하는 제어 장치, 사고가 났을 때 원인을 추적하는 기록 장치가 필요하다.

여러 평가 도구 문서도 같은 방향을 가리킨다. OpenAI는 evals를 작업 정의, 테스트 입력 실행, 결과 분석과 개선의 흐름으로 설명한다. LangSmith는 오프라인 평가와 온라인 평가를 나누고, Braintrust는 데이터셋·채점기·트레이스·CI 통합·운영 모니터링을 함께 다룬다 (출처: OpenAI Working with Evals, LangSmith Evaluation Concepts, Braintrust LLM Evaluation Guide). 이 공통분모가 하네스의 최소 골격이다.

2026년에 갑자기 중요해진 이유

모델 성능이 올라가면서 역설적으로 제품 실패는 더 잘 숨는다. 데모에서는 답이 그럴듯하다. 그러나 배포 후에는 같은 질문이 매번 조금씩 달라지고, RAG 검색 결과가 흔들리고, 도구 호출이 실패하고, 사용자가 악의적 입력을 넣고, 비용이 조용히 불어난다.

OpenAI와 Braintrust 모두 생성형 AI 평가에서 목표, 데이터셋, 지표, 비교 실행, 지속 평가가 필요하다고 설명한다. Langfuse 역시 평가를 반복 가능한 행동 점검으로 보고, 변경 전 회귀를 잡는 데 쓴다 (출처: OpenAI Evaluation Best Practices, Braintrust LLM Evaluation Guide, Langfuse Evaluation Overview).

이 글에서 쓰는 실전 정의

이 글에서는 하네스 엔지니어링을 이렇게 정의한다.

이 글의 핵심

하네스 엔지니어링의 실전 정의

하네스 엔지니어링은 AI 모델이 제품 안에서 읽고, 판단하고, 도구를 쓰고, 실패를 기록하고, 다음 배포에서 개선되도록 만드는 컨텍스트·도구·평가·관측·권한·피드백 루프의 설계다.

중요한 점은 “프롬프트를 잘 쓰는 법”과 다르다는 것이다. 프롬프트는 하네스 안의 한 부품이다. 제품의 신뢰성은 부품 하나가 아니라 전체 장치에서 나온다.

하네스가 없는 AI 앱은 어디서 무너질까?

하네스가 약한 팀은 대개 같은 패턴으로 무너진다. 첫째, 모델이나 프롬프트를 바꾼 뒤 기존 정상 케이스가 깨졌는지 모른다. 둘째, 운영에서 환각이 발생해도 그 입력이 다음 테스트셋으로 들어가지 않는다. 셋째, 도구 호출 실패와 모델 판단 실패를 구분하지 못한다. 넷째, 비용과 지연 시간이 기능 단위로 추적되지 않아 어느 워크플로가 돈을 쓰는지 알 수 없다.

이 네 가지는 모델을 더 비싼 것으로 바꿔도 사라지지 않는다. 오히려 더 강한 모델에게 더 큰 권한과 더 긴 작업을 맡기면 실패 경로가 늘어난다. 그래서 하네스 엔지니어링은 “모델이 부족해서 하는 일”이 아니라 “모델이 충분히 강해졌기 때문에 필요한 일”에 가깝다.

왜 AI 앱은 프롬프트만으로 제품이 되지 않을까?

프롬프트만으로 데모는 만들 수 있다. 하지만 제품은 다르다. 제품은 사용자가 예측 불가능한 입력을 넣어도, 모델이나 프롬프트를 바꿔도, 운영 로그에서 실패가 발견돼도, 다시 배포할 때 품질이 무너지지 않아야 한다.

프롬프트는 의도이고, 제품은 상태다

프롬프트는 모델에게 “어떻게 행동하라”는 의도를 전달한다. 하지만 AI 제품은 상태를 가진다. 대화 기록, 검색 인덱스, 사용자 권한, 도구 호출 결과, 파일 시스템, 외부 API, 비용 한도, 실패 로그가 모두 제품 상태다.

예를 들어 고객지원 챗봇이 “정확히 답하라”는 프롬프트를 갖고 있어도, 검색 인덱스가 오래됐거나 권한 없는 문서를 가져오거나 JSON 응답이 깨지면 제품은 실패한다. 이 문제는 프롬프트 문장을 다듬는 것으로 해결되지 않는다.

코딩 에이전트가 보여준 역할 이동

이 변화를 실무적으로 보여주는 대표 사례는 Claude Code다. Anthropic은 Claude Code가 파일을 읽고, 명령을 실행하고, 변경을 만들 수 있는 에이전트형 코딩 환경이라고 설명하면서, 좋은 사용 패턴으로 “검증할 방법을 먼저 제공하기”, “먼저 탐색하고, 계획한 뒤, 구현하기”를 제안한다. 이 관점에서 핵심은 모델 이름이 아니라 모델이 일할 작업장, 성공 기준, 테스트 루프를 사람이 설계한다는 점이다 (출처: Anthropic Claude Code Best Practices).

OpenAI의 Codex 하네스 글도 같은 흐름을 보여주는 다른 사례다. 다만 이것을 OpenAI만의 방법론처럼 읽으면 곤란하다. Anthropic의 에이전트 설계 글은 검색, 도구, 메모리를 갖춘 augmented LLM과 단계별 워크플로를 설명하고, 다중 에이전트 리서치 시스템 글도 도구 인터페이스와 실행 경로 관찰을 강조한다. LangSmith와 Braintrust 역시 운영 트레이스를 평가 데이터로 되돌리는 루프를 다룬다 (출처: Anthropic Building Effective Agents, Anthropic Multi-Agent Research System, OpenAI Harness Engineering, LangSmith Evaluation Types, Braintrust LLM Evaluation Guide).

즉 핵심은 “Codex를 쓰자”가 아니다. 사람이 더 상위의 설계 수준에서 우선순위, 수용 기준, 결과 검증, 위험 경계를 정해야 한다는 것이다.

이 흐름은 GPT-5.5 총정리에서 다룬 장기 실행 에이전트 흐름과도 이어진다. 모델이 더 오래 일할수록 중요한 것은 답변 문장보다 작업 환경이다.

좋은 프롬프트도 실패를 기억하지 못한다

가장 큰 차이는 기억이다. 프롬프트는 실패를 구조적으로 축적하지 못한다. 오늘 운영에서 발생한 실패가 내일 테스트셋에 들어가고, 다음 PR에서 자동으로 재현되고, 배포 게이트에서 막히는 구조가 있어야 같은 실패가 줄어든다.

Braintrust는 LLM 평가에 필요한 구성요소로 데이터셋 관리, 채점기, 트레이싱, CI/CD 통합, 운영 모니터링을 함께 언급한다 (출처: Braintrust LLM Evaluation Guide). 이 다섯 가지를 합치면 프롬프트가 아니라 하네스가 된다.

프롬프트·컨텍스트·하네스 엔지니어링은 어떻게 다를까?

셋은 경쟁 개념이 아니다. 범위가 다르다. 프롬프트 엔지니어링은 모델에게 말하는 법이고, 컨텍스트 엔지니어링은 모델에게 무엇을 보여줄지 고르는 법이고, 하네스 엔지니어링은 모델이 제품 안에서 어떻게 실행되고 검증되는지 설계하는 법이다.

세 개념의 경계를 먼저 잡아야 한다

컨텍스트는 하네스의 가장 비싼 부품이다

AI 앱이 커질수록 컨텍스트는 비용이자 위험이다. 모델에게 많이 보여줄수록 비용이 오르고, 잘못 보여주면 오답이 더 그럴듯해진다. Graphify로 Claude Code 토큰 줄이는 법에서 다뤘던 지식 그래프 접근도 같은 문제의식에서 나온다. 모델에게 모든 파일을 밀어 넣는 대신, 읽어야 할 구조를 먼저 만든다.

하네스는 실행과 검증까지 포함한다

컨텍스트가 “읽을 것”이라면 하네스는 “일하는 방식”이다. 모델이 어떤 API를 호출할 수 있는지, 실패 시 재시도할지, 출력이 스키마를 만족하는지, 평가가 기준 이하이면 배포를 막을지, 운영 트레이스가 다음 테스트셋으로 들어갈지까지 포함한다.

Anthropic도 다중 에이전트 리서치 시스템을 만들며 정확한 프롬프트와 도구로 시뮬레이션을 돌리고, 에이전트가 어떤 단계에서 잘못된 도구를 고르는지 관찰했다고 설명했다. 복잡한 에이전트는 같은 입력에서도 여러 유효한 경로를 택할 수 있어 평가가 더 어렵다 (출처: Anthropic Engineering).

좋은 하네스는 어떤 층으로 이루어질까?

좋은 하네스는 모델 위에 얹는 장식이 아니다. 모델 주변에 층을 만든다. 컨텍스트, 도구, 메모리, 평가, 관측성, 보안이 각각 따로 움직이면 안 되고 하나의 피드백 시스템으로 연결돼야 한다.

컨텍스트와 데이터 층

첫 번째 층은 모델이 읽는 정보다. 문서, DB 결과, 검색 인덱스, 코드베이스 규칙, 사용자 권한, 이전 대화가 여기에 들어간다. 이 층에서 가장 중요한 질문은 “많이 넣을 것인가”가 아니라 “지금 작업에 맞는 신뢰 가능한 정보를 넣었는가”이다.

Karpathy LLM 위키 개념편에서 다룬 외부 지식 구조도 이 층과 맞닿아 있다. RAG든 위키든 그래프든, 핵심은 모델이 즉석에서 모든 것을 기억하게 만드는 것이 아니라 필요한 지식을 검색 가능한 구조로 외부화하는 것이다.

도구와 실행 층

두 번째 층은 도구다. 검색, 파일 읽기, 셸 실행, DB 조회, 결제 API, CRM 업데이트 같은 행동이 여기에 들어간다. 도구 설명이 모호하면 에이전트는 잘못된 도구를 고른다. Anthropic은 리서치 에이전트 글에서 도구 인터페이스가 인간용 UI만큼 중요하다고 설명했다 (출처: Anthropic Engineering).

AI 코딩 에이전트를 쓰는 팀이라면 Claude Code 완전 정복에서 다룬 실행 루프와 권한 모델을 함께 봐야 한다. 코딩 에이전트의 품질은 모델뿐 아니라 파일 시스템, 명령 실행, 테스트 루프, 승인 UX에서 나온다.

평가와 관측성 층

세 번째 층은 평가와 관측성이다. LangSmith는 오프라인 평가는 데이터셋과 예제에서, 온라인 평가는 운영 실행(run)과 대화 스레드(thread)에서 수행된다고 구분한다. 평가 기법도 사람 평가, 코드 평가, LLM-as-a-judge, 쌍대 비교(pairwise)로 나뉜다 (출처: LangSmith Evaluation Concepts).

Langfuse는 evals(평가)를 반복 가능한 행동 점검으로 설명하고, 변경 전 회귀를 잡는 데 쓴다고 설명한다 (출처: Langfuse Evaluation Overview). 이 층이 없으면 AI 앱은 “느낌상 좋아진 것 같다”와 “실제로 좋아졌다”를 구분하지 못한다.

하네스의 층은 서로 연결되어야 한다

각 층을 따로 도입하면 대시보드만 늘어난다. 검색 품질 지표가 낮아졌는데 어떤 프롬프트 버전에서 발생했는지 모르면 개선이 늦다. 도구 오류가 늘었는데 어떤 권한 정책 변경 이후인지 모르면 보안팀과 개발팀이 서로 다른 문제를 본다. 평가 점수가 떨어졌는데 운영 트레이스와 연결되지 않으면 실제 사용자 영향도를 알 수 없다.

좋은 하네스는 “모델 출력”만 저장하지 않는다. 입력, 검색된 문서 ID, 프롬프트 버전, 모델 이름, 도구 호출, 권한 판정, 비용, 지연 시간, 최종 사용자 반응까지 같은 사건으로 묶는다. 그래야 실패를 재현하고, 재현한 실패를 테스트로 만들고, 테스트가 다음 배포를 막을 수 있다.

매번 답이 바뀌는 LLM을 어떻게 테스트할까?

LLM 테스트의 핵심은 “항상 같은 문자열을 내는가”가 아니다. “허용 가능한 범위 안에서 같은 업무 품질을 유지하는가”다. 따라서 테스트도 완전 일치(exact match) 하나로 끝나지 않는다.

골든셋은 작게 시작해도 된다

처음부터 1,000개 케이스가 필요하지 않다. Braintrust는 실제 사용 사례와 알려진 실패 모드를 대표하는 25~50개 테스트 케이스와 2~3개 핵심 지표로 시작하라고 제안한다 (출처: Braintrust LLM Evaluation Guide). LangSmith도 수동으로 큐레이션한 고품질 예제 10~20개에서 출발해 운영 트레이스를 추가하는 방식을 권한다 (출처: LangSmith Evaluation Concepts).

중요한 것은 숫자보다 구성이다. 쉬운 성공 케이스만 모으면 품질이 좋아 보인다. 실제로는 실패한 고객 질문, 엣지 케이스, 악의적 입력, 기존 버그 리포트를 골든셋에 넣어야 한다.

규칙 기반 검사는 가장 먼저 돌린다

비싼 LLM 평가자(judge)를 먼저 쓰면 비용과 노이즈가 동시에 늘어난다. JSON이 파싱되는가, 필수 필드가 있는가, 금지 단어가 없는가, 인용 URL이 존재하는가, 생성된 SQL이 실행되는가 같은 검사는 규칙 기반으로 먼저 처리해야 한다.

OpenAI Graders 문서는 문자열 검사, 텍스트 유사도, 점수 모델 채점기, 파이썬 코드 실행 같은 평가 방식을 나눈다 (출처: OpenAI Graders). 실전에서는 이 순서가 중요하다. 결정적 검사로 잡을 수 있는 것은 결정적 검사로 잡아야 한다.

LLM-as-a-judge는 마지막 판단에 쓴다

LLM-as-a-judge는 유용하지만 만능이 아니다. OpenAI는 LLM 평가자가 위치 편향과 장황함 편향을 가질 수 있다고 설명하며, 쌍대 비교(pairwise), 통과/실패 판정, 명확한 루브릭, 강한 평가 모델, 길이 통제 등을 권한다 (출처: OpenAI Evaluation Best Practices).

이런 루브릭도 처음부터 완벽하지 않다. 사람이 일부 샘플을 직접 채점하고 LLM 평가자의 판정과 비교해야 한다. 평가자가 장황한 답변을 선호하거나, 더 자신감 있는 말투에 속거나, 특정 모델의 문체를 선호하면 루브릭을 고쳐야 한다.

테스트셋은 세 가지 바구니로 나눈다

실무에서는 모든 케이스를 한 파일에 넣지 않는 편이 좋다. 목적이 다르기 때문이다. 첫 번째는 역량 평가(capability eval)다. 아직 모델이나 하네스가 잘 못하는 어려운 과제를 모아 개선 방향을 찾는다. 두 번째는 회귀 평가(regression eval)다. 이미 고친 실패를 다시 깨지 않게 지키는 방어선이다. 세 번째는 안전성 평가(safety eval)다. 권한, 개인정보, 정책 위반, 금지 도구 호출처럼 제품 리스크가 큰 행동을 따로 본다.

이 셋을 섞으면 판단이 흐려진다. 역량 평가는 통과율이 낮아도 괜찮다. 아직 개선할 과제이기 때문이다. 회귀 평가는 통과율이 매우 높아야 한다. 이미 고친 버그가 다시 나오는 것은 배포 차단 사유다. 안전성 평가는 샘플 수가 적어도 엄격해야 한다. 한 번의 민감정보 노출이 제품 신뢰를 무너뜨릴 수 있기 때문이다.

RAG와 에이전트는 무엇을 따로 평가해야 할까?

RAG와 에이전트는 한 덩어리로 평가하면 원인을 놓친다. 답이 틀렸을 때 검색이 틀린 것인지, 검색은 맞았는데 생성이 틀린 것인지, 도구 호출 순서가 틀린 것인지, 권한 모델이 잘못된 것인지 분리해야 한다.

RAG는 검색과 생성을 분리해야 한다

Ragas는 RAG 평가 지표로 context precision, context recall, noise sensitivity, response relevancy, faithfulness 등을 제공한다. 또한 tool call accuracy, tool call F1, agent goal accuracy 같은 에이전트/도구 사용 지표도 따로 둔다 (출처: Ragas Metrics).

RAG 시스템에서 흔한 실수는 최종 답변만 보는 것이다. 최종 답변이 틀렸다면 최소 세 가지를 봐야 한다.

에이전트는 결과와 경로를 같이 봐야 한다

에이전트는 최종 결과가 맞아도 과정이 위험할 수 있다. 불필요한 외부 API를 호출했거나, 권한 없는 파일을 읽었거나, 비싼 모델을 반복 호출했거나, 실패 후 무한 루프에 빠졌다면 제품 관점에서는 실패다.

Anthropic은 다중 에이전트 시스템에서 같은 시작점이라도 서로 다른 유효한 경로로 목표에 도달할 수 있어 평가가 어렵다고 설명한다 (출처: Anthropic Engineering). 그래서 에이전트 평가에는 결과 평가(outcome eval)뿐 아니라 경로 평가(trajectory eval)가 필요하다.

운영 트레이스는 다음 테스트셋의 원료다

운영에서 나온 트레이스는 단순 로그가 아니다. 다음 평가셋의 원료다. 사용자가 낮은 평점을 준 답변, 지연 시간이 긴 요청, 도구 오류가 난 run, 정책 위반 가능성이 있는 출력은 모두 골든셋 후보가 된다.

LangSmith는 온라인 평가가 운영 실행(run)과 대화 스레드를 대상으로 한다고 설명한다. 반대로 오프라인 평가는 배포 전 선별한 데이터셋에서 돌린다 (출처: LangSmith Evaluation Types). 이 둘이 연결될 때 하네스가 성장한다.

어떤 도구를 선택해야 할까?

도구 선택은 “최고의 툴”을 고르는 문제가 아니다. 하네스의 어느 층이 약한지 보는 문제다. CI가 약하면 promptfoo나 DeepEval 계열이 먼저고, 트레이스가 약하면 LangSmith나 Langfuse가 먼저고, 협업 평가가 약하면 Braintrust 같은 플랫폼을 검토할 수 있다.

비교 기준은 기능보다 위치다

작은 팀은 CI 하네스부터 시작한다

작은 팀이라면 대형 플랫폼보다 CI 하네스가 먼저다. promptfoo는 CI/CD에서 프롬프트 평가, 보안 취약점 테스트, 품질 게이트, 비용 추적을 다룬다고 설명한다 (출처: Promptfoo CI/CD). 이 계층만 있어도 “프롬프트 한 줄 바꿨더니 기존 질문이 망가졌다”는 문제를 줄일 수 있다.

운영 서비스는 트레이스와 평가를 붙여야 한다

사용자가 이미 있는 서비스라면 트레이스가 필요하다. LangSmith 관측성 문서는 트레이싱, 모니터링, 대시보드, 알림, 자동화, 피드백 수집을 함께 다룬다 (출처: LangSmith Observability). Langfuse도 데이터셋, 실험, 실시간 평가자를 평가 흐름으로 제공한다 (출처: Langfuse Evaluation Overview).

도구는 취향이 아니라 병목으로 고른다. “왜 틀렸는지 모른다”가 병목이면 트레이스다. “배포 때마다 망가진다”가 병목이면 CI 평가다. “PM과 도메인 전문가가 품질 기준을 못 넣는다”가 병목이면 협업형 평가 UI다.

도구 선택은 90일 계획으로 쪼개야 한다

첫 주에는 도구보다 기준이 먼저다. 어떤 답변을 좋은 답변으로 볼지, 어떤 행동을 위험 행동으로 볼지, 어떤 비용을 초과하면 실패로 볼지 정의해야 한다. 첫 달에는 이 기준을 로컬 또는 CI에서 반복 가능하게 만든다. 그 다음에야 관측성 플랫폼과 협업 UI가 의미를 갖는다.

오늘 바로 만들 수 있는 최소 하네스는 무엇인가?

처음부터 완벽한 LLMOps 플랫폼을 만들 필요는 없다. 최소 하네스는 “반복 가능한 질문 모음, 자동 검사, 배포 기준, 실패를 다시 넣는 루프”만 있으면 시작할 수 있다.

1일차 목표는 작은 골든셋이다

제품에서 중요한 사용자 질문 30개를 고른다. 이때 20개는 정상 케이스, 5개는 엣지 케이스, 5개는 과거 실패 또는 위험 케이스로 잡는다. 각 케이스에는 입력, 기대 속성, 금지 조건, 참고 근거를 붙인다.

CI 게이트는 작고 단호해야 한다

처음부터 20개 지표를 만들면 팀이 지친다. 첫 달에는 세 가지만 보는 편이 낫다. 출력 형식 통과율, 근거성 통과율, 비용 또는 지연 시간 상한이다. 이 세 가지가 흔들리면 사용자가 바로 체감한다.

Promptfoo처럼 CI에 붙는 도구를 쓰든 직접 스크립트를 만들든, 원칙은 같다. 프롬프트, 모델, 검색 로직, 도구 스키마가 바뀌면 골든셋을 다시 돌린다. 기준 이하이면 merge나 배포를 막는다.

운영 트레이스를 남기지 않으면 개선도 없다

운영 트레이스에는 최소한 입력, 최종 출력, 모델 이름, 프롬프트 버전, 검색 문서 ID, 도구 호출, 지연 시간, 토큰 사용량, 에러, 사용자 피드백이 들어가야 한다. 이 데이터가 있어야 실패를 재현할 수 있다.

최소 하네스의 파일 구조 예시

도구를 아직 정하지 못했다면 파일 구조부터 고정해도 된다. 핵심은 평가셋, 실행기, 판정 기준, 운영에서 발견한 실패 후보를 분리하는 것이다.

evals/
  golden.jsonl          # 반드시 지켜야 하는 회귀 케이스
  capability.jsonl      # 아직 어려운 개선 과제
  safety.jsonl          # 권한, PII, 정책 위반 케이스
  rubrics/
    support-answer.md
    rag-grounding.md
  run-evals.ts
  reports/
    latest.json

이 구조만 있어도 프롬프트 변경 전후의 품질을 비교할 수 있다. 나중에 promptfoo, OpenAI Evals, LangSmith, Braintrust로 옮기더라도 이 파일들이 기준점이 된다.

보안과 개인정보 리스크는 어디서 통제해야 할까?

보안은 프롬프트 안에서만 해결되지 않는다. 특히 에이전트는 외부 문서, 웹 페이지, DB, 파일 시스템, 실행 도구를 읽고 쓴다. 신뢰 경계가 모델 안이 아니라 하네스 전체로 넓어진다.

간접 프롬프트 인젝션은 도구 경계에서 막아야 한다

간접 프롬프트 인젝션은 사용자가 직접 입력하지 않은 악성 지시가 웹 페이지, 문서, 이메일, API 응답을 통해 들어오는 문제다. 모델은 이 텍스트가 “데이터”인지 “명령”인지 완벽하게 구분하지 못한다.

따라서 방어는 하네스 층에 있어야 한다. 검색 결과를 그대로 도구 권한과 연결하지 않고, 도구 출력 정제, 권한 최소화, 위험 액션 승인, 네트워크 격리, 출력 검사를 조합해야 한다.

샌드박스는 실행 권한의 기본값이다

AI 코딩 에이전트가 파일을 읽고 셸 명령을 실행한다면 샌드박스는 선택이 아니다. 샌드박스는 모델을 믿지 않기 위한 장치가 아니라, 모델이 실수해도 피해 범위를 좁히기 위한 장치다.

OpenAI의 Codex 사례와 Anthropic의 다중 에이전트 사례는 모두 에이전트가 외부 도구를 직접 사용한다는 점을 보여준다 (출처: OpenAI Harness Engineering, Anthropic Engineering). 도구를 직접 쓴다는 것은 곧 권한 모델이 제품 품질의 일부가 된다는 뜻이다.

데이터 보존과 학습 사용 정책도 하네스 설계에 들어간다

데이터 정책은 벤더마다 다르므로 글에서 하나의 정책을 업계 표준처럼 말하면 안 된다. 예를 들어 OpenAI API 데이터 제어 문서는 2023년 3월 1일 이후 API로 보낸 데이터가 명시적으로 opt-in하지 않는 한 모델 학습에 쓰이지 않는다고 설명한다. 다만 abuse monitoring logs는 기본적으로 최대 30일 보존될 수 있으며, 일부 고객은 Zero Data Retention 또는 Modified Abuse Monitoring 대상이 될 수 있다 (출처: OpenAI Data Controls). 이 문장은 OpenAI API에 한정된 예시일 뿐이고, Anthropic, Google, Azure, 자체 호스팅 모델, 관측성 SaaS는 각각 보존·학습·감사 정책이 다르다.

이런 정책은 법무팀만의 일이 아니다. 어떤 트레이스를 저장할지, PII를 마스킹할지, 평가 데이터셋에 실제 고객 대화를 넣을지, 외부 SaaS로 관측성 데이터를 보낼지 모두 하네스 설계 결정이다.

권한은 자연어가 아니라 정책으로 관리한다

에이전트에게 “위험한 행동은 하지 마”라고 말하는 것은 필요하지만 충분하지 않다. 파일 삭제, 외부 전송, 결제, 고객 정보 조회, 배포, 권한 변경 같은 행동은 도구 호출 단계에서 별도 정책으로 걸러야 한다. 프롬프트가 아니라 하네스가 결정해야 하는 영역이다.

권한 정책은 최소 세 가지 값을 가져야 한다. 허용, 거부, 사람 승인 요청이다. 모든 것을 승인 팝업으로 보내면 사용자는 피로해지고, 모든 것을 허용하면 사고가 난다. 도구별 위험도와 데이터 민감도에 따라 기본값을 다르게 두는 편이 현실적이다.

하네스 성숙도는 어떻게 올릴까?

하네스는 한 번에 완성되지 않는다. 대부분의 팀은 수동 검토에서 시작해 골든셋, CI 게이트, 운영 트레이스, 거버넌스로 천천히 올라간다. 중요한 것은 지금 어느 단계인지 정확히 아는 것이다.

0단계: 감상 평가

0단계는 “몇 번 물어보니 괜찮아 보인다”는 상태다. 빠른 데모에는 충분하지만 제품에는 위험하다. 어떤 변경이 좋아졌는지, 나빠졌는지, 다시 재현할 수 없기 때문이다.

이 단계의 목표는 거창한 도구 도입이 아니다. 팀이 자주 묻는 질문과 과거 실패를 모아 평가셋으로 옮기는 것이다. 감상 평가를 데이터셋으로 바꾸는 순간 하네스가 시작된다.

1~2단계: 골든셋과 CI 게이트

1단계는 대표 입력을 모으고 기대 기준을 붙이는 것이다. 2단계는 그 기준을 CI에서 자동으로 돌리는 것이다. 이때부터 프롬프트 변경, 모델 변경, 검색 로직 변경이 배포 전에 검증된다.

초기에는 정확성보다 안정성이 중요하다. 모든 어려운 문제를 맞히는 것보다, 이미 고친 실패가 다시 나오지 않게 막는 것이 먼저다. 그래서 첫 CI 게이트는 작고 단호해야 한다.

3~4단계: 운영 학습과 거버넌스

3단계부터는 운영 트레이스가 테스트셋으로 돌아온다. 낮은 사용자 평가, 도구 오류, 긴 지연 시간, 정책 위반 가능성이 있는 출력이 자동으로 후보가 된다. 이 단계에서는 품질팀, PM, 도메인 전문가가 평가셋에 직접 관여할 수 있어야 한다.

4단계는 권한, 비용, 개인정보, 감사 로그가 하네스에 들어오는 단계다. 이 단계부터 AI 앱은 “잘 답하는 서비스”가 아니라 “운영 가능한 시스템”이 된다. 엔터프라이즈나 민감 데이터가 있는 제품은 이 단계를 늦게 붙이면 재작업 비용이 커진다.

어디까지 믿고, 어디부터 의심해야 할까?

하네스 엔지니어링은 만능 처방이 아니다. 오히려 좋은 하네스는 자신이 무엇을 모르는지 드러낸다. 평가 점수, 벤치마크, LLM 평가자, 관측성 대시보드를 모두 의심할 줄 알아야 한다.

벤치마크는 제품 품질이 아니다

공개 벤치마크는 모델의 대략적 능력을 보는 데 도움을 준다. 그러나 제품 품질은 내 데이터, 내 도구, 내 권한, 내 사용자의 실패 패턴에서 결정된다. 특히 코딩 에이전트 벤치마크는 어떤 실행 하네스, 어떤 도구, 어떤 제한 조건을 썼는지에 따라 달라진다.

Meta-Harness 논문은 모델 가중치뿐 아니라 어떤 정보를 저장, 검색, 제시하는 하네스 코드가 성능에 영향을 준다고 주장한다. 이 논문은 2026년 3월 arXiv preprint이므로 확정된 표준처럼 말하면 안 되지만, “같은 모델도 하네스에 따라 달라진다”는 방향성은 실무적으로 중요하다 (출처: Meta-Harness).

LLM 평가자는 감사 대상이다

LLM 평가자가 통과 판정을 줬다고 안전한 것이 아니다. 평가자도 모델이다. 루브릭을 오해하고, 긴 답변을 선호하고, 답변 순서에 영향을 받고, 특정 문체를 더 좋게 볼 수 있다. 그래서 사람이 채점한 작은 기준셋으로 평가자를 보정하고, 랜덤 샘플을 사람이 계속 확인해야 한다.

Braintrust도 흔한 평가 함정으로 과적합, 평가자 편향, 데이터 누수, 지표 게임, 엣지 케이스 무시, 감상 기반 평가를 꼽는다 (출처: Braintrust LLM Evaluation Guide).

관측성은 예방이 아니라 증거 수집에 가깝다

트레이스가 있다고 실패가 자동으로 사라지지는 않는다. 관측성은 “무슨 일이 있었는가”를 알려준다. 예방은 권한, 입력 검증, 데이터 품질, CI 게이트, 사람 승인 같은 다른 층과 결합할 때 가능하다.

그래서 하네스 엔지니어링의 성숙도는 대시보드 개수로 측정하면 안 된다. 운영 실패가 얼마나 빨리 재현 가능한 테스트가 되는지, 그 테스트가 다음 배포를 실제로 막는지로 봐야 한다.

FAQ: 하네스 엔지니어링에 대해 자주 묻는 질문은?

하네스 엔지니어링은 프롬프트 엔지니어링을 대체하나요?

대체가 아니라 포함한다. 프롬프트는 하네스 안의 한 부품이다. 하네스는 프롬프트에 더해 컨텍스트, 도구, 메모리, 평가, 관측성, 권한, 배포 게이트까지 설계한다.

작은 팀도 하네스 엔지니어링을 해야 하나요?

해야 한다. 다만 처음부터 대형 플랫폼을 도입할 필요는 없다. 실제 사용자 입력 25~50개, 규칙 기반 검사, 간단한 LLM 평가자, CI 실행, 운영 실패 추가 루프만으로도 시작할 수 있다.

LLM-as-a-judge만 쓰면 사람이 검토하지 않아도 되나요?

아니다. LLM 평가자는 확장성 있는 보조 평가자다. 위치 편향, 장황함 편향, 루브릭 오해가 있으므로 사람이 라벨링한 작은 샘플과 계속 비교해야 한다.

RAG 평가는 최종 답변만 보면 안 되나요?

최종 답변만 보면 원인을 놓친다. 검색이 틀렸는지, 검색은 맞았는데 답변이 근거를 벗어났는지, 질문 의도에 답하지 못했는지 분리해서 봐야 한다.

하네스 엔지니어링의 첫 번째 산출물은 무엇인가요?

작은 골든셋과 배포 차단 기준이다. 모델이나 프롬프트를 바꿀 때 이 골든셋을 다시 돌리고, 형식·근거성·안전성·비용 기준을 통과하지 못하면 배포하지 않는다.

벤치마크 점수가 높은 모델을 쓰면 하네스가 덜 필요하지 않나요?

오히려 더 필요하다. 강한 모델일수록 더 많은 도구를 쓰고 더 긴 작업을 맡게 되므로 실패 경로도 늘어난다. 모델 성능은 출발점이고, 제품 신뢰성은 하네스에서 완성된다.

결론: AI 제품의 품질은 어디서 완성되는가?

AI 제품의 품질은 모델 선택에서 시작하지만, 하네스에서 완성된다. 모델은 점점 좋아진다. 그러나 사용자 데이터, 도구 권한, 운영 트레이스, 평가셋, 배포 기준, 보안 정책은 각 팀이 직접 설계해야 한다.