Skip to main content
블로그로 돌아가기
계속 변화하는 Claude Code 완료 신호: 무중단 감지를 구현한 엔지니어링 이야기
블로그

계속 변화하는 Claude Code 완료 신호: 무중단 감지를 구현한 엔지니어링 이야기

터미널 텍스트의 키워드 매칭은 왜 필연적으로 깨질 수밖에 없는가? MadoHub가 백엔드 세션 감시자(Watcher)와 구조적 정규식의 이중 트랙으로 안정적인 완료 판정을 내리는 방법.

멀티 에이전트 오케스트레이션에서 MadoHub는 에이전트가 현재 턴을 마치는 순간을 밀리초 단위로 정확히 포착해야 합니다. 타일의 상태를 working에서 done으로 전환하고, 연결된 다운스트림 에이전트가 안전하게 산출물을 가져가도록 라우팅 트리거를 당기는 핵심 신호이기 때문입니다.

초기 버전에서 Claude Code의 작업 완료를 판별하는 방식은 단순한 문자열 매칭이었습니다. 하지만 Claude Code가 업데이트되면서 터미널에 출력하는 동사를 바꾸자마자 감지 로직은 즉시 무력화되었습니다.

이 글에서는 깨지기 쉬운 키워드 하드코딩을 폐기한 과정과, 정규식 개선을 넘어선 근본적인 해결책을 어떻게 설계했는지 설명합니다.

문제의 본질

어휘 목록은 언젠가 반드시 깨집니다

Claude Code는 턴을 완료할 때 터미널에 ✽ Worked for 2m 30s와 같은 한 줄짜리 완료 배너를 출력합니다. 1세대 감지기는 당시 특정 버전이 출력하던 두 개의 구체적인 동사—Sautéed와 Cogitated—를 매칭하도록 하드코딩되어 있었습니다. 특정 단어가 감지되면 타이머를 시작하고 라우팅을 실행하는 단순한 방식이었습니다.

하지만 Anthropic이 CLI에 개성을 더하기 위해 Worked, Churned, Sautéed, Cogitated 등 다양한 재치 있는 동사들을 무작위 순환 풀에서 출력하기 시작하면서 문제가 발생했습니다.

어휘 목록이 바뀔 때마다 키워드 매칭은 조용히 실패했고, 개발자가 이를 발견하고 새 단어를 수동으로 추가하기 전까지는 완료 상태를 전혀 감지하지 못했습니다.

움직이는 표적을 한정된 단어 목록으로 뒤쫓는 것은 필패의 게임입니다. 해결책은 구체적인 단어가 무엇인지 신경 쓰지 않는 것이었습니다.

특정 단어가 아닌 구조적 형태(Shape)를 매칭하기

매주 어떤 새로운 동사가 추가되더라도 모든 완료 배너는 일관된 구조를 유지합니다: 행 시작 부분의 특정 글리프(Glyph), 대문자로 시작하는 과거형 동사, 고정된 for 접속사, 그리고 소요 시간 단위.

이 구조적 형태를 기준으로 매칭하면 앞으로 어떤 생소한 동사가 등장하더라도 코드 수정 없이 지속적으로 감지가 유지됩니다.

특히 글리프가 행의 맨 처음에 위치해야 한다는 조건은 필수적입니다. 터미널 출력에는 Retried for 3s(재시도 로그)나 Waited for 5s(빌드 대기 로그)처럼 '동사 + for + 시간' 패턴을 띠지만 실제 작업 완료와는 무관한 비정형 로그가 무수히 많기 때문입니다.

MadoHub의 이중 트랙 감지 아키텍처

화면 매칭은 가속기일 뿐, 최종 판정이 아닙니다

터미널 화면 패턴 매칭은 MadoHub가 완료를 판단하는 유일한 수단이 아닙니다. 이는 시각적 반응성을 극대화하기 위한 **지연 시간 단축용 가속기(Accelerator)**에 가깝습니다.

가장 신뢰할 수 있는 최종 권한은 Claude Code의 로컬 세션 트랜스크립트(Transcript) 로그를 직접 읽어내는 **백엔드 핵심 감시자(Watcher)**에 있습니다.

  • Watcher는 로그의 마지막 메시지를 실시간으로 분석합니다. 보류 중인 도구 호출이 없는 순수 어시스턴트 메시지라면 에이전트의 작업이 완료된 것입니다.
  • 사용자 메시지, 진행 중(progress) 메시지, 도구 실행 중인 메시지라면 에이전트는 여전히 실행 중으로 판단됩니다.

애플리케이션은 트랜스크립트 파일에 기반한 '절대적 사실'과 터미널 스크린 덤프에 기반한 '추정'을 엄격히 구분하여 신뢰도 플래그를 관리합니다.

심층 방어: 오탐(False Positive)의 철저한 배제

너무 엄격한 감지(미탐 가능성)와 너무 느슨한 감지(오탐 가능성) 사이에서, MadoHub는 엄격함을 선택했습니다.

화면 매칭을 놓치더라도 백엔드 Watcher가 밀리초 뒤에 진정한 완료 신호를 확정해 주므로 시스템에 무해합니다. 하지만 잘못된 완료 판정은 작업 중간에 미완성 산출물을 다음 에이전트로 잘못 라우팅하는 치명적인 문제를 일으킵니다.

따라서 화면 매칭이 'done'을 가리키더라도 활성 Watcher가 'working' 상태를 보고하고 있다면, MadoHub는 화면 판정을 과감히 폐기합니다. Watcher의 판정이 언제나 최종 결정권을 갖습니다.

실무 권장 사항

  • 동사 단어에 의존하지 마세요: Claude Code의 완료는 문법적 형태와 세션 트랜스크립트로 추적하는 것이 가장 안전합니다.
  • 상태의 순간적인 재조정은 정상 동작입니다: 타일이 'done'으로 뒤집혔다가 순간적으로 'working'으로 되돌아오는 경우가 있다면, 이는 Watcher가 성급했던 화면 판정을 바로잡는 자기 치유 과정입니다.
  • MadoHub의 상태 머신 신호를 신뢰하세요: 커스텀 플로우를 구축할 때는 원시 터미널 텍스트를 파싱하려 하지 마시고 MadoHub가 보장하는 공식 상태(Working / Done / Failed)를 기반으로 라우팅을 설계하세요.

관련 문서