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

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/

본 기사의 범위: C3 v2.52.0 ~ v2.53.0. 이전 기사의 맺음말에서 「구멍 3개의 개수를 포함하여 정식 배포를 향해 나아갈 예정입니다」라고 쓴, 그 예고의 회수편입니다. 자율 모드 (autonomous-mode skill)가 오늘부터 배포물에 포함되었습니다.

서론 ── 예고를 회수합니다

지난번, 「루프 다음은 그래프」라는 버즈워드(buzzword)에 혼란스러워하던 기세로, Opus 4.8에 자율 모드를 완주시키는 검증을 수행했습니다. 검증은 완주되었고, 규약의 구멍이 3개라는 점을 실제 실행 증거와 함께 확정 지었다── 거기까지가 지난번 내용입니다.

이번에는 그 다음입니다. 구멍 3개를 규약 개정으로 메우고 (v2.52.0), 또 한 번의 Opus 완주를 거듭하며 (v2.52.1), 배포 전환 태스크를 A~E 풀 워크플로우(full workflow)로 실행하여 v2.53.0로서 배포를 시작했습니다. 7/14에 「git 비추적·wheel 비포함의 배포처 전용」으로 태어난 지 10일. 숙성 기간으로는 짧아 보이지만, 이 사이에 실제 프로젝트에서의 완주를 거듭하며 규약 개정 2회와 리뷰 사이클 수십 회가 압축되어 있습니다.

그리고 배포 전환 당일, 마지막의 마지막에 CI가 빨간색(fail)이 되었습니다. 범인은, 「autonomous-mode는 배포에서 제외된다」라고 assert(단언)하고 있는 나의 과거 테스트였습니다. 제외를 해제하는 태스크인 만큼, 제외를 주장하는 테스트와 정면 충돌하는 것은 당연한 일이지만, 계획 단계에서는 아무도 (design-critic의 적대적 감사도, Red 페이즈의 tester도, 저도) 눈치채지 못했습니다. 이 이야기는 후반부에서 다루겠습니다.

1. 우선 오해를 풀자 ── 자율 모드는 「방치할 수 있는 AI」가 아닙니다

배포를 시작함에 있어, 가장 전달하고 싶은 오해에 관한 이야기부터 하겠습니다. 저 자신이 제작자임에도 2번이나 오해했던 논점이기에, 처음 접하시는 분들은 높은 확률로 같은 곳에서 실수할 것입니다.

C3에는 「사람이 개입하지 않고 돌아가는」 것처럼 보이는 메커니즘이 2가지 있지만, 서로 다른 것입니다.

즉 자율 모드란 「질문하지 않는 AI」가 아니라, **「정형화된 도장 승인을 객관적 조건으로 교체하고, 도장으로 해결되지 않는 판단만을 사람에게 가져오는 AI」**입니다. 따라서 자율 모드 주행 중에 질문이 날아온다면, 그것은 고장이 아니라 설계대로 작동하는 것입니다. 지난 기사에서 「자율 모드인데 질문을 받았다」라고 제작자 본인이 오인했던 반성을 토대로, 이 문장을 온보딩 문서의 서두에 넣었습니다.

질문이 온다 = 설계대로다. 질문이 오지 않는다면, 오히려 그쪽을 걱정해 주십시오.

참고로 기본 설정은 지금까지와 동일하게 **HITL (모든 게이트에서 사람이 승인)**입니다. v2.53.0을 설치하더라도, 후술할 이중 opt-in을 하지 않는 한 자율 모드는 일절 발동하지 않습니다. 이 부분은 fail-closed(실패 시 차단)로 설정되어 있습니다.

2. 배포까지 한 일 ── 구멍 3개의 개수와, 완주 2번째 번째의 실제 실행 데이터

지난번에 확정된 구멍 3개는, v2.52.0의 규약 개정을 통해 다음과 같이 메웠습니다.

