코드 완성에서 코드 팀으로: Claude Code를 엔지니어링 부서로 전환한 방법

우리는 매일 Claude Code를 사용합니다. 훌륭합니다. 복잡한 리팩토링을 처리하고, 테스트를 작성하고, 대규모 코드베이스를 탐색하며, 우리가 놓칠 버그를 잡습니다. 하지만 몇 개월 동안 자율 다중 에이전트 시스템의 일부로 실행한 후, 우리는 한 가지를 깨달았습니다: Claude Code는 강력한 도구이지만 근본적으로 수동적입니다. 지시를 기다리고, 실행하고, 멈춥니다. 자기 자신을 모니터링하지 않고, 미리 계획하지 않으며, 자신의 결과물을 검토하지 않고, 지난번에 무엇이 잘못되었는지 기억하지 않습니다.

이것은 비판이 아닙니다. 설계 선택입니다. Claude Code는 자율 엔지니어링 에이전트가 아닌 코딩 어시스턴트로 만들어졌습니다. 우리가 계속 던진 질문은 이것이었습니다: 이것을 자율 에이전트로 변환하려면 무엇이 필요할까요?

그 답이 바로 V2 아키텍처입니다: Claude Code를 모니터링, 계획 및 검토로 감싸는 3계층 시스템입니다. 이 포스트는 우리가 무엇을 만들었고 각 계층이 왜 존재하는지 설명합니다.

수동 도구의 문제

Claude Code를 직접 실행하면 상호작용 모델은 다음과 같습니다: 작업을 주면, 작업을 수행하고, 완료됩니다(또는 막힙니다). 진행 중인지 모니터링하는 프로세스가 없고, 실행 중인 구조화된 계획도 없으며, 출력이 실제로 올바른지에 대한 제2의 의견도 없습니다.

실제로 이것은 우리가 반복해서 마주치는 3가지 실패 모드를 만듭니다:

권한 프롬프트. Claude Code는 파일을 읽고, 명령을 실행하고, 디렉토리에 접근할 수 있는 권한을 자주 요청합니다. 대화형 세션에서는 괜찮습니다. 승인하면 됩니다. 하지만 자율적으로 실행할 때, 이러한 프롬프트는 전체 세션을 멈추게 합니다. 승인해줄 사람이 없으므로 작업이 그냥 멈춥니다.

첫 번째 시도는 거의 충분하지 않습니다. Claude Code는 기술적으로 작동하는 작업을 완료하지만, 실제로 테스트할 때(앱을 실행하고, 출력을 확인하고, 엣지 케이스를 검증할 때) 조정이 필요합니다. 초기 구현은 엣지 케이스를 놓칠 수 있거나, 출력 형식이 맞지 않거나, 로컬에서는 작동하지만 프로덕션에서는 깨질 수 있습니다. 인간 엔지니어는 결과를 살펴보고, 디버깅하고, 반복합니다. Claude Code는 기본적으로 “완료”를 선언하고 기다립니다. 이것이 V2로 구축하고 있는 것입니다. Coder 에이전트가 Claude Code를 모니터링하고, 출력을 테스트하고, 실제 결과를 평가하고, 다른 패스를 위해 개선된 프롬프트를 다시 피드백하는 인간을 루프에 두는 것입니다. 일회성 도구를 반복 개발 루프로 전환하는 것입니다.

교차 검토 없음. 모델이 자신의 출력을 검토하는 것은 맹점을 가지고 있습니다. 버그를 만든 것과 같은 추론이 종종 버그가 괜찮다는 이유를 만듭니다. 다른 훈련 분포를 가진 제2의 모델은 다른 것들을 잡습니다.

이들 각각은 해결 가능합니다. 함께 V2 아키텍처가 됩니다.

V2 아키텍처 개요

시스템에는 모든 Claude Code 세션 주위에서 작동하는 3개의 계층이 있습니다:

Layer 1: Heartbeat (watchdog + supervisor)
  └─ tmux session monitor
  └─ detects stuck/permission prompts → review + auto-recover

Layer 2: Skill-Driven Dev (planning)
  └─ SKILL.md written before code
  └─ implementation blueprint

