하네스 엔지니어링

AI 모델 자체가 아니라 모델을 감싸는 맥락·도구·가드레일·검증 구조를 설계하는 일이다. 같은 모델인데 프로젝트마다 결과가 들쭉날쭉하거나 에이전트에게 긴 작업을 맡길 때 쓰며, 프롬프트 하나가 아니라 에이전트 작업 전체를 다룬다는 점이 다르다.

하네스는 네 부분으로 이뤄진다

하네스라고 하면 거창해 보이지만, 실제로는 에이전트가 일하는 환경을 이루는 장치 몇 가지의 묶음이다. 모델을 바꾸지 않고 이 장치만 다시 짜도 결과가 눈에 띄게 좋아지는 경우가 많다.

Claude Code에서는 설정 파일로 짠다

Claude Code를 쓴다면 이미 하네스를 다루고 있는 셈이다. CLAUDE.md에 프로젝트 규칙과 코딩 컨벤션을 적어 두면 에이전트가 세션마다 그 맥락을 읽고 시작한다. 나머지 장치도 필요해질 때 하나씩 붙이면 된다.

에이전트를 직접 만들 때도 순서는 같다. 시스템 프롬프트로 역할과 제약을 잡고, 도구 정의로 할 수 있는 일을 정한 뒤, 출력 검증 루프로 잘못된 결과를 걸러 낸다.

오래 걸리는 작업은 '기록'이 핵심

몇 시간씩 이어지는 작업은 중간에 맥락이 끊기기 쉽고, 새 세션의 에이전트는 이전에 무엇을 했는지 모른다. 진행 상황을 적는 파일을 두고, 기능 하나를 끝낼 때마다 테스트를 돌린 뒤 git에 커밋하게 하면 다음 세션이 그 기록을 읽고 이어서 작업할 수 있다. 한 번에 다 하려 하기보다 작은 단위로 끝내고 넘기게 하는 구조가 실패를 줄인다.

처음엔 느슨하게, 문제가 생긴 곳만 조인다

하네스를 너무 빡빡하게 짜면 에이전트가 유연하게 대응하지 못하고, 너무 느슨하면 엉뚱한 방향으로 간다. 처음에는 최소한의 규칙만 두고, 실수가 실제로 반복되는 지점에 가드레일이나 검증을 하나씩 더하는 방식이 실용적이다. 규칙 문서가 길어지면 모델이 중요한 내용을 놓칠 수 있으니, 낡은 규칙은 정리해서 짧게 유지한다.

코딩 에이전트에서 가장 많이 쓴다

가장 흔한 건 코딩 에이전트의 작업 환경을 다듬는 일이다. 규칙 문서와 테스트만 잘 갖춰도 같은 모델이 훨씬 안정적으로 일한다.