Claude Code Harness로 VibeCoding 후 코드 체계 잡기: 5개 에이전트 병렬 감사 실전기

여러 명이 동시에 VibeCoding으로 만든 프로덕션 코드베이스. “잘 돌아가는데 체계가 있는 건지 모르겠다”는 상태에서 Harness 플러그인으로 전문 에이전트 팀을 구성하고, 한 세션 만에 보안 취약점부터 인터페이스 불일치까지 체계적으로 잡아낸 기록이다.

AI 코딩 도구로 VibeCoding을 하면 빠르게 동작하는 코드가 나온다. 문제는 여러 명이 동시에 진행할 때다. 각자가 Claude Code, Cursor, Codex 등 서로 다른 도구와 맥락에서 코드를 생성하고, 빌드는 통과하지만 패턴이 제각각이다. API가 보내는 필드와 프론트가 기대하는 타입이 다르고, 인증 Guard가 주석 처리된 채로 남아 있다.

이걸 어떻게 점검할 것인가. ESLint나 SonarQube 같은 기존 정적 분석 도구는 단일 파일 내의 문법/패턴 위반은 잘 잡지만, 백엔드 Controller의 응답 구조(shape)와 프론트 서비스의 타입이 일치하는지는 검증하지 못한다. GeekNews에서 Harness라는, 에이전트 팀 구성을 자동화하는 Claude Code 플러그인을 발견하고, 실제 프로덕션 프로젝트에 적용해본 경험을 정리했다.

Harness: 에이전트 팀을 설계하는 메타 스킬

Harness는 카카오 AI Native 전략 팀 리더인 황민호님(@revfactory)이 만든 Claude Code 메타 스킬 플러그인이다. “하네스 구성해줘”라고 요청하면 프로젝트를 분석하여 전문 에이전트 정의(.claude/agents/)와 작업 스킬(.claude/skills/)을 자동 생성한다. 황민호님은 Claude Code 마스터하기 가이드북, harness-100(10개 도메인 100개 프로덕션 레디 에이전트 팀, 각 하네스당 4~5개 전문 에이전트 포함) 등을 공개하며 Claude Code 생태계에서 활발히 활동하고 있다.

핵심 개념은 세 가지의 분리다.

• 에이전트 (.claude/agents/) = “누가 하는가” — 전문가 역할 정의
• 스킬 (.claude/skills/) = “어떻게 하는가” — 절차적 가이드
• 오케스트레이터 = “누가 언제 어떤 순서로” — 팀 조율

에이전트가 바뀌어도 스킬은 재사용 가능하고, 같은 에이전트가 다른 스킬을 사용할 수도 있다. 6가지 아키텍처 패턴(파이프라인, 팬아웃/팬인, 전문가 풀, 생성-검증, 감독자, 계층적 위임)을 지원하며 프로젝트 분석 결과에 따라 적합한 패턴을 선택한다. 실험 결과(Hwang, M., 2026, “Harness: Structured Pre-Configuration for Enhancing LLM Code Agent Output Quality”)에 따르면 구조화된 사전 설정이 비구조화 대비 LLM 코드 에이전트 성능을 60% 향상시키고 출력 분산을 32% 감소시켰다.

단, Harness의 효과는 CLAUDE.md에 프로젝트 코딩 규칙이 얼마나 잘 정의되어 있느냐에 크게 의존한다(CLAUDE.md 설정 방법은 설정 구성기 참고). Code Auditor가 “이 코드는 규칙 위반이다”라고 판단하려면 기준이 있어야 하고, 그 기준이 CLAUDE.md다. 규칙이 없는 프로젝트에서는 먼저 CLAUDE.md를 정비하는 선행 투자가 필요하다.

적용: Nx 모노레포에 “하네스 구성해줘”

