하네스가 무엇인가요 — 말에 채우는 마구에서 클로드 코드까지

한눈에

• 하네스는 원래 말에 채우는 마구(馬具)입니다. 말은 그대로 두고, 둘레에 채워서 원하는 대로 부리는 장치입니다.
• 그 뜻이 그대로 넘어와 두 군데서 쓰입니다. 헷갈리는 게 당연합니다 — 저도 헷갈렸습니다.
• 하나는 「시험대」입니다. 진짜 코드는 그대로 두고 바깥 세상만 가짜로 만들어 시험합니다.
• 다른 하나는 클로드 코드 같은 「도구를 쥐여주는 껍데기」입니다. 모델은 혼자서는 글자만 만듭니다.
• 둘 다 뼈대가 같습니다 — 본체는 안 건드리고 둘레를 만든다.

자동매매를 만들면서 「하네스」라는 말을 쓰게 됐습니다. 그런데 클로드 코드를 쓰면서 또 그 말이 나왔습니다. 뜻이 달라 보였습니다.

찾아보니 둘 다 맞았습니다. 뿌리가 같고 갈라져 나온 것이었습니다. 그 이야기를 정리합니다.

원래 뜻 — 말에 채우는 마구

harness는 원래 말이나 개에게 채우는 장구를 말합니다. 우리말로 마구(馬具)입니다. 마차를 끄는 말에 채우는 가죽 띠와 줄, 강아지 산책시킬 때 몸통에 두르는 그것도 하네스입니다.

여기서 중요한 게 있습니다.

마구는 말을 바꾸지 않습니다. 말은 그대로 말입니다. 둘레에 무언가를 채워서 원하는 방향으로 가게 만들 뿐입니다.

이 뼈대가 그대로 넘어왔습니다. 「본체는 안 건드리고, 둘레를 만들어서 원하는 대로 부린다」 — 컴퓨터 쪽에서 하네스라고 부르는 것은 전부 이 모양입니다.

그런데 「무엇에 채우느냐」가 갈리면서 뜻이 둘로 나뉘었습니다.

첫째 — 코드에 채우는 하네스 (시험대)

제가 자동매매에서 쓰는 게 이쪽입니다.

프로그램을 고치면 잘 도는지 확인해야 합니다. 계산기라면 2 더하기 3을 눌러보면 됩니다. 그런데 자동매매는 돌리는 순간 진짜로 주식을 삽니다.

막아서는 게 셋이었습니다.

문제	무슨 뜻인가
돈이 나간다	한 번 돌릴 때마다 진짜 매매가 일어납니다
시간이 안 맞는다	장은 평일 낮에만 섭니다. 밤에 고친 건 다음 날까지 기다려야 합니다
상황을 못 만든다	「폭락하면 어떻게 되나」를 보려고 폭락을 기다릴 수는 없습니다

세 번째가 특히 답답합니다. 고장은 드문 상황에서 납니다. 그런데 그 드문 상황이 바로 기다려서는 만날 수 없는 상황입니다.

그래서 말에 마구를 채우듯 코드에 채웠습니다. 제 프로그램은 혼자 돌지 않습니다 — 증권사에 물어보고, 시계를 보고, 파일을 읽습니다. 그 바깥쪽을 전부 가짜로 바꿔치기했습니다.

「가짜 바깥 세상 + 진짜 프로그램 + 확인할 항목」 이 한 벌을 테스트 하네스라고 부릅니다. 우리말로는 시험대가 가깝습니다.

핵심은 프로그램 자신은 한 글자도 안 고친다는 것입니다. 시험대 위에 있는 줄도 모릅니다. 평소처럼 증권사에 주문을 넣고 평소처럼 시계를 봅니다. 그래서 시험에서 통과한 동작이 실제 동작과 같습니다.

가짜 증권사는 이렇게 생겼습니다

말로만 하면 감이 안 오니 실제 모습을 보여드리겠습니다. 제 가짜 증권사의 주문 부분입니다.

주문을 받으면 (종목, 수량, 값, 사는지 파는지)
  → 목록에 적어둔다
  → 「성공했습니다」라고 대답한다

어디에도 보내지 않습니다. 받아서 적어두고 성공했다고 대답할 뿐입니다.

그런데 이게 확인에는 충분합니다. 제가 알고 싶은 건 「증권사가 주문을 잘 처리하나」가 아니라 「내 프로그램이 이 상황에서 무슨 주문을 내는가」이기 때문입니다.

이런 상황을 만들어놓고 프로그램을 돌린다
→ 가짜 증권사가 적어둔 주문 목록을 꺼내 본다
→ 「살 것 한 건, 그것도 정확히 이 종목」이 맞는가

돈은 한 푼도 안 나가는데 「무엇을 하려 했는지」는 정확히 알 수 있습니다.

제일 많이 만든 가짜는 시계였습니다

이건 저도 세어보고 알았습니다. 검사 파일들이 만들어 쓰는 가짜를 종류별로 세어봤습니다.

가짜로 만든 것	쓰인 곳
시계	52곳 — 가장 많습니다
증권사	41곳
시세	15곳
화면	15곳

