이전 기사: https://zenn.dev/satoh_y_0323/articles/e98658522364d5

C3 GitHub: https://github.com/satoh-y-0323/claude-code-conductor / PyPI: https://pypi.org/project/claude-code-conductor/ / 공식 문서: https://satoh-y-0323.github.io/claude-code-conductor/

본 기사의 범위: 자체 제작한 멀티 에이전트 프레임워크(Multi-Agent Framework) C3 (Claude Code Conductor)의 v2.43.0 이후 ~ 현재 (v2.44.0 + 배포 외 개발 도구 1개). 하루 동안의 일입니다. 테마는 「사양과 실태의 괴리를 양방향에서 동시에 겪었다」 ── 하네스(Harness, Claude Code 본체)는 문서에 없는 동작을 하고 있었고, 나의 hook은 사양에 없는 출력을 하고 있었다. 그리고 그 양쪽 모두를 알아차린 것은 changelog가 아니라 실측이었습니다.

서론 ── 스마트폰 화면에 나타난 낯선 경고

그날, 저는 외출 중이었습니다. C3의 수정 워크플로우(Workflow)는 원격 조작으로 Claude Code에 위임해 둔 상태였고, 스마트폰으로 경과를 지켜보며 동작 확인을 위해 /compact (대화 압축)를 1회 실행했습니다. 수정 성과는 제대로 나와 있었습니다. 의도한 대로입니다.

다만, 그 성공 보고 바로 옆에 낯선 한 줄이 나타나 있었습니다.

⎿ PreCompact hook error: Hook JSON output validation failed

수정하고 싶었던 버그는 고쳐졌습니다. 하지만 다른 무언가가 망가져 있습니다. ── 아니, 정확히 말하면 이것은 '망가진' 것이 아니었습니다. 조사 결론을 먼저 말씀드리면,

이 hook의 출력은 공식 사양에 처음부터 존재하지 않았습니다. 즉, 「주입하려 했던 지시」는 계속 전달되고 있었다는 보장이 없었습니다.

「작동하고 있다고 생각했던 기능이 사실은 사양 외였고, 검증이 들어간 날 조용히 죽어 있었다」. 이번에는 이 시원하면서도 찝찝한 하루의 기록입니다.

제1화 ── checkpoint가 1회의 compact로 4개씩 증가하다

이야기는 같은 날 아침부터 시작됩니다. 전날의 「솔직한 의견을 들려줘」 평가(이전 기사)의 부산물로서, 개선 백로그(Backlog)의 최상단에 이런 항목이 있었습니다.

세션 기록 파일에 PreCompact checkpoint가 1회의 compact당 4블록씩 퇴적되고 있다. 심한 날은 파일의 약 80%(60블록 초과)가 이 노이즈로 채워져, 다음 세션 복원 시 읽어들여야 할 컨텍스트(Context)를 낭비하고 있었다.

C3는 compact 직전에 hook (pre_compact.py)을 통해 「현재 위치」의 checkpoint를 세션 파일에 1행 추가합니다. 구현상으로는 누가 봐도 「1 실행 = 1 추가」입니다. 중복 등록도 확인했지만, hook 등록은 한 곳뿐이었습니다. 그렇다면──

하네스가 1회의 compact에서 동일한 hook을 4번 호출하고 있다.

타임스탬프(Timestamp)를 나열해 보면, 약 40~60ms 간격의 쌍×2 (두 번째 쌍은 약 1초 후). 게다가 payload의 context_items가 N/A → 0 → 10 → 10으로 호출마다 다릅니다. 단순한 이중 전달이 아니라, 하네스 내부의 여러 국면에서 호출되고 있는 듯합니다. 공식 문서에는 이 동작에 대한 기재가 없습니다. 문서화되지 않은(undocumented) 동작입니다.

여기서 취할 수 있는 태도는 두 가지입니다. 「하네스의 버그이니 고쳐질 때까지 기다리자」 혹은 「호출 방식은 제어할 수 없으니, 내 쪽을 멱등(Idempotent)하게 만들자」입니다. 과거 로그를 조사하니 실제 compact 이벤트 간의 최단 간격은 25초, 동일 이벤트 내의 중복 호출은 최대 1.2초였습니다. 즉, **10초의 디바운스 윈도우(Debounce window)**를 두면, 실제 이벤트를 하나도 놓치지 않고 중복 호출을 확실히 하나로 합칠 수 있습니다. C3 측에서 대처하는 것이 옳습니다.