• opt-in 유도 경로(導線)의 미문서화 → 온보딩 (Onboarding) 문서를 신규 작성 (v2.53.0에서 배포물 포함)
• 수정의 실시 주체 → "소스 변경은 담당 에이전트 고정 · 부모의 직접 편집은 예외 없이 금지"를 불변칙으로 명문화
• usage 관문(関所)의 재설계 → 주행 중의 usage 정지를 전폐하고, 위임 플랜 승인 시의 "자원 동의" 절 (최대 회전 수 · 예상 자원 규모)에 통합. 인간의 관문은 비가역 조작 · 정보 부족 질문의 2가지 유형으로 축소

나아가 검증 2회차 (v2.52.1의 TOML 이스케이프 수정 사항을 자율 모드로 구현)에서는, 1회차에서는 얻을 수 없었던 실주행 데이터를 얻을 수 있었습니다. 설계 감사 (Design Audit)가 규정 상한인 5 사이클에 도달하여, 규약대로 인간에게 에스컬레이션(Escalation) → 재정(裁定) → 재개라는 안전장치의 모든 경로가 실주행으로 한 바퀴를 돌았다는 것. 그리고 감사가 수렴한 계획으로부터 만든 구현에서, 리뷰를 통해 구현 버그가 2건 발생했다는 것. 후자로부터 "C-3 (설계 감사)의 수렴은 결함 제로를 의미하지 않는다. 그 시점의 계획의 건전성만을 보증한다"라는 한 문장이 탄생했으며, 이 또한 온보딩 문서에 실려 있습니다. 낙관적인 홍보 문구를 쓸 수 있는 곳에 실측의 한계를 적는 것은 약간의 용기가 필요했지만, 오해해서 사고를 치는 것보다 100배 낫습니다.

3. 배포 전환 당일 ── 짧은 이야기 3연발

배포 전환 그 자체도 C3의 표준 워크플로우 (히어링 → 설계 → 계획 → 감사 → TDD → 리뷰)로 실행했습니다. 제외 리스트에서 3줄을 지우는 것뿐인 작업으로 보이지만, 실제로는 리뷰 5회전 · 수정 사이클 3회의 풀코스가 된 당일의 기록입니다.

3-1. 「배포하지 않겠다」고 주장하는 테스트가 마지막에 빨간색이 되었다

서두의 복선 회수입니다. 제외 3개 파일 (.gitignore / _excludes.py / hatch_build.py)에서 autonomous-mode 행을 삭제하고, git add로 추적을 시작한 직후, pytest가 1건만 빨간색(Fail)이 되었습니다.

FAILED tests/test_excludes.py::test_autonomous_mode_skill_is_excluded_from_distribution
AssertionError: assert False is True

테스트 이름을 보세요. is_excluded_from_distribution ── "배포에서 제외될 것"을 검증하는 테스트입니다. 10일 전의 내가 "실수로 배포되지 않도록" 선의로 배치해 둔 회귀 가드(Regression Guard)가, 배포를 해금한 순간 의무를 다하며 빨간색이 된 것입니다. 과거의 내가 남긴 유산에 현재의 내가 붙잡힌 형태입니다.

재미있는 점은 여기서부터인데, 구현 담당인 developer 에이전트에게는 "기존 테스트가 빨간색이 되면 마음대로 고치지 말고 정지하여 보고하라"고 지시해 두었기에, 규약대로 정지하여 "이 테스트는 구버전 사양을 기대하고 있습니다. 수정하시겠습니까?"라고 물어왔습니다. 재정하여 테스트를 is_included_in_distribution으로 반전시켜 해결. 교훈은 "사양을 반전시키는 태스크에서는, 구사양을 assert 하고 있는 기존 테스트를 가장 먼저 점검할 것". 다음부터는 Red 페이즈의 체크리스트에 포함됩니다.

3-2. 리뷰가 찾아낸 오타

코드 리뷰에서 테스트 파일의 코멘트에 다음과 같은 지적이 나왔습니다.

# AD-3: 既존 skill は除外하지 않음

── 일본어와 한글이 혼재되어 있습니다.

既存(기존)의 「존」 부분만 한글의 존이 되어 있습니다. 구현한 AI가 생성 시에 혼입시킨 듯합니다 ("기존"과 "기존"은 발음이 유사한 모양입니다). 기능에는 무해하지만 확실히 거슬립니다.

