Claude Code 하네스: 1인 개발자가 AI 에이전트 팀을 만드는 법

혼자 개발을 하다 보면 이상한 순간이 찾아옵니다. 백엔드 API를 짜다가 프론트엔드 컴포넌트로 넘어가고, 타입을 맞추다가 테스트를 작성하고, 테스트를 돌리다가 다시 백엔드로 돌아옵니다. "댓글 기능 추가해줘"라는 한 마디가 실제로는 API 설계, 컴포넌트 구현, 타입 동기화, 테스트, PR까지 이어지는 긴 여정이라는 걸, 1인 개발자라면 잘 아실 겁니다.

Claude Code에 이런 작업을 통째로 맡겨본 적이 있습니다. 한 번에 하나의 일은 꽤 잘 해냅니다. 그런데 백엔드와 프론트엔드를 동시에 진행하면서 타입을 맞추고, QA까지 자체적으로 수행하는 건 다른 차원의 문제였습니다. 결국 전문가 팀을 미리 정의해두고, 오케스트레이터가 조율하게 하면 어떨까라는 생각에 도달했습니다. 그렇게 만들기 시작한 것이 Claude Code 하네스입니다.

하네스라는 구조

하네스는 세 가지 요소로 구성됩니다. 에이전트, 스킬, 그리고 오케스트레이터입니다.

에이전트는 전문가의 페르소나를 정의한 파일입니다. .claude/agents/ 폴더에 마크다운으로 존재합니다. 핵심 역할이 무엇인지, 어떤 원칙으로 작업하는지, 다른 에이전트와 어떻게 소통하는지를 담고 있습니다. 파일로 존재하기 때문에 세션이 바뀌어도 같은 전문가를 다시 불러올 수 있습니다. 예를 들어 backend-dev는 NestJS와 데이터베이스에 특화된 전문가이고, frontend-dev는 Next.js와 React에 집중하는 전문가입니다.

스킬은 절차적 가이드입니다. "어떤 순서로 무엇을 하는가"를 정의한 업무 매뉴얼이라고 보면 됩니다. 여기서 중요한 점은 Progressive Disclosure 방식을 따른다는 것입니다. 메타데이터는 항상 로드되지만, 본문은 트리거될 때만, 레퍼런스는 필요할 때만 불러옵니다. AI의 컨텍스트 윈도우는 유한하기 때문에, 필요한 정보만 필요한 시점에 제공하는 것이 핵심입니다.

오케스트레이터는 스킬의 특수한 형태입니다. 에이전트 팀을 구성하고, 작업 순서와 통신 규칙을 정의합니다. 비유하자면 에이전트는 팀원의 이력서, 스킬은 업무 매뉴얼, 오케스트레이터는 프로젝트 매니저의 실행 계획서에 해당합니다.

에이전트 팀과 서브 에이전트

하네스를 실행하는 방식은 두 가지입니다.

에이전트 팀 모드에서는 팀원들이 서로 직접 대화합니다. 공유 작업 목록을 통해 자체적으로 조율하고, 서로의 결과물을 검증하기도 합니다. 백엔드 개발자가 API 스펙을 완성하면 프론트엔드 개발자에게 직접 전달하는 식입니다. 에이전트 간 실시간 소통이 필요한 작업에 적합합니다.

서브 에이전트 모드는 더 가볍습니다. 각 에이전트를 개별적으로 호출하고, 결과만 받아서 종합합니다. 에이전트끼리는 서로의 존재를 모릅니다. 독립적인 결과를 모아서 하나로 합치면 되는 작업에 씁니다.

어떤 모드를 선택할지는 작업의 성격에 달려 있습니다. 풀스택 기능 개발처럼 백엔드와 프론트엔드가 맞물려야 하는 작업은 에이전트 팀이, 여러 소스에서 독립적으로 정보를 수집하는 리서치 같은 작업은 서브 에이전트가 적합합니다.

monorepo-dev: 풀스택 개발을 위임하다