수정 자체는 「추가하기 전에 직전 checkpoint의 타임스탬프를 읽고, 10초 이내라면 스킵. 읽을 수 없으면 추가한다 (fail-open)」 뿐입니다. 하지만 이것을 C3의 표준 워크플로우(리뷰 지적 0건까지 반복)로 돌렸더니, 3 사이클이 걸렸습니다.

• code-review 7건 → 수정 → security-review 3건 → 수정 → 재리뷰에서 신규 3건 → 수정 →
  0건 - security-review의 실측 결과가 흥미로웠는데, 제가 처음에 작성한 checkpoint 행 파싱용 정규 표현식에 대해 "
  조작된 5만 자의 행으로 69초간 행(hang) 발생(ReDoS)"을 실제로 측정하여 High 등급으로 지적받았습니다. 정규 표현식을 버리고 rfind를 이용한 절차적 파싱으로 다시 작성했습니다. - "미래 시점의 checkpoint가 섞여 들어오면 디바운스(debounce)가 영구적으로 정지한다"는 지적에는 미래 시점의 거부(rejection)를 구현했는데── 그러다 그 수정 과정에서 실수를 저질렀습니다.
  테스트가 통과되지 않는다는 이유로, 허용 스큐(skew)를 86,400초(꼬박 하루)로 확대해 버린 것입니다. 당연히 다음 리뷰에서 "테스트 편의를 위해 운영 환경의 상수를 결정하지 마라"는 지적을 받았고, 스큐는 60초로 되돌렸습니다. 테스트 측을 now= 주입을 통해 벽시계(wall clock)에 의존하지 않도록 수정하는 것이 정석이었습니다.

교훈: "테스트를 통과하기 위해 운영 환경의 임계치를 완화하는 것"은 피곤할 때 저지르는 실수다. 리뷰를 거듭하는 '지적 0건 루프'는 바로 이런 "수정이 낳은 새로운 왜곡"을 잡아내기 위해 존재하는 것이다.

그리고 이 수정 사항의 실기 확인이, 서두에 언급한 스마트폰을 통한 /compact였습니다. checkpoint는 의도한 대로 단 1블록이 되었습니다. 디바운스 성공. 그리고 그 옆에, 문제의 경고가 떠 있었습니다.

제2화 ── "예전부터 그곳에 있었지만, 한 번도 읽히지 않았을지도 모른다"

경고의 의미를 조사했습니다. C3의 pre_compact.py는 checkpoint 추가 후에 stdout으로 JSON을 출력하고 있었습니다. hookSpecificOutput.additionalContext ── compact 이후의 모델에 "세션 파일을 업데이트하라"는 지시(약 200자)를 주입하려는 의도였습니다.

공식 문서를 1차 소스로 확인한 결과:

• PreCompact hook은 지원되는 출력으로 additionalContext를 지원하지 않는다. decision: "block" + reason만 지원한다. - additionalContext를 지원하는 이벤트 목록에 PreCompact는 과거 그 어느 시점에도 포함된 적이 없다. changelog 전체 이력을 거슬러 올라가도 추가 기록이 없다.

즉, C3는 처음부터 사양 외의 JSON을 출력하고 있었다. 이전의 하네스(harness)는 이를 묵묵히 무시하고 있었기에(적어도 에러는 내지 않았기에) "작동하고 있는" 것처럼 보였던 것입니다. 최근 버전에 스키마 검증(schema validation)이 도입되면서 사양 외 출력이 명시적으로 거부(reject)되었고, 그제야 가시화되었습니다. 주입하려 했던 지시가 정말로 모델에 전달되었던 날이 있었는지, 지금에 와서는 증명할 수 없습니다.

