AI 에이전트, 프롬프트 대신 '하네스'로 길들인다

본문에서는 프롬프트 엔지니어링(Prompt Engineering)의 한계를 지적하며, AI 에이전트의 신뢰성을 확보하기 위한 새로운 접근법으로 하네스 엔지니어링(Harness Engineering)을 제시한다. 프롬프트는 결국 '부탁'에 불과하며, 에이전트가 지시를 따르지 않는 경우가 발생한다. 이러한 문제를 해결하기 위해, 에이전트가 실행되는 환경 자체를 설계하고, 시스템 레벨에서 에이전트의 동작을 강제하는 하네스 엔지니어링을 도입했다. 이는 AI 환각(Hallucination)을 방지하고, 일관된 결과를 보장하기 위한 핵심 전략이다.

하네스 엔지니어링의 핵심은 Claude Code의 hooks를 활용한 시스템 레벨 가드레일(Guardrail) 구축이다. hooks는 에이전트의 생명주기(세션 시작, 도구 실행 전/후, 응답 완료 등)에 셸 스크립트나 LLM 판단을 끼워 넣을 수 있는 메커니즘이다. command 훅은 속도가 빠르고 확실하게 알려진 패턴을 차단하며, prompt 훅은 LLM 호출을 통해 의미를 이해하고, 정규 표현식(Regex)이 놓치는 부분을 보완한다. 이러한 이중 구조는 안전성과 유연성을 동시에 확보하는 전략이다.

code-forge는 멀티모델 지원을 위해 AGENTS.md를 활용한다. AGENTS.md는 AAIF(Agentic AI Foundation) 표준에 맞춘 파일로, Claude, Codex, Cursor 등 다양한 모델이 공통적으로 이해할 수 있는 에이전트 설정 표준을 제공한다. 이를 통해, 모델 간의 편향성(Bias)을 줄이고, 코드 품질을 향상시킬 수 있다. 또한, /setup을 통해 스택을 자동 감지하고, CLAUDE.md를 생성하여, 각 모델에 맞는 설정을 적용한다.

저자는 런타임 해석 방식의 복잡성을 해결하기 위해, 빌드타임 컴파일 방식을 도입했다. 기존에는 매 세션마다 규칙 파일을 주입하고, spawn할 때마다 STATE 체인을 재귀적으로 재계산하는 방식을 사용했다. 하지만, 빌드타임에 STATE+ACT 체인을 미리 계산해 정적 .md 파일로 만들어, 런타임 인프라를 제거했다. 이는 시스템의 복잡성(Complexity)을 줄이고, 성능을 향상시키는 효과를 가져왔다. 빌드 타임(Build Time)에 컴파일함으로써, 런타임 오버헤드를 줄였다.

하네스 엔지니어링은 단순화와 실동작을 통해, AI 에이전트의 성능과 안정성을 향상시켰다. 6단계 사고 모델을 4단계로 단순화하고, 런타임 해석 방식을 빌드타임 컴파일 방식으로 변경했다. 또한, 껍데기뿐이었던 스텁(Stub)을 실제 동작으로 채워, 시스템의 신뢰성을 높였다. 이러한 변화는 코드 품질(Code Quality) 향상과 유지보수성 개선으로 이어졌다. 특히, exit 0 스텁을 9개 패턴을 차단하는 가드레일로 바꾸고, Stop hook을 quality-gate.sh로 구현한 점이 주목할 만하다.

저자는 멀티모델 협업을 통해, AI 에이전트의 성능을 더욱 향상시키고 있다. Claude와 Codex, Critic 에이전트 간의 토론을 통해, 코드의 품질을 개선하고, 단일 모델의 편향성을 극복한다. 이는 AI 에이전트가 다양한 관점을 수용하고, 더욱 정확하고 신뢰할 수 있는 결과를 도출하도록 돕는다. 하네스 엔지니어링은 AI 에이전트의 지속적인 발전(Continuous Improvement)을 위한 핵심적인 방법론으로 자리 잡을 것이다.