하네스 엔지니어링이란? - 클로드 코드를 써보며

하네스 엔지니어링이란? AI를 잘 쓴다는 게 뭘까?

AI를 잘 쓴다는 게 뭘까

생성형 AI를 처음 쓰기 시작했을 때, 나는 프롬프트를 열심히 다듬었다. 역할을 부여하고, 출력 형식을 지정하고, 예시를 넣고, 그런데 프롬프트가 길어질수록 오히려 AI가 더 엉뚱한 답을 내놓는 경험을 했다. 그 다음엔 RAG를 파고들었고, 직접 서비스도 만들었다. 하지만 또 다른 한계에 부딪혔다.

그러다 Claude Code를 쓰면서 처음으로 "아, 이게 다른 차원이구나"를 느꼈다. 이 경험을 정리하다 보니 세 가지 개념이 보였다. 프롬프트 엔지니어링, 컨텍스트 엔지니어링, 하네스 엔지니어링이다.

 

 

1단계:  프롬프트 엔지니어링

AI한테 말 잘 거는 법

프롬프트 엔지니어링은 AI에게 입력하는 텍스트를 잘 설계해서 더 좋은 결과를 얻는 기술이다.

X) "파이썬 코드 짜줘"
X) "요약해 줘"
O) "당신은 10년 경력의 파이썬 개발자입니다. 초보자도 이해할 수 있도록 주석을 달아서, 파일을 읽고 CSV로 저장하는 코드를 작성해주세요."

 

역할 부여, 예시 제공, 단계적 사고 유도, 시스템 프롬프트 설정 같은 기법들이 여기에 해당한다.

 

프롬프트가 길어질수록 오히려 역효과

직접 써보면서 느낀 한계다 있다. 프롬프트가 길어질수록 오히려 역효과가 난다. 너무 많은 조건과 지시를 넣으면 AI가 그걸 다 처리하느라 정작 핵심 작업의 퀄리티가 떨어진다. 열심히 쓴 시스템 프롬프트가 오히려 AI의 지능을 깎아먹는 느낌이었다.

 

2단계:  컨텍스트 엔지니어링

AI에게 필요한 정보를 잘 전달하는 법

컨텍스트 엔지니어링은 AI가 답변하기 위해 필요한 정보를 얼마나 잘 제공하느냐에 관한 기술이다. 가장 대표적인 기법이 RAG(Retrieval-Augmented Generation)이다.

AI에게 질문하기 전에, 관련 문서를 먼저 검색해서 함께 전달하는 것

 

직접 RAG 기반 서비스를 만들어보면서 확실히 할루시네이션이 줄어드는 걸 느꼈다. AI가 모르면 지어내는 대신, 실제 문서를 기반으로 답변하게 되기 때문이다.

 

RAG도 만능은 아니었다

그런데 생각보다 쉽지 않았다. 질문과 관련된 문서를 제대로 찾아오는 것 자체가 어려웠고, 어렵게 문서를 찾아줘도 AI가 그걸 제대로 활용하지 못하고 딴소리를 하는 경우가 많았다. 정보를 잘 전달하는 것만으로는 부족했다.

결국 깨달은 건 이거였다. AI에게 정보를 전달하는 것과, AI가 그 정보를 가지고 실제로 뭔가를 할 수 있는 환경은 완전히 다른 문제다.

 

3단계:  하네스 엔지니어링

AI가 최대 성능을 낼 수 있는 환경을 만드는 법

하네스는 원래 말에게 채우는 마구를 뜻한다. 강력하지만 예측 불가능한 말을 올바른 방향으로 이끄는 장비가 하네스다. 즉, 하네스 엔지니어링이란 AI가 제 능력을 발휘할 수 있도록 주변 환경과 시스템 전체를 설계하는 것이다.

 

모델이 아니라 환경이 달라진 것

Claude Code를 써보면서 그 차이를 직접 느꼈다. 기존엔 코드를 하나씩 직접 읽으며 구조를 파악해야 했는데, Claude Code에서는 AI가 코드베이스를 스스로 읽고 필요한 파일을 찾아서 질의응답이 가능했다. 코드 분석부터 서비스 리팩토링까지, 내가 정보를 넣어준 게 아니라 AI가 스스로 필요한 걸 가져오는 환경이 만들어진 것이다. 모델이 달라진 게 아니라, 환경이 달라진 것이었다.

 

하네스가 결정하는 것들

구성요소	역할	Claude Code 예시
컨텍스트	무엇을 볼지 설계	코드베이스 자동 파악
도구	무엇을 할 수 있는지	파일 읽기/수정, 터미널 실행
제약	언제 멈출지	위험한 명령어 실행 방지
복구	잘못됐을 때	실행 결과 확인 후 재시도

 

마치며

AI를 잘 쓰는건 모델 선택이 아니다

프롬프트를 열심히 다듬던 시절, RAG 서비스를 직접 만들던 시저을 거쳐 하네스 엔지니어링을 경험하고 나니 한 가지가 명확해졌다.

AI를 잘 쓰는 건 더 좋은 모델을 고르는 게 아니다. 모델에게 말을 잘 걸고, 필요한 정보를 잘 전달하고, 모델이 최대 성능을 낼 수 있는 환경을 만드는 것이다. 이 세 가지를 이해하는 것만으로도 AI 활용 수준이 완전히 달라진다.