Nx 모노레포 기반 3-Tier 웹 애플리케이션에 적용했다. Next.js 16 프론트엔드, NestJS API Gateway, TypeScript LangGraph 워크플로우 엔진으로 구성된 프로젝트에서 여러 명이 VibeCoding으로 1차 개발을 마친 상태였다. 빌드는 통과하고 기능은 동작했지만 코드 체계에 대한 확신이 없었다. 새 프로젝트를 처음부터 설계하는 것이 아니라 이미 만들어진 코드베이스에 뒤늦게 감사 체계를 구축하는 사례다.

Claude Code에서 Harness 스킬을 호출하면 코드베이스 전체를 탐색한다. 디렉토리 구조, 기술 스택, CLAUDE.md 코딩 규칙, DB 마이그레이션 히스토리, 테스트 설정까지 분석한 뒤 에이전트와 스킬을 추천했다.

flowchart TD
    O[오케스트레이터] --> F[frontend-dev]
    O --> B[backend-dev]
    F <-->|API 스펙 교환| B
    F -->|완료 알림| Q[qa-inspector]
    B -->|완료 알림| Q
    Q <-->|인터페이스 힌트| A[code-auditor]
    O --> S[security]
    Q --> R[통합 리포트]
    A --> R
    S --> R

여기서 인상적이었던 건 Harness의 추천 과정이다. 처음 요청한 건 “Frontend, Backend, QA 3개를 만들어달라”였는데, Harness가 코드베이스를 분석한 뒤 code-auditor를 추가로 제안했다. 이유는 이랬다.

VibeCoding으로 여러 명이 동시 개발한 코드베이스에서는 QA(인터페이스 정합성)와 Code Audit(내부 품질)이 서로 다른 관점입니다. QA가 “API 응답과 프론트 타입이 안 맞는다”를 잡는 동안 Code Auditor는 “디버그 로그가 수백 건 남아있고 any 타입이 곳곳에 있다”를 잡습니다.

실제로 이 분리가 정확했다. Code Auditor가 “인증 인터셉터를 우회하는 API 호출 패턴”을 발견하면 QA Inspector에게 힌트로 넘기고, QA는 같은 파일에서 인증 토큰 전달 누락까지 추가로 찾아냈다. 한 에이전트의 발견이 다른 에이전트의 검증 범위를 좁혀주는 셈이다.

Security 에이전트는 직접 요청하여 추가했다. Harness가 기본 추천한 구성에는 없었지만, Dependabot alert 해소나 secret scanning 같은 보안 조치가 별도로 필요했기 때문이다. QA가 인터페이스 정합성을, Code Auditor가 내부 품질을 본다면, Security는 의존성 취약점과 OWASP 패턴처럼 외부 위협 관점의 검증을 맡는다.

각 에이전트는 단순한 역할 설명이 아니라, 프로젝트 기술 스택에 맞춤화된 구체적 지식을 가진다. 에이전트 정의에는 “이 프로젝트에서 어떤 모듈 구조를 따라야 하는지”, “에러가 나면 어떤 에이전트에게 알려야 하는지”까지 명시되어 있다. 스킬에는 “백엔드 Controller의 반환 타입을 추출하고, 대응하는 프론트 서비스의 호출 타입과 교차 비교하라”는 식의 실행 가능한 단계가 담겨 있다. 이 때문에 에이전트가 “대충 봤는데 괜찮아 보입니다” 수준이 아니라 체계적인 감사를 수행할 수 있었다.

생성된 파일 구조는 이런 형태다.

.claude/
  agents/
    frontend.md      # 에이전트: Next.js/React 전문가 역할 + 팀 통신 프로토콜
    backend.md       # 에이전트: NestJS/LangGraph 전문가 역할
    qa-inspector.md  # 에이전트: "양쪽 동시 읽기" 원칙 명시
    code-auditor.md  # 에이전트: CLAUDE.md 규칙 기반 위반 탐지
    security.md      # 에이전트: Dependabot + OWASP 패턴
  skills/
    qa-inspection/
      skill.md       # 스킬: 6단계 검증 절차 (API shape 비교 -> 이벤트 -> 라우팅 -> ...)
      references/
        integration-checklist.md  # 프로젝트 전용 상세 체크리스트
    code-audit/
      skill.md       # 스킬: 6단계 감사 절차 (데드코드 -> 패턴 -> 중복 -> ...)
    orchestrator/
      skill.md       # 오케스트레이터: Mode A/B/C 정의