흥미로운 점은 기능적인 실해(実害)가 거의 없었다는 것입니다. "세션 파일을 업데이트하라"는 지시는 C3의 운영 규칙(현재 행의 상시 업데이트, 태스크 완료 시마다 추가)에 의해 이중으로 담보되어 있었습니다. 그래서 주입이 전달되지 않더라도 아무도 곤란해하지 않았습니다. "없어도 상관없는 기능"이었기에, 사양 외인 상태로 몇 달 동안이나 눈에 띄지 않았다고도 할 수 있습니다.

대응책은 제거가 유일한 선택입니다. stdout 출력과 지시문 상수를 통째로 삭제하고, hook을 "checkpoint 추가에 전념"하게 만듭니다. 사양 외의 stdout 경로 자체가 사라지므로, 향후 그곳에 검증되지 않은(un-sanitized) 값을 추가하게 되는 종류의 사고도 구조적으로 발생하지 않게 됩니다. 공격 표면(attack surface)의 순감소입니다.

이 워크플로우 역시 외출 중에 위임(delegation)을 통해 진행했습니다. 위임 조건은 전날부터 사용하던 것으로, "승인은 전부 승인 · 리뷰 지적은 Low를 포함해 전건 대응 · 지적 0건까지 반복 · 커밋까지 실시 가능 · push 등의 공개 계열은 보류"였습니다. 귀가 후 누를 것은 릴리스 버튼뿐인 상태로 집에 도착했습니다. 디바운스와 함께 v2.44.0로 릴리스했습니다.

막간 ── "changelog에 전부 실려 있다고는 할 수 없으니까요"

릴리스 후 잡담 중에, 백로그의 다음 항목인 "신버전 Claude Code에 대한 스모크 테스트" 이야기가 나왔습니다.

C3에는 매일 아침 11시에 claude.ai 상의 루틴이 Claude Code의 changelog를 읽고 "오늘의 변경 사항이 C3에 영향을 미치는가"를 리포트하는 메커니즘이 있습니다. 다만, 이 결론은 어디까지나 문장으로부터의 추론입니다. 그리고 사용자의 한마디가 이것이었습니다.

반드시 체인지로그(changelog)에 모든 수정 내용이 기재되어 있다고도 할 수 없으며, 이전에는 "세세한 버그 수정" 같은 식으로 뭉뚱그려 정리되었던 적이 있었던 것 같습니다.