가장 먼저, 그리고 가장 깊이 만들었던 하네스가 monorepo-dev입니다. NestJS 백엔드와 Next.js 프론트엔드가 공존하는 모노레포에서, 풀스택 기능 개발의 전체 라이프사이클을 자동화하는 것이 목표였습니다.

팀 구성

세 명의 전문가로 팀을 구성했습니다. backend-dev는 NestJS API와 데이터베이스 스키마, 유닛 테스트를 담당합니다. frontend-dev는 Next.js 페이지와 React 컴포넌트, E2E 테스트를 맡습니다. qa-integrator는 양쪽의 결과물을 교차 검증하고, 빌드 확인과 영상 녹화까지 수행합니다.

워크플로우

작업은 격리된 환경에서 시작합니다. Git worktree로 별도의 작업 공간을 만들고, 별도 브랜치에서 진행합니다. 메인 코드에 영향을 주지 않기 때문에 실패해도 안전합니다.

요구사항이 정리되면 에이전트 팀이 구성됩니다. backend-dev와 frontend-dev가 병렬로 구현을 시작합니다. API 스펙이 완성되면 backend-dev가 frontend-dev에게 직접 전달하고, 각자 테스트도 함께 작성합니다.

양쪽 구현이 끝나면 qa-integrator가 등장합니다. 공유 타입이 실제로 일치하는지, 전체 빌드가 통과하는지, 유닛 테스트와 E2E 테스트가 모두 성공하는지를 확인합니다. 문제가 발견되면 해당 에이전트에게 수정을 요청합니다. Playwright로 E2E 테스트를 실행하면서 영상도 녹화하기 때문에, 사용자는 영상과 QA 보고서만 확인하면 됩니다.

QA를 통과하면 자동으로 커밋, 푸시, PR 생성까지 이어집니다. 여기서 끝이 아닙니다. 별도의 코드 리뷰 에이전트가 PR을 검토하고, 피드백이 있으면 수정과 재리뷰를 반복합니다.

이 구조가 잡아내는 것

솔직히 말하면, 하나의 프롬프트로 백엔드와 프론트엔드를 동시에 시키면 타입 불일치 같은 통합 버그가 자주 발생했습니다. 백엔드가 반환하는 필드명과 프론트엔드가 기대하는 필드명이 다르다거나, 응답 구조가 미묘하게 어긋나는 문제들입니다. qa-integrator가 이런 틈을 잡아냅니다. 역할을 분리하고, 검증하는 사람을 따로 두는 것만으로도 품질이 눈에 띄게 달라졌습니다.

워크트리 격리도 생각보다 큰 안전망이었습니다. 에이전트가 잘못된 방향으로 가더라도 메인 브랜치는 무사합니다. 부담 없이 실험할 수 있다는 것 자체가 이 구조의 숨은 장점이었습니다.

하네스가 바꿔놓은 것

하네스를 만들면서 가장 크게 느낀 점은, AI에게 일을 잘 시키는 것도 결국 조직 설계의 문제라는 것이었습니다. 한 명에게 모든 걸 맡기는 것보다, 전문가를 나누고 조율하는 구조를 만드는 편이 훨씬 안정적입니다.

복잡한 작업을 한 마디로 위임할 수 있게 되었습니다. 한번 정의해둔 에이전트는 다른 하네스에서도 재사용할 수 있습니다. 한 에이전트가 실패하더라도 전체가 무너지지 않습니다. 무엇보다, 컨텍스트 스위칭에 쓰던 에너지를 다른 곳에 쓸 수 있게 되었습니다.

다음 편에서는 같은 하네스 구조를 리서치, 웹 디자인, 블로그 글쓰기, 블로그 분석, 데이터 파이프라인에 적용한 사례를 다루려고 합니다. 하나의 구조가 얼마나 다양한 영역에 확장될 수 있는지, 그리고 각 영역에서 어떤 패턴이 반복되는지를 정리해볼 생각입니다.