증권사보다 시계를 더 많이 가짜로 만들고 있었습니다.

생각해보면 당연했습니다. 앞 글에서 3시 20분에 무슨 일이 일어나는지를 다뤘는데, 그걸 확인하려고 매일 3시 20분까지 기다릴 수는 없습니다. 가짜 시계에 「지금은 3시 20분이다」라고 적어두면 프로그램이 그렇게 믿고 움직입니다.

제 가짜 시계에는 이런 주석이 붙어 있습니다.

시각을 평일로 고정 — 주말에 돌려도 시험대가 안 깨진다

이 한 줄도 그냥 나온 게 아닙니다. 토요일에 검사가 통째로 깨진 적이 있어서 붙인 것입니다.

둘째 — 모델에 채우는 하네스 (클로드 코드)

이제 헷갈리던 쪽입니다. 클로드 코드 같은 AI 도구에서도 하네스라는 말을 씁니다. 그런데 뜻이 달라 보입니다.

여기서 본체는 코드가 아니라 AI 모델입니다.

모델은 혼자서는 글자만 만들어냅니다. 파일을 읽지도 못하고, 명령을 실행하지도 못하고, 인터넷을 보지도 못합니다. 그냥 말을 만들어내는 것이 전부입니다.

그 둘레를 감싸서 실제로 일하게 만드는 껍데기 — 그게 에이전트 하네스입니다. 클로드 코드가 바로 그 하네스입니다.

하네스가 하는 일은 이렇습니다.

하는 일	무슨 뜻인가
도구를 쥐여준다	파일 읽기·쓰기, 명령 실행, 검색 같은 것을 쓸 수 있게 합니다
실제로 실행한다	모델이 「이 파일 읽어줘」라고 하면 하네스가 진짜로 읽어서 결과를 돌려줍니다
기억을 넣어준다	지금까지 대화, 규칙 파일, 열어본 파일을 함께 건네줍니다
권한을 관리한다	승인창을 띄우고, 거부하면 막습니다

여기서 알아두면 쓸모 있는 게 하나 있습니다.

같은 모델이라도 하네스가 다르면 할 수 있는 일이 달라집니다.

같은 클로드인데 웹에서 쓸 때와 클로드 코드로 쓸 때가 다르게 느껴지는 이유가 이것입니다. 모델은 같고 둘레가 다릅니다. 클로드 코드는 제 컴퓨터의 파일을 만지고 명령을 실행할 수 있게 채워둔 하네스입니다.

둘을 나란히 놓으면

	테스트 하네스	에이전트 하네스
본체	내가 만든 코드	AI 모델
둘레	가짜 증권사·시계·시세	도구·기억·권한
목적	돈 안 쓰고 시험하려고	글자만 만드는 것을 일하게 하려고
공통	본체는 안 건드리고 둘레를 만든다 — 말에 마구를 채우듯

그래서 두 뜻이 서로 틀린 게 아닙니다. 같은 생각을 다른 데 쓴 것입니다. 대화에서 「무엇에 채운 하네스인지」만 확인하면 헷갈리지 않습니다.

제 시험대는 처음엔 하나도 없었습니다

지금은 검사 파일 90개, 확인 항목 1,076개가 됐습니다.

그런데 처음부터 이랬던 게 아닙니다. 시작할 때는 하나도 없었습니다. 고치고 나서 눈으로 보고 「되네」 하고 넘어갔습니다.

검사가 하나씩 늘어난 건 거의 다 사고가 난 뒤였습니다. 무언가 깨질 때마다 「이건 다시는 몰래 지나가지 못하게 하자」며 붙였습니다.

그래서 이 1,076개는 제가 부지런해서 쌓인 게 아니라, 그만큼 당해서 쌓인 것입니다.

그리고 시험대도 고장 납니다

마지막으로 하나만 미리 말해두겠습니다.

시험대를 만들어놓으면 마음이 놓입니다. 「1,076개가 다 통과했으니 괜찮겠지」 싶어집니다. 그게 다음 함정입니다.

시험대는 제가 만든 것이라 저처럼 틀립니다. 가짜 증권사가 실제와 달라지기도 하고, 확인한다고 만든 항목이 아무것도 확인하지 않으면서 통과하기도 합니다.

실제로 저는 하루에 다섯 번 그 함정에 걸린 적이 있습니다. 다섯 번 다 프로그램이 고장 난 것처럼 보였는데 시험대가 고장 나 있었습니다.

그 이야기들은 이 연재 뒤쪽에서 따로 다루겠습니다. 지금은 「시험대가 있다」와 「그래서 안전하다」는 다른 말이라는 것만 남겨둡니다.

함께 읽으면 좋은 글

• 동시호가에 판 돈은 그날 못 씁니다 — 파는 건 장중에, 사는 건 마지막에
• 클로드 코드 기억 기능 — 「기억해둬」라고만 했더니 규칙이 3,840줄이 됐습니다
• CLAUDE.md 설정법 — 클로드 코드가 멋대로 코드를 고칠 때