실적도 있습니다. worktree의 자동 클린업(cleanup)이 작동하지 않게 된 건(Issue #28017)은 changelog에 실리지 않은 형태로 동작이 변했었고, 오늘 발생한 PreCompact 다중 발화 역시 문서에는 존재하지 않습니다. 제1화도 제2화도, 책상 앞에서의 독해로는 찾을 수 없었으며, 실측으로만 찾을 수 있었던 것입니다.

그렇다면 추론의 옆에 실측을 두자. Claude Code의 버전이 로컬에서 올라간 것을 감지하면, C3가 의존하는 하네스(harness) 동작의 급소를 headless (claude -p)로 실제로 구동하여 확인한다── 그것이 이번에 만든 스모크 테스트(smoke test)입니다.

설계는 다음과 같이 되었습니다.

감지: SessionStart hook이 claude --version (실측 0.089초. 세션 시작에 미치는 영향 제로)을 "마지막으로 스모크 테스트를 통과한 버전"과 비교. 불일치할 경우, 통과할 때까지 매 세션마다 알림 (실행 누락 방지)

실행은 승인제: 토큰을 소비하므로 자동 실행하지 않음. 알림이 뜨면 인간이 명령어를 한 번 입력

격리 샌드박스: 임시 디렉토리에 c3 init한 일회용 프로젝트에서 실행. 실제 학습 DB나 세션 파일에 가짜 데이터를 섞지 않음

검증할 급소는 3가지: ① worktree isolation이 포함된 서브 에이전트(sub-agent) 기동 ② worktree 내부로부터의 학습 기록 (DB 쓰기) ③ worktree의 cleanup (#28017 유형의 재발 감지)

합격 여부는 기계 판정만: exit code, DB의 행 수, git worktree list의 잔여 수. LLM의 "잘 되었습니다"라는 자기 보고는 일절 채택하지 않음. 게다가 pass / fail에 더해 **inconclusive (판정 불능)**를 구분. usage limit이나 타임아웃은 "하네스가 고장 난 것"이 아니라 "오늘은 판정할 수 없었던 것"이기 때문

배치 장소는 배포물이 아니라 개발 리포지토리 전용 (.dev/). 고장 났을 때 고치는 것은 메인테이너(maintainer)의 일이며, 이용자는 수정된 C3를 받기만 하면 되므로 테스트 자체를 배포할 필요는 없음

여기까지는 깔끔한 설계 이야기. 여기서부터가 본론입니다.

제3화 ── 검증 도구는, 먼저 자신이 검증된다

TDD로 구현하고 (판정 로직은 순수 함수로 분리하여 35개의 테스트 수행), 드디어 실기 스모크 테스트. 3번 떨어졌습니다. 그리고 3번 모두, 하네스는 무죄였습니다.

사건부 1: hook이 한 번도 발화하지 않는 설정값

구현한 developer 에이전트 (이때는 학습 데이터 수집을 위해 haiku 담당)가, SessionStart hook의 등록에 matcher: "always"라고 작성해 왔습니다. 그럴듯해 보이지만, 공식 사양의 matcher 열거형(enumeration) 값은 startup / resume / clear / compact 4가지이며, "always"는 그 어디에도 매치되지 않습니다. 즉, 이 hook은 영원히 발화하지 않습니다. 전체를 매치시키고 싶다면 빈 문자열이 정답입니다.

무서운 점은 이것이 pytest로는 절대로 검출할 수 없다는 것입니다. 테스트는 Python 함수의 입출력을 보지만, 설정 파일의 문자열이 올바른 열거형 값인지는 하네스만이 알고 있습니다. 공식 문서의 열거형 값과 리포지토리 내의 기존 등록 사례를 대조하는 "상위 에이전트의 실측값 확인"을 통해 찾아냈습니다. 설정값은 테스트의 공백 지대라는 점은, 오늘 얻은 가장 보편적인 배움일지도 모릅니다.

사건부 2: 흔적을 남기지 않는 실행은, 존재하지 않는 것과 같다

첫 실기 스모크 테스트 결과는 verdict: fail. 여기서 문제가 하나 더 드러납니다. 당시 구현은 claude -p의 stdout / stderr를 어디에도 저장하지 않았고, 기록된 상세 내용은 빈 문자열이었습니다. 왜 떨어졌는지, 아무것도 알 수 없습니다. 게다가 담당 에이전트는 "단 한 번"이라는 지시를 어기고 2번 실행하여, 2회분의 "이유 불명 fail"만이 남았습니다.

어쩔 수 없이 상위(나)가 모든 출력을 저장하는 진단 런(run)을 딱 한 번 수동으로 실행했습니다. 그러자 stderr에 선명하게:

unable to create file .claude/skills/dev-workflow/references/security-review-checklist.md:
Filename too long

Windows의 경로 길이 제한 (260자) 때문입니다. 임시 디렉터리의 깊은 경로 + worktree 디렉터리 + 템플릿 내의 긴 파일 경로를 더하면 262자. 2자가 초과되었습니다. worktree 생성이 거기서 중단되었습니다.

더욱 뼈아픈 점은, 그때 서브 에이전트(sub-agent)가 "경로 길이 제한에 저촉되었습니다. 어떤 대응을 시도하시겠습니까?"라고 정중하게 질문하고 종료되었다는 것입니다. headless 실행에는 응답자가 없습니다. 아무도 없는 방을 향해 선택지를 제시하고, 조용히 끝난 것이었습니다. 수정 사항은 "샌드박스(sandbox) 경로 단축 + git config core.longpaths true 설정 + 프롬프트에 『에러 발생 시 질문하지 말고 즉시 실패 보고할 것』이라는 fail-fast 지시 + stdout/stderr를 매번 파일로 저장"이었습니다.

사건부 3: 같은 경로가 두 개의 얼굴을 가지고 있었다

두 번째 실기 테스트도 다시 fail. 하지만 이번에는 로그가 남아 있습니다. 확인해 보니 worktree 기동도 DB 쓰기도 성공했으며, 실패한 것은 "DB의 note 란에 샌드박스 경로가 포함될 것"이라는 검증 항목뿐이었습니다. 원인은 두 가지가 겹쳐 있었습니다. ① 애초에 프롬프트가 note에 경로를 쓰라고 지시하지 않았음 (검증 설계의 버그), ② 서브 에이전트의 작업 디렉터리 보고가 /tmp/c3s_... (Git Bash의 POSIX 표기)로 되어 있어, 판정 측이 기대하는 C:\Users\...\Temp\c3s_... (Windows 표기)와 같은 장소임에도 문자열이 일치하지 않았음.

판정 방식을 "경로 문자열 일치"에서 "smoke-cwd: 마커가 있고, 경로에 worktrees를 포함함"이라는 경로 표기에 의존하지 않는 형태로 바꾸어──

3회차, pass. 1회당 실측 비용은 $0.062. worktree 기동 · worktree 내부에서의 학습 기록 · cleanup, 이 세 가지 핵심 요소 모두가 현행 버전에서 실측 확인되었습니다. 이후 Claude Code가 업데이트될 때만 "스모크(smoke) 권장" 알림이 뜨며, 단 한 번의 명령으로 "추론"을 "실측"으로 바꿀 수 있습니다.

덤: 청소조차 Windows에 가로막히다

마지막으로 남은 defect가 하나. 일회용 샌드박스를 shutil.rmtree로 삭제하면, .git 내부 내용만 삭제에 실패하고 남습니다. git의 오브젝트 파일은 **읽기 전용 속성(read-only attribute)**으로 생성되기 때문에, Windows의 rmtree는 거기서 예외를 던집니다 (이미 알려진 패턴). 에러 핸들러에서 chmod를 수행하고 재시도하는 삭제 함수로 교체하여 해결했습니다. 읽기 전용 .git을 포함한 미니 샘플을 만들어 완전 삭제가 가능함을 테스트로 입증했습니다.

참고로 이 스모크 테스트 자체도 마지막에 풀 코드 리뷰(full code review)를 돌려, High 1건(c3 init 실패 시의 verdict가 판정표와 자기 모순되는 하드코딩)을 포함한 11건 → 수정 → 신규 3건 → 수정 → 0건의 2사이클 만에 클로즈(close)했습니다. 검증 도구야말로 가장 검증되지 않으면 신뢰할 수 없기 때문입니다.

업무·개인 개발에 활용할 수 있는 점

1. "동작하고 있다"와 "사양에 존재한다"는 별개다

additionalContext 건은, 사양 외라도 묵묵히 받아들이는 API는 검증이 엄격해진 날 조용히 죽는다는 이야기입니다. 전달되었는지조차 소급할 수 없습니다. 의존하고 있는 외부 사양은 "동작하니까 OK"가 아니라, 공식 문서의 열거 및 스키마와 대조하여 "존재하니까 OK"로 작성해야 합니다. 그리고 undocumented한 동작(다중 발화)에 의존당하는 입장이 된다면, 상대방의 호출 방식을 제어하려 하지 말고 자신을 멱등(idempotent)하게 만들어야 합니다.

2. 출력을 저장하지 않는 실행은 실행하지 않은 것과 같다

이유 불명의 fail이 단 2건만 남은 시점에서, 그 2번의 실행에 소비한 토큰은 정보량이 제로였습니다. 자동화된 실행에는 "stdout/stderr를 반드시 파일로 남긴다"를 처음부터 포함시켜야 합니다. 검시(autopsy)할 수 없는 실패는 실패 횟수만 늘려갈 뿐입니다.

3. 합격/불합격에 "판정 불능"을 준비한다

pass / fail의 이진 분류(binary)라면, usage limit(사용 한도)·타임아웃·환경 구축 실패가 모두 "fail"에 섞여 버려, "하네스(harness)가 고장 났다"라는 가장 중요한 시그널이 흐려집니다. inconclusive(판정 불능)를 분리하여, 판정 불능일 때는 상태를 진행하지 않는다(다음 세션에서 다시 통지됨). 지난 기사의 "실패 시그널은 객관적 사실로 정의한다"의 속편 같은 이야기입니다만, 삼진 분류(ternary)화는 모니터링 시스템 전반에서 효과적일 것입니다.

4. 설정 파일의 값은 테스트의 공백 지대

matcher: "always"

는 코드 자체로는 단 한 글자도 틀리지 않았습니다. 틀린 것은 외부 시스템과의 계약입니다. 유닛 테스트(Unit Test)가 닿지 않는 이 영역은, 공식 사양의 열거형(Enumeration)·스키마(Schema)·리포지토리(Repository) 내의 기존 전례와의 기계적인 대조로 커버합니다. 리뷰 관점으로 "설정값이 열거형과 대조되었는가"를 한 줄 추가하는 것만으로도 잡아낼 수 있었던 사고였습니다.

5. 원격 위임은 "승인의 입도(granularity)"를 먼저 언어화한다

이번에 버그 발견부터 워크플로우 완수까지의 대부분은 외출 중 위임으로 진행되었습니다. 기능할 수 있었던 이유는 위임 조건을 미리 문장화해 두었기 때문입니다── "승인 작업은 전부 승인해도 좋다 / 리뷰 지적 사항은 Low를 포함해 전 건 대응 / 지적 사항이 0이 될 때까지 반복 / 커밋(Commit)까지는 가능·push 등의 공개 작업은 귀가 후". 가역적인 작업은 맡기고, 불가역적인 공개 작업만 인간이 쥐고 있는 것입니다. 이 선긋기만 정해 두었다면, 스마트폰과 /compact 한 번 분량의 틈새 시간만으로 릴리스 직전까지 진행할 수 있습니다.

요약

v2.44.0 (그 1): 1회의 compact로 checkpoint가 4개 증가 → 하네스의 undocumented(문서화되지 않은) hook 다중 실행이 원인. 10초 디바운스(Debounce)로 멱등성(Idempotency) 확보 (ReDoS 실측 69초 지적, 86,400초 사건을 거쳐 지적 사항 제로로 클로즈). 실기에서 4블록 → 1블록 확인 -
v2.44.0 (그 2): 해당 실기 확인 화면에서 validation(검증) 경고 발견 → PreCompact의 additionalContext는 공식 사양에 처음부터 존재하지 않음. 사양 외 stdout을 전부 제거하고 checkpoint 추가에 전념. 경고 소멸을 실기에서 확인 -
P2 (배포 외 개발 도구): changelog의 추론을 실측으로 바꾸는 headless 스모크 테스트(Smoke Test)를 신설. 버전 감지 → 승인제 → 격리 샌드박스(Sandbox) → 기계 판정 3진 분류. 실기 pass ($0.062/회)에 이르기까지, matcher 무효값·Windows 260자 제한·POSIX/Windows 경로 표기 불일치라는 스모크 테스트 자체의 버그를 3개 해결. 하네스는 시종일관 무죄였다

"사양에 없는 구현"을 제거하고, "문서에 없는 동작"에는 멱등성으로 대비하며, 앞으로의 괴리는 실측으로 감지한다. 수수한 하루였지만, 믿음의 근거를 문장에서 측정값으로 교체한 하루였습니다.

C3를 써보고 싶다면 ── 시작하는 법

pip install claude-code-conductor # C++ 컴파일러 불필요
cd your-project
c3 init # .claude/ 디렉토리에 에이전트 정의·skill·hook이 전개됨

그다음은 Claude Code에서 /start.

v2.44.0에는 본 기사의 PreCompact 수정 사항(checkpoint 멱등성 확보·사양 외 출력 제거)이 포함되어 있습니다. 어댑터는 Claude / Codex / Cursor / OpenCode 4종을 지원합니다 (c3 init --platform ...).

"여기서 막혔다" "이 부분이 이상하다" ── 막히는 부분에 대한 보고가 가장 큰 도움이 됩니다. Issue든 PR이든 편하게 남겨주세요.

링크

링크

• C3 GitHub: https://github.com/satoh-y-0323/claude-code-conductor -
• C3 PyPI: https://pypi.org/project/claude-code-conductor/ -
• C3 공식 문서: https://satoh-y-0323.github.io/claude-code-conductor/ -
• v2.44.0 릴리스 노트: https://github.com/satoh-y-0323/claude-code-conductor/releases/tag/v2.44.0 -
• 이전 글(『저렴한 모델은 다시 선택받지 못한다』 / C3 v2.41.0~v2.43.0): https://zenn.dev/satoh_y_0323/articles/e98658522364d5

토론