펫프렌즈 물류 개발팀, Slack 봇 '창식'에 하네스 엔지니어링 도입

펫프렌즈 물류 개발팀은 Slack 봇 '창식'에 하네스 엔지니어링(Harness Engineering)을 적용하여, 장기·복잡한 작업의 정확성을 높임

지식 베이스(Knowledge Base), 규칙 인덱스(Rule Index), 교정 로그(Correction Log)를 활용하여 봇의 운영 품질을 개선하고, 컨텍스트 품질(Context Quality)을 향상시킴

MCP 채널(MCP Channel)을 통해 Slack과 Claude Code를 연결하는 아키텍처를 구축하고, CLI와 SDK 두 가지 실행 모드를 지원하며, 3계층 메모리 구조를 활용

하네스 엔지니어링(Harness Engineering)의 핵심 원리

본문에서는 하네스 엔지니어링(Harness Engineering)을 AI 에이전트의 안정적인 운영을 위한 환경, 컨텍스트, 피드백 루프 설계로 정의한다. 에이전트 루프 설계보다 컨텍스트 품질(Context Quality)이 중요하며, 공유 컨텍스트(Single Source of Truth)를 통해 모든 봇이 동일한 지식 베이스(Knowledge Base)에서 출발하도록 설계했다.

공유 컨텍스트(Single Source of Truth): 모든 봇이 동일한 규칙과 안전 지침을 공유하며, 수정 시 즉시 반영

규칙 경량화(Progressive Disclosure): CLAUDE.md는 인덱스 역할만 수행하고, 세부 내용은 필요 시 로드하여 컨텍스트 소비 최소화

점진적 정제(Permanent Correction): 실수 발생 시 교정 로그(Correction Log)에 기록하고, 다음 작업부터 자동 적용

MCP 채널(MCP Channel)을 활용한 Slack ↔ Claude Code 연동

Slack과 Claude Code를 연결하기 위해 MCP 채널(Model Context Protocol)을 사용하며, 이는 Claude Code 외부에서 발생한 이벤트를 세션 안으로 밀어넣는 역할을 한다. 일반 MCP 서버와 달리 claude/channel capability를 선언하여 Claude Code가 notification 리스너를 등록한다.

MCP 채널(MCP Channel)의 특징: 외부 이벤트가 Claude 세션으로 push (push) 방식으로 전달

연결 구조: Claude Code는 .mcp.json 설정을 읽고 slack-channel을 subprocess로 실행하며, 통신은 stdio로 이루어짐

중요 사항: stdout/stderr 분리, 모든 로그는 process.stderr.write()로 출력

이러한 구조를 통해 Slack 메시지를 Claude Code로 전달하고, 봇이 응답할 수 있도록 한다.

CLI와 SDK, 두 가지 실행 모드

창식 봇은 CLI와 SDK, 두 가지 실행 모드를 지원하여 봇의 특성에 맞는 유연성을 제공한다. CLI 모드는 깊은 코드 분석에 적합하며, SDK 모드는 동시 처리에 유리하다.

CLI 모드: tmux 세션에서 claude CLI 실행, 단일 세션으로 컨텍스트 유지, 슬래시 커맨드, 훅, 서브에이전트 사용 가능

SDK 모드: Python 기반 공유 런타임, 스레드별 독립 세션 생성, 최대 5개 세션 동시 처리, APScheduler 내장

3계층 메모리: 장기, 중기, 단기 메모리를 활용하여 지속적인 학습과 개선을 가능하게 한다.

두 가지 모드를 통해 다양한 환경에서 봇을 운영할 수 있도록 지원한다.

운영 도구 및 봇 구조

창식 봇은 봇 라이프사이클 관리, 대시보드, 3계층 메모리 구조를 통해 운영 효율성을 높인다. 봇은 Sentry 에러, Loki 로그 통합 분석, Tempo + Loki 연계 분석 등을 통해 문제 해결 능력을 향상시킨다.

봇 라이프사이클 관리: python3 manage.py start, status, restart, attach, watch 명령어를 통해 봇 관리

대시보드: 봇 상태 및 LLM 자체 메트릭 관측

3계층 메모리: 장기(CLAUDE.md + knowledge/), 중기(docs/memory.md), 단기(Slack 스레드)를 활용

지속적인 운영 개선**을 위해, 봇의 상태를 모니터링하고, 문제 발생 시 빠르게 대응할 수 있는 환경을 구축했다.

하네스 엔지니어링(Harness Engineering)의 가치

하네스 엔지니어링(Harness Engineering)은 특별한 기술이 아닌, 좋은 프롬프트와 운영 원칙을 코드와 파일 구조로 체계화하는 것이다. 봇별 격리, 브랜치 관리, 운영 도구를 통해 차별성을 만든다. 복잡한 에이전트 루프보다 좋은 컨텍스트와 정제된 규칙이 결과를 결정한다.

봇별 격리: 봇별로 지식 베이스를 격리하여 간섭을 방지

브랜치 관리: 봇의 코드와 규칙을 브랜치로 관리하여 버전 관리 및 협업 용이

운영 도구: 봇의 라이프사이클 관리, 상태 모니터링, 문제 해결을 위한 도구 제공

결과적으로, 하네스 엔지니어링은 AI 에이전트의 성능과 안정성을 향상시키는 핵심 요소이다.