에이전트 정의에는 역할뿐 아니라 팀 통신 프로토콜(“누구에게 무엇을 SendMessage하는지”)과 에러 핸들링 방침이 포함된다. 스킬에는 구체적인 Grep 패턴, 비교 절차, 리포트 형식이 담겨 있다. 이 분리 덕분에 에이전트를 교체하더라도 스킬의 검증 절차는 그대로 재사용 가능하다.

감사 실행: 에이전트별 발견 사항

오케스트레이터에는 세 가지 실행 모드가 정의되어 있다. Mode A(개발 — 프론트/백엔드 에이전트가 기능 구현), Mode B(코드 감사 — 감사 에이전트들이 품질/보안 점검), Mode C(통합 — A와 B를 순차 실행). 이번에는 이미 개발이 끝난 코드베이스를 점검하는 것이므로 Mode B를 실행했다. code-auditor와 qa-inspector가 병렬로 감사하고, security 에이전트가 별도로 보안 점검을 수행했다.

QA Inspector: 인터페이스 불일치

가장 가치 있었던 건 QA Inspector의 “양쪽 동시 읽기” 검증이다. 한쪽만 읽어서는 절대 발견할 수 없는 불일치들이다.

인터페이스 불일치의 Before/After 예시: 백엔드 DTO는 6개 필드만 정의하는데 프론트 타입은 10개 필드를 선언한다. 백엔드에 없는 4개 필드는 실제 데이터가 내려오지 않아 undefined로 표시된다.

// Before: 백엔드 DTO (6개 필드만 정의)
interface ProjectSummary {
  id: string; name: string; status: string;
  projectType: string; progress: number; lastActivity: string;
}

// Before: 프론트 타입 (10개 필드 — 4개가 백엔드에 없음)
interface ProjectSummary {
  id: string; name: string; status: string;
  projectType: string; progress: number; lastActivity: string;
  phase: string;        // <- undefined 표시
  currentStep: number;  // <- undefined 표시
  totalSteps: number;   // <- undefined 표시
  createdAt: string;    // <- undefined 표시
}

대부분의 검증 항목은 통과했지만, 영향도가 높은 불일치가 여러 건 발견되었다:

• NestJS Controller의 인증 Guard가 주석 처리된 채 배포 직전 — 사용자 목록 API의 @UseGuards(AuthGuard) 데코레이터가 비활성화되어 있어, 로그인 없이 전체 사용자 정보를 조회할 수 있는 상태였다. 전체 Controller를 전수 검사해야 발견 가능한 항목
• 같은 파일에서 API 4개 중 2개만 인증 토큰을 전달 — 삭제와 검색은 토큰을 보내는데 목록 조회는 누락. 인증 강화 시 즉시 깨지는 시한폭탄
• 프론트가 표시하는 값과 백엔드가 실제 사용하는 값의 불일치 — 프론트 설정 화면에 표시된 항목과 백엔드가 실제로 처리하는 항목이 달랐다. 프론트/백엔드를 각자 다른 세션에서 VibeCoding하면서 상수 정의가 동기화되지 않은 전형적인 사례

이런 종류의 버그는 ESLint, SonarQube 같은 단일 파일 정적 분석으로는 잡을 수 없다. 두 파일을 동시에 열고 shape을 대조하는 “교차 비교”가 필요하고, 그게 QA Inspector의 핵심 역할이었다.

Code Auditor: 패턴 불일치

VibeCoding 특유의 패턴이 드러났다. Claude, Cursor, Codex 등 다양한 AI 코딩 도구로 독립적으로 코드를 생성하면서:

• 한 기능 모듈은 공용 HTTP 클라이언트(인터셉터 포함)를 쓰고, 다른 모듈은 라이브러리를 직접 호출 — 인증 토큰 갱신이 일부에서만 동작
• 같은 역할의 디렉토리가 모듈마다 다른 이름 — 코드 탐색 시 혼란
• 디버그용 로그가 다수의 컴포넌트에 정리되지 않은 채 잔존

기능에는 영향이 없어서 빌드/테스트로 잡히지 않지만, 유지보수 비용을 높이는 항목들이 상당수 발견되었다.

Security Agent: 보안 취약점 + 코드 보안

Dependabot이 보고한 취약점들을 분석하여 직접/간접 의존성을 구분하고 조치 우선순위를 자동으로 세웠다. 코드 보안 패턴 검증에서는 XSS, SQL injection, 스택 트레이스 노출 등 주요 항목은 양호했으나, DB 마이그레이션 파일에 API 키가 하드코딩된 것과 CORS가 모든 origin을 허용하는 상태가 발견되었다.

조치: 서브에이전트 병렬 수정과 실행 모드 선택

에이전트 팀 모드의 현실

처음에는 Harness가 권장하는 에이전트 팀 모드(TeamCreate)로 시도했다. 팀원들이 SendMessage로 직접 통신하고 공유 작업 목록으로 자체 조율하는 방식이다. 그런데 세션 토큰 한도에 도달하면서 팀원들이 idle 상태를 반복하며 작업을 시작하지 못했다. 팀 모드는 각 에이전트가 독립 세션을 유지하므로 토큰 소비가 빠르고, 한도에 걸리면 전체 팀이 멈추는 구조적 문제가 있었다.

서브에이전트 방식으로 전환했다. 메인 세션이 서브에이전트를 백그라운드로 생성하고 결과만 수집하는 구조라 토큰을 더 효율적으로 쓴다. 3개 서브에이전트를 병렬로 실행하여 독립적인 파일 그룹을 동시에 수정했다.

frontend-fixes가 가장 무거웠다. 디버그 로그가 100여 건 넘게 남아 있어서 삭제하면서도 catch 블록의 에러 처리 흐름은 유지해야 하고, 미사용 변수가 생기면 lint 에러를 방지하기 위해 변수도 함께 제거해야 했다.

여기서 중요한 점은 에이전트가 수정한 코드를 무비판적으로 적용하지 않았다는 것이다. 모든 수정은 lint 검증을 거쳤고, 빌드 통과를 확인했으며, PR 단위로 AI 코드 리뷰까지 받았다. AI 에이전트의 수정에도 사람의 검토가 필수다.

조치 요약

기존 도구와의 비교: Harness는 무엇이 다른가

Harness의 가치를 정확히 이해하려면 기존 코드 품질 도구와 비교해야 한다.

핵심 차이는 파일 간 교차 비교다. “이 Controller가 보내는 응답 구조(shape)와 저 서비스 파일이 기대하는 타입이 일치하는가”는 ESLint나 SonarQube의 영역이 아니다. OpenAPI/Swagger 기반의 계약 테스트(contract testing)가 이 문제를 해결하는 전통적 방법이지만, 이미 만들어진 코드베이스에 사후 적용하기는 어렵다. Harness는 코드 분석 기반으로 이 교차 비교를 수행한다.

물론 Harness가 기존 도구를 대체하는 것은 아니다. ESLint로 잡을 수 있는 건 ESLint로 잡고, 그 위에 Harness로 인터페이스와 프로젝트 규칙을 검증하는 레이어를 추가하는 것이 이상적이다. 실제로 이번 프로젝트에서도 ESLint가 상당수의 warning을 이미 보고하고 있었고, Harness는 그 위에서 ESLint가 커버하지 못하는 영역을 검증했다.

토큰 비용과 ROI: 언제 쓸 만한가

이 모든 작업이 하나의 Claude Code 세션에서 이루어졌다.

서브에이전트 토큰 (측정 가능):