Layer 3: Dual Review (verification)
  └─ Claude Code self-review
  └─ Gemini CLI cross-review

Claude Code는 여전히 실제 코딩을 수행합니다. 계층은 이를 대체하지 않습니다. 이를 감싸는 것입니다.

계층 1: Heartbeat

Claude Code는 tmux 세션에서 실행됩니다. Heartbeat는 30초마다 해당 세션을 폴링하고 터미널 출력을 검사하는 watchdog 프로세스입니다. 한 가지를 찾고 있습니다: Claude Code의 프롬프트가 보이는지 여부, 이는 완료되었고 입력을 기다리고 있음을 나타냅니다.

SOCKET="${TMPDIR:-/tmp}/openclaw-tmux-sockets/openclaw.sock"
LAST5=$(tmux -S "$SOCKET" capture-pane -p -J -t claude-code:0.0 -S -5)
echo "$LAST5" | grep -q "❯" && echo "DONE" || echo "RUNNING"

❯는 Claude Code의 셸 프롬프트입니다. 보이면 세션은 유휴 상태입니다. 타임아웃 임계값보다 오래 보이지 않으면 뭔가 잘못된 것입니다.

Heartbeat가 막힌 세션을 감지하면, 3가지 복구 전략이 있습니다(에스컬레이션 순서): 부드러운 인터럽트를 보내거나, 같은 작업 컨텍스트로 세션을 닫고 다시 시작하거나, 오케스트레이터(Orange)에 인간 루프 개입을 호출합니다. 대부분의 막힌 세션은 1단계에서 해결됩니다.

이것은 간단해 보이고, 실제로 간단합니다. 하지만 이것이 없으면 자율 코딩 세션은 취약합니다. Claude Code는 네트워크 오류, 권한 문제 또는 진행 중이라고 자신을 설득하는 루프에서 멈춥니다. Heartbeat는 이를 침묵하는 실패에서 처리된 예외로 변환합니다.

막힌 세션만 감지하는 것 외에 또 다른 차원이 있습니다: 권한 감독입니다. Claude Code가 권한 승인을 기다릴 때, Coder 에이전트는 맹목적으로 승인하지 않습니다. Claude Code가 무엇을 시도하고 있는지 검토합니다. 이 명령은 합리적입니까? 안전합니까? 파괴적일 수 있습니까? Coder는 단순히 감시자가 아니라 감독자 역할을 합니다. 막힌 세션을 모니터링하고 인간을 대신하여 정보에 입각한 동의를 제공합니다. 이것은 자율 코딩을 안정적이고 안전하게 만듭니다.

계층 2: 스킬 주도 개발

사소하지 않은 작업이 Claude Code로 가기 전에, 오케스트레이터는 SKILL.md 파일을 작성합니다. 이것은 구조화된 구현 계획입니다. Claude Code가 실행하는 설계 문서와 동등합니다.

스킬 파일 구조:

skills/
  feature-name/
    SKILL.md    # implementation plan + steps

일반적인 SKILL.md는 다음을 포함합니다:

• Goal — 작업이 무엇인지, 완료가 무엇인지
• Reference style — 어떤 기존 코드를 모델로 삼을 것인지
• Outline — 특정 섹션 또는 단계, 핵심 기술 세부사항이 채워짐
• Implementation steps — 무엇을 할 것인지 및 순서대로 된 정렬된 목록
• Privacy/safety checklist — 커밋 전에 검증할 항목

이것은 원래 형태로 지금 읽고 있는 파일입니다. 이 블로그 포스트는 자체 SKILL.md에 대해 작성되었습니다.

계획 단계는 코드가 작성되기 전에 정밀도를 강요합니다. 모호한 작업은 구현 중간이 아니라 계획 시점에서 명확해집니다. 또한 Claude Code가 완료 시기를 추론하는 대신 성공 기준을 확인하도록 제공합니다.

또 다른 이점은 재사용입니다. 스킬은 시간이 지남에 따라 축적됩니다. 유사한 작업이 다시 나타나면, 오케스트레이터는 스킬 라이브러리에서 관련 패턴을 검색하고 처음부터 시작하는 대신 기존 계획을 조정할 수 있습니다. 시간이 지남에 따라 이것이 특정 유형의 작업을 어떻게 접근해야 하는지에 대한 기관 지식을 쌓는 방법입니다.

