하네스 엔지니어링 튜토리얼 #1 — 모델을 바꿨는데 왜 똑같을까요

새 모델이 나오면 저는 대체로 바로 갈아탑니다. 이번엔 다르겠지, 하면서요. 그런데 며칠 지나면 비슷한 자리에 서 있는 걸 여러 번 겪었어요. 결과가 좋아진 것 같기도 하고, 아닌 것 같기도 하고요.

한동안은 제가 뭘 잘못 쓰고 있나 싶었어요. 그런데 지금은 조금 다르게 생각하고 있어요.

도구를 바꿔도 그대로인 것

이런 일이 있었어요.

같은 작업을 시켰는데 어제는 잘 됐고 오늘은 이상하게 나왔어요. 프롬프트는 똑같았어요. 복사해서 붙여넣었으니까요. 그래서 모델을 더 좋은 걸로 바꿔봤어요. 그래도 비슷했어요.

한참 뒤에 원인을 찾았는데, 도구가 참고하던 파일 하나가 낡아 있었어요. 예전에 폐기한 규칙이 그 안에 남아 있었던 거예요. 도구는 그걸 성실하게 읽고, 성실하게 틀린 답을 냈어요.

모델을 바꾼다고 그 파일이 고쳐지진 않죠. 그래서 아무리 좋은 모델로 갈아타도 같은 자리였던 거예요.

저는 이 경험 뒤로 규칙을 하나 만들었어요. 결과가 나쁘면 모델부터 바꾸지 말고 환경부터 본다. 지금은 아예 시스템에 적어두고 삽니다. "응답 품질이 낮다", "더 좋은 모델로 바꾸자" 같은 말이 나올 때 먼저 점검할 목록이 뜨게 해뒀어요.

점검 목록은 세 개예요.

하나, 필요한 정보에 접근이 되는가. 도구가 참고해야 할 문서가 실제로 읽히고 있는지, 그 내용이 최신인지 보는 거예요. 제 경우엔 여기서 걸렸어요.

둘, 도구 연결이 멀쩡한가. 캘린더나 문서함처럼 바깥 서비스에 손이 닿아야 하는 작업이라면, 그 연결이 살아 있는지 봅니다. 인증이 만료돼서 조용히 실패하고 있는 경우가 생각보다 흔해요.

셋, 일하는 순서가 제대로 짜여 있는가. 검증 없이 결과만 뱉게 해뒀는지, 끝나는 조건 없이 무한히 돌게 해뒀는지 같은 것들이요.

모델 교체는 그다음이에요. 그리고 대개 그 앞에서 해결됩니다.

하네스라는 말

이 "환경"을 부르는 이름이 있어요. 하네스(harness)라고 해요.

원래는 말에게 씌우는 마구를 뜻해요. 말의 힘을 없애는 게 아니라, 그 힘이 엉뚱한 데로 새지 않고 수레로 전달되게 만드는 장치죠. 소프트웨어 쪽에서 이 말을 가져다 쓰기 시작한 건 몇 해 안 됐어요. 그래서 아직 사람마다 조금씩 다르게 씁니다.

정의는 단순해요. 모델을 감싸고 있는 모든 것. 모델에게 무엇을 알려주는지, 무엇을 만지게 허락하는지, 결과를 누가 검사하는지, 잘못됐을 때 어떻게 되돌리는지.

여기서 자주 오해가 생겨요. 하네스라고 하면 뭔가 대단한 시스템을 상상하는데, 실체는 대개 문서 몇 장과 설정 몇 줄이에요.

구체적으로 말씀드릴게요. 클로드 코드를 쓰신다면 하네스는 이런 것들입니다.

• CLAUDE.md — 프로젝트 폴더에 두는 지침 파일이에요. 도구가 매번 자동으로 읽습니다. "우리 팀은 이런 걸 하고, 이 규칙을 지키고, 이건 하지 마라"를 적어두는 자리예요. 이름이 정해져 있어서 그 이름으로 만들기만 하면 됩니다.
• 훅(hook) — "이 조건이 되면 자동으로 이걸 실행해라"를 걸어두는 설정이에요. 저장할 때마다 검사를 돌린다든지요. 설정 파일에 몇 줄 적으면 됩니다.
• 권한 설정(permissions) — 무엇을 물어보지 않고 해도 되고, 무엇은 반드시 확인받아야 하는지의 목록이에요.
• 스킬(skill) — 반복 업무의 절차서예요. 마크다운 문서 한 장이 곧 스킬입니다.

전부 사람이 읽을 수 있는 문서고, 코드가 아니에요. 이게 이 시리즈의 전제이기도 해요. 하네스는 프로그래밍이 아니라 문서 작성에 가깝습니다.

사다리 하나

지금 우리가 어디 서 있는지 보려면 사다리를 하나 그려보면 좋아요. 요즘 나오는 말들이 대충 이 순서로 쌓입니다.

프롬프트 엔지니어링(prompt engineering). 좋은 지시를 한 번 잘 쓰는 법이에요. 우리가 제일 먼저 배우는 거죠. 실제로 하는 일은 채팅창에 문장을 다듬어 넣는 겁니다.

컨텍스트 엔지니어링(context engineering). 그 한 번의 실행에 올바른 정보를 공급하는 법이에요. 무엇을 읽히고 무엇을 빼둘지 고르는 일이요. 실제로 하는 일은 참고 문서를 붙여주거나, 반대로 필요 없는 걸 치워서 도구가 헷갈리지 않게 하는 겁니다.