여기서 끝난다면 흔한 이야기겠지만, 수정을 위해 Red 페이즈의 tester가 실측한 결과, 리뷰 보고 측에도 1글자 오류가 발견되었습니다. 리뷰는 "을 (U+C744)이 혼입"이라고 보고했으나, 실제로는 일본어의 "を" (U+3092)였습니다. tester는 "리뷰 기재가 아닌 실측값을 정답으로 한다"는 전달 사항을 붙여 수정 지시를 확정했습니다. 리뷰의 지적을 리뷰하는 층이 제대로 기능한, 소소하게 기쁜 순간이었습니다. 문자 코드의 세계에서는 육안은 믿을 것이 못 됩니다. repr()만이 친구입니다.

3-3. Windows에서만 대소문자를 구분하지 않는 fnmatch

어댑터용 제외 판정에 fnmatch.fnmatch

를 사용했을 때, 리뷰에서 Medium 지적을 받았습니다. 기존의 제외 판정은 fnmatch.fnmatchcase (항상 대소문자 구분)인 반면, 새로 만든 쪽은 fnmatch.fnmatch를 사용했습니다.

──이것은 OS에 의존하며, Windows에서는 대소문자를 구분하지 않습니다.

fnmatch.fnmatch('skills/AUTONOMOUS-MODE/SKILL.md', 'skills/autonomous-mode/*') # Windows: True
fnmatch.fnmatchcase('skills/AUTONOMOUS-MODE/SKILL.md', 'skills/autonomous-mode/*') # 항상 False

현재 패턴으로는 실질적인 피해가 없지만, 방치하면 "Windows 개발 환경에서는 통과하는데 Linux CI에서는 다르게 동작하는" 재현하기 어려운 불일치의 씨앗이 됩니다. fnmatchcase로 통일하고, 대문자 경로에 대한 회귀 테스트 (Regression Test)를 1건 추가했습니다. 참고로 이 지적에 대해, 리뷰어는 정적 독해 (Static Reading)가 아니라 python -c로 양쪽을 실행하여 차이를 확정한 후 보고해 왔습니다. 과거에 "정적 독해만으로 결론을 내렸다가 구현 버그가 2건 빠져나갔던" 실적이 있기 때문에, 조합 로직은 직접 실행하여 검증한다가 현재의 리뷰 규약입니다.

이렇게 해서 E 리뷰는 코드 측 3회전 (5건 → 3건 → 0건), 보안 측 2회전 (3건 → 0건)으로 수렴했습니다. 보안 리뷰에서는 인용구 파싱 (Quote Parsing)에 대해 적대적 입력 (Adversarial Input) 20가지를 실행하여 (경로 탐색 (Path Traversal), NUL 삽입, NTFS Junction, 8.3 짧은 파일 이름 등), 봉쇄 우회 사례가 0건임을 확인했습니다. 테스트는 2096 → 2115로 늘어났으며 모두 통과(Green)했습니다. pip 설치 검증 환경에서의 c3 update → 3점 실측도 PASS 하여 릴리스했습니다.

4. 사용법 ── 처음 사용하는 사람을 위해, 동작하는 단계까지

이 부분이 본 기사의 실용 파트입니다. "설치하면 알아서 자율적으로 움직이는 것 아닌가"라는 걱정과, "어떻게 해야 자율 모드가 되는지 모르겠다"라는 의문 모두에 답해 드립니다.

일반적인 이용 (자율 모드 없음) ── 우선 이것만으로도 OK

pip install claude-code-conductor # 기존 환경은 pip install -U 로 v2.53.0 으로 업데이트
cd your-project
c3 init # .claude/ 디렉토리에 에이전트 정의, skill, hook이 전개됨

Claude Code를 열고 /start를 입력합니다. 히어링(Hearing) → 설계 → 계획 → 구현 → 리뷰의 워크플로우가, 각 단계에서 사용자의 승인을 받으면서 진행됩니다. 이것이 기본 설정인 HITL (Human-in-the-Loop) 운전이며, v2.53.0을 설치해도 변하지 않습니다. 우선은 이 표준 워크플로우에 익숙해지는 것을 추천합니다.

자율 모드를 사용해 보기 ── 이중 opt-in의 구체적인 예