계층 3: 이중 검토

Claude Code가 완료되고 변경사항을 스테이징한 후, 커밋 전에 2가지 검토가 실행됩니다.

Claude Code 자체 검토. 첫 번째 검토는 Claude Code 자체를 사용합니다. 하지만 별도의 세션에서, 방금 작성한 코드가 아닌 diff를 검토합니다. 이것은 간단한 문제를 잡습니다: 남은 디버그 출력, 불완전한 구현, 잘못된 것을 테스트하는 테스트 파일.

Gemini CLI 교차 검토. 두 번째 검토는 스테이징된 diff를 Gemini에 전달합니다:

git diff --cached | gemini -p "Review this diff for: security issues, privacy leaks (IPs, emails, API keys), code quality. Output: PASSED or list of issues."

교차 검토가 더 중요합니다. 다른 훈련 분포를 가진 다른 모델은 Claude Code의 자체 검토가 놓치는 것들을 안정적으로 잡습니다. 특히 보안 문제와 개인 정보 누출입니다. 우리는 Gemini가 하드코딩된 테스트 자격증명, 공개 코드에 있으면 안 되는 내부 호스트명, Claude Code의 자체 검토가 의도적인 설계 결정으로 설명하는 로직 오류를 잡은 경우가 있습니다.

출력 형식은 엄격합니다: PASSED 또는 문제 목록입니다. 문제가 있으면 커밋이 차단되고 문제가 Claude Code로 다시 전송되어 수정됩니다. Gemini가 통과할 때까지 루프가 계속됩니다.

전체 V2 워크플로우

모두 합치면, 오케스트레이터의 AGENTS.md는 모든 코딩 작업을 위한 고정된 순서를 설명합니다:

1. memory_search → find relevant lessons and patterns from past work
2. Write SKILL.md (plan before code)
3. Launch Claude Code via tmux (with Heartbeat active)
4. Wait for Heartbeat signal: DONE
5. Gemini Review on staged diff
6. If issues: send back to Claude Code, loop
7. Commit
8. Update lessons/MEMORY.md with what was learned

1단계와 8단계는 시스템에 메모리를 제공하는 것입니다. 시작하기 전에, 오케스트레이터는 유사한 과거 작업에서의 교훈과 패턴에 대해 벡터 메모리를 검색합니다. 이전 결정, 실패 모드, 작동한 패턴입니다. 완료 후, 배운 것을 메모리로 다시 작성합니다. 시간이 지남에 따라 이것은 시스템이 특정 유형의 작업에서 측정 가능하게 개선되는 피드백 루프를 만듭니다.

이것이 아닌 것

이것은 완전히 자율적인 엔지니어링 팀이 아닙니다. 오케스트레이터(Orange)는 여전히 프로덕션에 영향을 미치거나, 재정 운영과 관련이 있거나, 중요한 아키텍처 결정을 나타내는 모든 것을 승인하기 위해 인간(Qiushi)이 필요합니다. V2 아키텍처는 일상적인 코딩 작업을 자동화합니다. 판단을 자동화하지 않습니다.

또한 Claude Code의 대체물이 아닙니다. 이것은 Claude Code의 구속 장치입니다. 코딩 품질은 여전히 Claude Code에서 나옵니다. 아키텍처는 그 품질이 확인되고, 세션이 침묵 속에서 실패하지 않으며, 시스템이 매번 처음부터 시작하는 대신 지식을 축적하도록 보장합니다.

원칙

여기의 패턴은 우리가 계속 돌아오는 패턴입니다: AI 도구는 단독일 때보다 모니터링하고, 지시하고, 출력을 확인하는 시스템에 포함될 때 가장 강력합니다. 단독 Claude Code는 강력한 코더입니다. Heartbeat, 계획 계층, 교차 검토 단계가 있는 Claude Code는 안정적인 엔지니어링 워크플로우에 더 가깝습니다.

동일한 원칙이 능력 있지만 수동적인 모든 AI 도구에 적용됩니다. 도구가 일을 합니다. 시스템은 그 일이 유지할 가치가 있는지 확인합니다.