에이전트 하네스

왜 하네스인가

LLM은 그 자체로는 강력하지만 불안정하다. 실행 사이에 맥락을 잃고, 그럴듯하게 틀리며, 잘못된 결과가 그대로 배포되는 걸 막아주는 것도 없다. 에이전트를 제품처럼 신뢰하려면 그 주위에 구조를 세워야 한다. 그 구조는 에이전트가 읽는 맥락, 통과해야 하는 검증, 닿을 수 있는 도구이고, 그 전체를 나는 하네스라고 부른다.

1 · 안정적인 맥락과 제약

프로젝트마다 Obsidian 기반 LLM 위키를 두는데, 단순히 쌓아두는 게 아니라 에이전트가 스스로 관리하고 발전시키도록 만들었다. 중요한 정보는 기록하고 불필요한 건 정리해서, 맥락이 세션 사이에 휘발하지도 쓸데없이 불어나지도 않고 또렷하게 누적된다. 그 위에 AGENTS.md와 CLAUDE.md가 작업 맥락과 에이전트가 지켜야 할 규칙을 적어두고, Claude Code skills가 반복하는 절차를 묶는다. 에이전트는 매번 프로젝트를 새로 배우는 대신 같은 바탕에서 일을 시작한다.

스스로 관리되는 LLM 위키

2 · 의도한 사양대로 에이전트 돌리기

나는 에이전트 옆에서가 아니라 에이전트와 함께 만든다. Claude Code의 각종 슬래시 커맨드, 그리고 울트라코드 모드의 dynamic workflow를 활용해, 한 프롬프트에 기대는 대신 에이전트를 작업에 돌려 의도한 사양으로 수렴시킨다. 일이 여러 에이전트로 갈라져 나갔다가 검증을 거쳐 돌아오므로, 큰 변경도 신중하게 간다.

3 · 메인까지 스스로 통과하기

어떤 것도 손대중으로 사용자에게 가지 않는다. 작업은 격리된 워크트리에서 릴리즈 브랜치로 흐르고, 거기서 사람이 dev 배포로 QA한 뒤에야 main으로 간다. release에서 main으로 넘어가는 길목은 세 겹(로컬 pre-push 훅·PR의 CI·브랜치 보호)으로 막혀 있고, 이 승격은 에이전트가 한 마디면 끝까지 돌린다. 그 게이트가 층층이 어떻게 작동하는지는 따로 한 편(배포 게이트)으로 다뤘다.

승격 흐름

1. Worktree

   feat/* · 격리 작업

   →

2. Release

   dev 배포 · 사람 QA

   →

3. PR + CI

   빌드·타입체크 · 깨끗한 머신

   →

4. main

   녹색일 때만 merge = prod

4 · 에이전트를 실제 도구에 연결

에이전트는 닿을 수 있는 만큼만 쓸모 있다. 나는 외부 도구를 MCP로 연결한다. 창작 파이프라인엔 이미지 생성 MCP를 물리고, 한 프로젝트에선 게임 엔진을 MCP로 직접 조종해 수정을 실제로 실행시켜 검증했다. MCP 외에도 시스템은 업무에 필요한 외부 API와 협업툴(Google Workspace 등)에 연결되고, 사내에선 AI 어시스턴트를 전사 단일 계정으로 보급해(Vercel AI SDK) 팀 전체가 개별 구독 없이 AI를 쓰게 했다.

5 · 배포가 끝이 아니다

배포는 운영이 시작되는 지점이다. 내가 운영하는 서비스는 이슈나 특정 이벤트가 발생하면 메신저로 알림을 보내서, 사용자보다 먼저 문제를 안다. 일상적인 데이터 분석은 아무도 안 여는 대시보드에 두는 대신 Google Chat 리포트로 보내고, 비용과 오류도 같은 식으로 지켜본다. 실제 사용에서 돌아오는 피드백이 다음 반복의 바탕이 된다.

증거는 이 레포에 있다

이 하네스를 이론으로 정리한 게 아니다. 그 구성요소가 실제로 이 레포 안에 있다. Obsidian 위키, 에이전트의 규칙을 정한 AGENTS.md와 CLAUDE.md, 그리고 모든 변경이 배포 전 통과하는 검증 게이트. 회사에서 운영하는 프로덕션 AI도 이런 구조와 검증 위에서 돌아간다. 결국 어려운 건 LLM을 쓰는 게 아니라, 믿고 배포할 만큼 안정적으로 만드는 쪽이었다.

지금 탐구 중

이 하네스는 지금 Claude Code 위에서 돈다. 강력하지만 닫힌 도구라, 오픈소스 쪽도 함께 테스트해 왔다. 매일 도는 내 AI Trend Notifier가 Nous Research의 오픈소스 자기개선형 에이전트 Hermes Agent를 짚어 줬는데, 닫힌 하네스의 오픈 대안이다. 이걸 오픈·자체호스팅·상시 구성으로 옮겨 같은 검증 중심 워크플로우를 돌려 봤고, 그 과정은 따로 한 편(자체호스팅)으로 다뤘다.