자율 모드를 발동시키려면 명시적인 절차 2가지가 필요합니다. 역으로 말하면, 이 2가지를 하지 않는 한 절대로 발동하지 않습니다.

단계 1: 플랜 모드에서 「위임 플랜」을 승인하기

Claude Code의 플랜 모드 (Shift+Tab으로 전환)에 들어가서, 하고 싶은 일과 함께 자율 모드 의사를 전달합니다.

이 태스크를 자율 모드로 완수해 줘:
tests/ 디렉토리 하위의 flaky 테스트 3건의 원인 조사 및 수정.
리뷰에서 High/Medium이 0이 될 때까지 반복해도 좋아. 커밋은 내가 승인할게.

Claude가 위임 플랜을 ~/.claude/plans/ 하위에 생성합니다. 이 플랜에는 자원 동의 절 (Resource Consent Clause) (최대 반복 횟수와 예상 자원 규모. 여기서 "어디까지 반복해도 좋을지"에 동의합니다)이 필수이며, 없으면 규약 위반으로 간주되어 자율 모드로 진입할 수 없습니다. 내용을 확인하고 승인합니다.

단계 2: 세션 파일의 모드 행 (Claude가 작성하며, 기계적으로 검증됨)

플랜 승인을 받으면, Claude가 세션 파일에 다음과 같은 한 줄을 작성합니다.

Windows의 경우:

모드: 자율 plan=C:\Users\you\.claude\plans\fix-flaky-tests.md cycles=C-3/0,E/0

macOS / Linux의 경우:

모드: 자율 plan=/Users/you/.claude/plans/fix-flaky-tests.md cycles=C-3/0,E/0

（Linux라면 경로는 /home/you/.claude/plans/... 입니다.

요컨대 당신의 홈 디렉토리 직하의 .claude/plans/ 하위가 위치하는 곳이며, 이곳 이외에 있는 플랜은 기계 검증에서 거부됩니다.)

이 행은 '대충' 해서는 통과할 수 없습니다. 부속된 검증 스크립트가 플랜의 경로가 실제로 존재하는지 확인 및 정규화(Normalization)하고, ~/.claude/plans/ 하위에 봉인되어 있는지를 기계적으로 판정합니다 (v2.53.0부터는 공백이 포함된 경로의 plan="..." 형식에도 대응합니다). 판정이 INVALID라면 묵묵히 일반적인 HITL (Human-in-the-Loop)로 돌아갑니다. 망가졌을 때는 안전한 쪽을 택한다는 것이 전체적인 방침입니다. 운행이 시작되면 어떤 일이 벌어지는가

• 정형화된 승인 게이트(계획 OK? 테스트 결과 OK? 등)는 당신을 대신하여 객관적 조건(테스트 전 녹색/All Green, 감사 지적 High/Medium 0 등)이 판정합니다.
• 그럼에도 불구하고 당신에게 질문이 오는 상황이 2가지 있습니다. ① 비가역적 조작(Commit, Push, Release) 직전, 그리고 ② 진행하기에 정보가 부족할 때입니다. 앞서 언급했듯이, 질문이 오는 것은 설계대로입니다. 감사나 리뷰가 규정된 상한 회차에 도달하면, 멋대로 연장하지 않고 인간에게 에스컬레이션(Escalation)합니다. 판결하여 재개시킬지, 아니면 중단할지는 당신이 결정합니다.

자세한 내용은 c3 init으로 배포되는 .claude/docs/autonomous-mode-onboarding.md에 이번 실전 주행에서 저자가 오독했던 논점들을 포함하여 정리해 두었습니다. 또한 자율 모드는 Claude Code 전용이며, Codex / Cursor / OpenCode의 어댑터(Adapter)를 통해서는 항상 무효(즉, HITL)입니다. 모드 행의 기계 검증을 타 플랫폼에서 안전하게 재현할 수 없기 때문에, '검증할 수 없다면 발동하지 않는다'는 방향으로 결정했습니다.

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

1. 「자율」을 팔 때는, 멈추는 조건부터 설명하라