Claude Code Max(월 $100)를 사용하고 있는데, 이 세션에서 토큰 한도를 완전히 소진했다. 다만 570K 전부가 Harness 감사에 쓰인 것은 아니다. 세션 초반에 다른 작업으로 일부 토큰을 사용한 상태였고, 이후 TeamCreate(팀 모드)로 에이전트를 실행하면서 각 에이전트가 독립 세션을 유지하는 구조 때문에 토큰 소비가 급격히 늘어났다. 팀 에이전트가 idle을 반복한 것도 이 한도 도달이 원인이었다. 토큰당 단가로 환산하기는 어렵지만 조직 규모별 ROI를 생각해보면:

이번 사례에서 전체 Controller 전수 검사, 모든 API 엔드포인트의 응답 구조(shape) 교차 비교, Dependabot 취약점 분석까지 수동으로 했다면 최소 1~2일이 걸렸을 것이다. Harness로는 하네스 구성부터 PR merge까지 하루(~6시간 실작업) 만에 완료했다. 다만 이것은 단일 사례의 관찰이므로, 프로젝트 규모와 기존 코드 품질 체계에 따라 효과는 달라질 수 있다.

적용 범위와 한계

이런 상황에서 Harness가 적합하다

• VibeCoding 후 코드 체계 점검 — 빠르게 만든 코드의 품질을 사후 검증
• 모노레포에서 인터페이스 검증 — 프론트/백엔드/워크플로우 엔진 사이의 타입/이벤트 정합성
• 팀 개발 시 일관성 유지 — 여러 사람이 동시에 작업할 때 패턴 불일치 방지
• 보안 감사 자동화 — Dependabot + 코드 보안 패턴 일괄 점검

한계와 주의점

• CLAUDE.md 선행 투자가 필수 — 프로젝트 코딩 규칙이 없으면 Code Auditor의 판단 기준이 없다. 규칙 작성에 수 시간의 선행 투자가 필요하다
• 토큰 소비가 상당하다 — 전체 ~570K 토큰은 소설 한 권(약 20만 자) 분량을 훌쩍 넘는 양이다. 작은 프로젝트에는 과할 수 있다
• 에이전트 팀 모드의 안정성 — 세션 토큰 한계에 민감하다. 서브에이전트 방식이 현재로서는 더 안정적
• false positive — Code Auditor가 지적하는 모든 항목이 실제 문제는 아니다. any 타입의 경우 LangChain 라이브러리 타입 한계로 불가피한 경우가 있다
• 런타임 검증이 아니다 — 코드 분석 기반이므로 동적 라우팅이나 조건부 응답은 검증하지 못한다
• 인간 감독이 필수 — 에이전트가 제안한 수정을 무비판적으로 적용하면 안 된다. PR 리뷰, lint 검증, 빌드 확인을 거쳐야 한다

Harness가 있으면 기존 도구(ESLint, TypeScript strict, contract testing)가 불필요한 것이 아니다. 기존 도구가 커버하지 못하는 영역을 보완하는 추가 레이어로 위치시키는 것이 현실적이다.

마무리

하루 동안 하네스 구성부터 감사 실행, 수정, PR merge까지 완료했다. 가장 큰 수확은 “인증 Guard 주석 처리”라는 보안 이슈를 배포 전에 잡은 것이다.

Harness의 진짜 가치는 “에이전트를 만들어주는 것”이 아니라, 프로젝트 맥락을 이해하고 어떤 관점의 검증이 필요한지를 판단해주는 것이다. QA와 Code Audit을 분리하고 Security를 별도로 두라는 추천이 결과적으로 정확했다. 각 에이전트가 서로 다른 관점에서 동일한 코드베이스를 보면서 교차 발견한 항목들이 가장 유의미했다.

VibeCoding으로 빠르게 만들고, Harness로 체계를 잡는 — 이 조합이 현실적인 AI 코딩 워크플로우가 될 수 있을 것이다. Claude Code 설정과 스킬 체계에 대한 더 자세한 내용은 이전에 작성한 Claude Code 설정 구성기에서도 다루고 있다.