하네스 엔지니어링(harness engineering). 그 실행 한 번이 안정적으로 나오게 만드는 법이에요. 어제도 되고 오늘도 되게 하는 것. 실제로 하는 일은 방금 말씀드린 지침 파일·훅·권한을 설계하는 겁니다. 이번 시리즈가 여기예요.

한 칸씩 올라갈 때마다 다루는 단위가 커져요. 문장에서 정보로, 정보에서 환경으로요. 그리고 위로 갈수록 결과에 남는 게 많아집니다. 프롬프트는 창을 닫으면 사라지지만, 환경은 내일도 거기 있으니까요.

사다리 위에 한 칸이 더 있는데, 그건 나중에 다른 시리즈에서 다룰게요.

네 개의 기둥

하네스를 뜯어보면 하는 일이 네 가지더라고요. 저는 이걸 기둥이라고 불러요. 이번 시리즈는 사실상 이 네 기둥을 하나씩 세우는 이야기예요.

알린다(inform). 도구가 무엇을 아는가. 내 일의 배경, 지켜야 할 규칙, 결과물의 모양. 실물로는 아까 말한 CLAUDE.md 같은 지침 파일이 여기 해당해요. 이걸 안 적어두면 도구는 매일 첫 출근한 사람처럼 굽니다.

제한한다(constrain). 도구가 무엇을 만질 수 있는가. 읽기만 시킬지, 파일을 고치게 할지, 바깥으로 뭔가 내보내게 할지. 실물로는 권한 설정과 "이건 반드시 물어보고 해라" 목록이에요. 이건 나중에 이야기하겠지만, 제가 사고를 한 번 크게 겪고 나서야 제대로 그린 부분이에요.

검증한다(verify). 결과가 맞는지 누가 보는가. 여기서 중요한 건, 만든 쪽이 채점하면 안 된다는 거예요. 도구는 자기 결과에 후한 점수를 줍니다. 실물로는 별도의 검사 도구를 붙이거나, 만든 것과 다른 쪽에 검수를 맡기는 구조예요.

교정한다(correct). 틀렸을 때 어떻게 되돌리는가. 그리고 같은 실수를 다시 안 하게 어떻게 장치를 거는가. 실물로는 훅이 여기예요. 사람의 의지 대신 조건으로 거는 겁니다.

알리고, 제한하고, 검증하고, 교정한다. 네 개예요. 외우실 필요는 없어요. 한 편씩 다룰 거니까요.

이 시리즈에서 하려는 것

솔직히 말하면 하네스 이야기는 이미 많아요. 저도 여러 개 봤고, 이 시리즈를 쓰면서 제 자료를 다시 뒤졌더니 관련된 게 오십 건 넘게 나왔어요.

그래서 개념 설명을 한 번 더 하는 건 의미가 없다고 생각했어요.

대신 제가 할 수 있는 게 하나 있어요. 저는 이걸 제 시스템에 실제로 걸어놓고 살고 있고, 그 결과를 숫자로 재봤고, 꽤 많이 실패했어요.

규칙을 잘못 걸어서 도구가 제 작업을 오히려 방해한 적이 있어요. 잘 돌던 자동화가 조용히 죽어 있는 걸 한참 뒤에 안 적도 있고요. 감시하라고 만든 장치가 정작 아무 말도 안 한 적도 있어요. 검사기를 하나 붙였더니, 그 검사기가 처음으로 잡아낸 오류가 검사기 자신의 버그였던 적도 있어요.

그래서 매 편에 제가 직접 재본 숫자나 직접 겪은 실패를 하나씩 넣으려고 해요. 그게 없는 편은 안 쓸 거예요. 그러면 그냥 남의 이야기를 옮기는 게 되니까요.

마지막에 뒤집을 이야기 하나

미리 예고를 하나 할게요. 그래야 이 시리즈를 오해 없이 읽으실 것 같아서요.

지금부터 저는 환경을 만들라고, 규칙을 적어두라고, 장치를 걸라고 계속 말할 거예요. 그런데 마지막 편에서 그걸 상당 부분 뒤집을 거예요.

하네스는 쌓을수록 좋은 게 아니거든요. 규칙이 늘어나면 어느 순간부터 도구가 일을 하는 대신 규칙을 지키느라 바빠져요. 문서를 스무 장 읽고 나서 정작 시킨 일은 대충 하는 거죠.

그리고 모델이 좋아질수록, 예전에 필요했던 보조 장치들이 오히려 걸림돌이 됩니다. 손이 서툰 사람에게 필요했던 보조기구가 익숙해진 사람에게는 방해가 되는 것과 같아요. 저는 실제로 한번 크게 덜어내야 했어요.

그러니 이 시리즈는 짓는 이야기이면서 동시에 덜어내는 이야기예요. 짓는 법을 모르면 덜어낼 수도 없어서, 짓는 것부터 시작할 뿐이에요.

결과가 마음에 안 들 때, 모델을 먼저 의심하지 마세요. 대개 답은 그 옆에 있습니다.

---

📌 오늘 해볼 것

최근에 도구가 이상하게 굴었던 일을 하나 떠올려 보세요. 그리고 그때 모델을 바꾸면 풀렸을 문제였는지 자문해 보세요. 아니라면, 그게 바로 하네스 문제예요. 무엇이 없어서 그랬는지 한 줄만 적어두시면 다음 편에서 이어가요.

🗓 다음 편

첫 번째 기둥, 알리는 일부터 시작해요. 그런데 저는 이 편의 제목을 이렇게 붙였어요 — 적어두지 않은 규칙은, 없는 규칙이에요.

---