자율 모드 설명에서 가장 효과적이었던 것은 '무엇을 할 수 있는가'가 아니라 '어떤 상황에서 반드시 멈추는가'였습니다. 비가역적 조작과 정보 부족 시에는 반드시 질문이 오고, 상한에 도달하면 에스컬레이션한다──멈추는 조건이 명확하기 때문에 맡길 수 있습니다. 반대로 '전부 자동입니다'라는 설명은 첫 번째 질문이 날아오는 순간 불신으로 변합니다.

2. 사양을 반전시키는 태스크는, 구 사양을 주장하는 테스트를 먼저 찾아라

'제외를 해제한다', '제한을 철폐한다' 계열의 태스크에서는 구 사양을 assert(단언)하는 기존 테스트가 높은 확률로 존재합니다 (그것을 위해 작성했을 테니까요). 구현 후에 빨간색(Fail)이 된 뒤에 대처하는 것이 아니라, 계획 단계에서 grep 하여 반전 대상 리스트에 올립니다. 감사도 리뷰어도 인간도 놓친 구멍이므로, 체크리스트화하는 것이 확실합니다.

3. 기능을 배포하기 전에 「기능의 한계」를 문서화하라

'C-3 수렴 ≠ 결함 제로', '감사 에이전트는 실행 검증을 할 수 없다'와 같이 실측된 한계를 온보딩(Onboarding)에 명시했습니다. 한계를 적으면 기능이 약해 보일 것 같지만, 실제로는 반대입니다. 한계 기술이 있는 문서만이 사고가 발생했을 때 사용자 편에 서 줄 것입니다.

4. denylist는 「추가하는 것을 잊어버릴 미래의 자신」을 상정하라

어댑터로의 사상(Mapping) 제외는 수동 업데이트 방식인 denylist로 구현했습니다. 지금은 올바르게 동작하지만, 향후 'Claude Code 전용 skill'을 추가할 때 추가하는 것을 잊으면 조용히 누락됩니다 (fail-open). 이번에는 allowlist화하는 것을 보류하는 대신, 그 성질 자체를 리뷰 기록과 인수인계 사항에 남기는 선택을 했습니다. 설계 판단의 부채는 상환하지 않을 거라면 최소한 장부에라도 기록해야 합니다.

요약

• autonomous-mode skill을 v2.53.0에서 배포 시작했습니다. 기본값은 변함없이 HITL이며, 발동은 이중 opt-in(위임 플랜 승인 + 기계 검증이 포함된 모드 행) 방식입니다. 타 플랫폼에서는 항상 무효입니다.
• 자율 모드는 '사람이 질문에 답한다'는 전제의 메커니즘이며, 응답자가 부재한 루프 엔지니어링 계층(미배포·실험 중)과는 별개입니다. 질문이 오는 것은 = 설계대로입니다.
• 배포 전환 태스크 자체도 풀 워크플로우(Full Workflow)로 주행했습니다. '배포하지 않겠다'고 주장하는 과거의 내 테스트에 걸렸고, 리뷰는 한글 한 글자를 잡아냈으며, tester는 리뷰의 오타를 잡아냈습니다. 리뷰하는 계층이 서로를 검증하는 구조는 오늘도 기능했습니다.

지난번에 "'사용해보고 싶다'는 목소리는 배포의 강력한 뒷받침이 됩니다"라고 썼지만, 기다리지 못하고 배포해 버렸습니다. 이번에는 "사용해봤다"는 목소리를 기다리고 있습니다. 작동했다, 막혔다, 질문이 와서 놀랐다──그 어떤 것도 환영합니다.

링크

C3 GitHub: https://github.com/satoh-y-0323/claude-code-conductor -
C3 PyPI: https://pypi.org/project/claude-code-conductor/ -
C3 공식 문서 (Official Documentation): https://satoh-y-0323.github.io/claude-code-conductor/ -
v2.53.0 릴리스 노트 (Release Notes): https://github.com/satoh-y-0323/claude-code-conductor/releases/tag/v2.53.0 -
이전 기사 (그래프 ⊃ 루프 정리와 Opus 완주 검증): https://zenn.dev/satoh_y_0323/articles/f01a07afe1a654 -
자율 모드 (Autonomous Mode) 관련 과거 기사: 검증 3일간의 실주 기록 / 본체 구현 이야기 (v2.49.0)

Discussion