Vibe Coding

하네스 구축 가이드

Claude Code에게 "조직 구조"를 부여하는 설정법. 가상의 팀과 전문가를 만들어 체계적으로 일하게 합니다

by Kainos·2026.4.6·10분 읽기

하네스란?

하네스(Harness)는 Claude Code에게 "조직 구조"를 부여하는 설정입니다. 회사에 여러 팀이 있고, 각 팀에 전문가가 있듯이, 하네스는 Claude Code 안에 가상의 팀과 전문가를 만들어 체계적으로 일하게 합니다.

실제 회사에 대표 → CTO → 개발팀/기획팀/QA팀이 있듯이, 하네스로 Claude Code 안에 동일한 구조를 만듭니다.

3가지 구성 요소

person

에이전트 (Agent)

개별 전문가. 특정 역할과 전문성을 가진다

.claude/agents/팀이름/이름.md

description

스킬 (Skill)

업무 절차서. 여러 에이전트가 어떤 순서로 협업하는지 정의

.claude/skills/팀이름/스킬이름/skill.md

menu_book

CLAUDE.md

프로젝트 설명서. 전체 구조와 규칙을 정의

CLAUDE.md

전체 구조 이해하기

하네스는 회사 조직도처럼 계층 구조를 가집니다. 대표(사용자)가 CTO(에이전트)에게 지시하면, CTO가 기획자, 개발자, QA에게 업무를 분배합니다.

조직 구조 예시

# 대표 (사용자)
#   └── CTO (에이전트)
#         ├── 기획자 → product-manager (전문팀 5명)
#         ├── 개발자 → api-designer, database-architect... (전문팀)
#         └── QA → code-reviewer, test-automation (전문팀)

각 전문팀은 harness-100 레포에서 가져옵니다. Anthropic이 공개한 100개의 하네스 중 프로젝트에 필요한 것만 골라 조합하면 됩니다.

숫자로 보는 예시 구조

4명

워크플로우 에이전트

14개

전문팀

74명

전문가 (에이전트)

37개

스킬

워크플로우 비교

하네스의 워크플로우는 크게 두 가지 방식이 있습니다. 작업 성격에 따라 적절한 방식을 선택합니다.

일방향 워크플로우

한 번에 쭉 진행하는 방식입니다. 명확한 요구사항이 있을 때 적합합니다.

일방향 흐름

# CTO → 기획자 → 개발자 → QA → CTO → 대표
# 방향    스펙     구현    검증   보고

반복 설계 워크플로우

대표의 피드백을 받으며 반복하는 방식입니다. 새로운 기능이나 복잡한 요구사항에 적합합니다.

설계 합의

CTO + 기획자 + 개발자가 함께 설계 → 대표 피드백 → 승인까지 반복

구현

승인된 설계대로 개발자가 코드 작성

검증 → 이슈 발견 → 수정 → 재검증 → 통과까지 반복

최종 보고

CTO가 결과를 정리하여 대표에게 전달

언제 어떤 것을 쓸까?

arrow_forward"이 버그 수정해줘"일방향

sync"포인트 시스템을 만들고 싶어"반복 설계

arrow_forward"API에 필드 하나 추가해줘"일방향

sync"새로운 결제 시스템 도입"반복 설계

verified"테스트 코드 보강해줘"QA 단독

직접 만들기 (단계별 가이드)

다른 프로젝트에서 처음부터 하네스를 만들고 싶다면 아래 순서를 따르세요.harness-100 레포에서 필요한 전문팀을 골라 조합합니다.

폴더 구조 만들기

프로젝트 루트에 다음 폴더를 생성합니다.

Terminal

mkdir -p .claude/agents .claude/skills

폴더 구조

# 프로젝트/
#   └── .claude/
#         ├── agents/       ← 에이전트(전문가) 파일
#         ├── skills/       ← 스킬(업무절차) 파일
#         └── CLAUDE.md     ← 프로젝트 설명서

역할 정의하기

프로젝트에 필요한 역할을 정합니다. 스스로에게 질문해보세요:

이 프로젝트에서 어떤 작업을 하는가?
각 작업에 어떤 전문가가 필요한가?
어떤 순서로 일이 진행되는가?

harness-100에서 전문팀 선택하기

harness-100에서 필요한 하네스를 골라 복사합니다.

전문팀 복사 예시

# 코드 리뷰 하네스 복사
cp -r harness-100/ko/21-code-reviewer/.claude/agents/* .claude/agents/code-reviewer/
cp -r harness-100/ko/21-code-reviewer/.claude/skills/* .claude/skills/code-reviewer/

여러 하네스를 합칠 때는 팀별 하위 폴더를 만들어야 합니다. 같은 이름의 파일이 다른 하네스에 존재할 수 있기 때문입니다.

팀별 폴더 구조

# .claude/agents/
#   ├── code-reviewer/      ← 21번 하네스
#   ├── test-automation/    ← 24번 하네스
#   └── api-designer/       ← 18번 하네스

에이전트 경로 수정하기

스킬 파일 안에 에이전트 경로가 적혀 있습니다. 하위 폴더로 옮겼으면 경로를 맞춰줘야 합니다.

경로 수정 예시

# 수정 전
# | style-inspector | .claude/agents/style-inspector.md |
 
# 수정 후
# | style-inspector | .claude/agents/code-reviewer/style-inspector.md |

워크플로우 에이전트 만들기 (선택)

전문팀 위에 업무 흐름을 관리하는 상위 에이전트를 만들 수 있습니다. CTO, 기획자, 개발자, QA 같은 역할입니다.

에이전트 파일 형식 (.md)

# ---
# name: cto
# description: "기술 총괄 에이전트"
# ---
 
# CTO
 
# 당신은 기술 총괄 책임자입니다.
 
# ## 핵심 역할
# 1. 기술 방향 설정
# 2. 팀 간 조율
 
# ## 팀 통신 프로토콜
# - 기획자에게: 기술 방향 전달
# - 개발자에게: 구현 지시
# - QA에게: 검증 요청

워크플로우 스킬 만들기 (선택)

여러 에이전트가 어떤 순서로 협업하는지 정의합니다.

스킬 파일 위치

# .claude/skills/workflow/build/skill.md

스킬 파일에는 에이전트 구성, 워크플로우 순서, 에러 핸들링을 정의합니다.

CLAUDE.md 작성하기

프로젝트의 전체 구조와 사용법을 정리합니다.

CLAUDE.md 기본 구조

# 프로젝트 이름
 
# ## 프로젝트 컨텍스트
# - 언어, 프레임워크, DB 등
 
# ## 조직 구조
# (조직도)
 
# ## 사용법
# (어떤 명령어로 무엇을 할 수 있는지)
 
# ## 프로젝트 규칙
# (코드 컨벤션, 테스트 방법 등)

동작 확인

Claude Code에서 스킬을 실행해봅니다.

실행 예시

/code-reviewer   # 코드 리뷰 전문팀 실행
/build           # 전체 파이프라인 실행
/document        # 문서 작성 파이프라인 실행

사용법

기능 개발 요청

대표가 Claude Code에 입력

# 자연어로 요청
포인트 시스템을 만들고 싶어
 
# 또는 /build 명령 사용
/build 포인트 시스템 개발

전문팀 직접 사용

특정 작업만 필요할 때 전문팀을 직접 호출합니다.

전문팀 직접 호출

/code-reviewer    # 이 PR 리뷰해줘
/test-automation  # 이 서비스에 테스트 작성해줘
/api-designer     # 이 API 설계해줘

산출물 확인

모든 결과물은 _workspace/ 폴더에 저장됩니다.

_workspace/ 폴더 구조

# _workspace/
# ├── A_01_cto_initial_design.md   ← CTO 초기 설계
# ├── A_02_direction.md            ← 방향 합의
# ├── A_03_design_draft.md         ← 설계 초안
# ├── A_05_report_to_ceo.md       ← 대표 보고
# ├── B_implementation.md          ← 구현 보고
# ├── C_qa_report.md               ← QA 보고
# └── D_final_report.md            ← 최종 보고

자주 묻는 질문

Q.전문팀을 더 추가하고 싶어요

harness-100에서 원하는 하네스를 골라 같은 방식으로 복사하면 됩니다. 팀별 하위 폴더를 만들어 경로를 수정하세요.

Q.워크플로우 순서를 바꾸고 싶어요

.claude/skills/workflow/build/skill.md 파일에서 Phase 순서를 수정하면 됩니다.

Q.에이전트 역할을 수정하고 싶어요

.claude/agents/팀이름/에이전트.md 파일을 열어 내용을 수정하면 됩니다. 핵심 역할, 작업 원칙, 산출물 포맷 등을 프로젝트에 맞게 조정하세요.

Q.다른 프로젝트에도 적용할 수 있나요?

.claude/ 폴더를 복사하고 CLAUDE.md의 프로젝트 컨텍스트만 수정하면 됩니다.

Q.~/.claude/와 .claude/의 차이는?

~/.claude/는 모든 프로젝트에 적용되는 범용 설정이고, .claude/는 해당 프로젝트에만 적용됩니다. 전문팀은 반드시 프로젝트의 .claude/에 넣으세요.

Q.파일 이름이 겹치면 어떻게 하나요?

하네스별로 하위 폴더를 만들면 해결됩니다. 예: .claude/agents/code-reviewer/performance-analyst.md와 .claude/agents/database-architect/performance-analyst.md는 다른 전문성을 가진 별개의 에이전트입니다.

함께 보면 좋은 도구

Claude Code OpenClaw

하네스란?

실제 회사에 대표 → CTO → 개발팀/기획팀/QA팀이 있듯이, 하네스로 Claude Code 안에 동일한 구조를 만듭니다.

3가지 구성 요소

person

에이전트 (Agent)

개별 전문가. 특정 역할과 전문성을 가진다

.claude/agents/팀이름/이름.md

description

스킬 (Skill)

업무 절차서. 여러 에이전트가 어떤 순서로 협업하는지 정의

.claude/skills/팀이름/스킬이름/skill.md

menu_book

CLAUDE.md

프로젝트 설명서. 전체 구조와 규칙을 정의

CLAUDE.md

전체 구조 이해하기

하네스는 회사 조직도처럼 계층 구조를 가집니다. 대표(사용자)가 CTO(에이전트)에게 지시하면, CTO가 기획자, 개발자, QA에게 업무를 분배합니다.

조직 구조 예시

# 대표 (사용자)
#   └── CTO (에이전트)
#         ├── 기획자 → product-manager (전문팀 5명)
#         ├── 개발자 → api-designer, database-architect... (전문팀)
#         └── QA → code-reviewer, test-automation (전문팀)

각 전문팀은 harness-100 레포에서 가져옵니다. Anthropic이 공개한 100개의 하네스 중 프로젝트에 필요한 것만 골라 조합하면 됩니다.

숫자로 보는 예시 구조

4명

워크플로우 에이전트

14개

전문팀

74명

전문가 (에이전트)

37개

스킬

워크플로우 비교

하네스의 워크플로우는 크게 두 가지 방식이 있습니다. 작업 성격에 따라 적절한 방식을 선택합니다.

일방향 워크플로우

한 번에 쭉 진행하는 방식입니다. 명확한 요구사항이 있을 때 적합합니다.

일방향 흐름

# CTO → 기획자 → 개발자 → QA → CTO → 대표
# 방향    스펙     구현    검증   보고

반복 설계 워크플로우

대표의 피드백을 받으며 반복하는 방식입니다. 새로운 기능이나 복잡한 요구사항에 적합합니다.

설계 합의

CTO + 기획자 + 개발자가 함께 설계 → 대표 피드백 → 승인까지 반복

구현

승인된 설계대로 개발자가 코드 작성

검증 → 이슈 발견 → 수정 → 재검증 → 통과까지 반복

최종 보고

CTO가 결과를 정리하여 대표에게 전달

언제 어떤 것을 쓸까?

arrow_forward"이 버그 수정해줘"일방향

sync"포인트 시스템을 만들고 싶어"반복 설계

arrow_forward"API에 필드 하나 추가해줘"일방향

sync"새로운 결제 시스템 도입"반복 설계

verified"테스트 코드 보강해줘"QA 단독

직접 만들기 (단계별 가이드)

다른 프로젝트에서 처음부터 하네스를 만들고 싶다면 아래 순서를 따르세요.harness-100 레포에서 필요한 전문팀을 골라 조합합니다.

폴더 구조 만들기

프로젝트 루트에 다음 폴더를 생성합니다.

Terminal

mkdir -p .claude/agents .claude/skills

폴더 구조

# 프로젝트/
#   └── .claude/
#         ├── agents/       ← 에이전트(전문가) 파일
#         ├── skills/       ← 스킬(업무절차) 파일
#         └── CLAUDE.md     ← 프로젝트 설명서

역할 정의하기

프로젝트에 필요한 역할을 정합니다. 스스로에게 질문해보세요:

이 프로젝트에서 어떤 작업을 하는가?
각 작업에 어떤 전문가가 필요한가?
어떤 순서로 일이 진행되는가?

harness-100에서 전문팀 선택하기

harness-100에서 필요한 하네스를 골라 복사합니다.

전문팀 복사 예시

# 코드 리뷰 하네스 복사
cp -r harness-100/ko/21-code-reviewer/.claude/agents/* .claude/agents/code-reviewer/
cp -r harness-100/ko/21-code-reviewer/.claude/skills/* .claude/skills/code-reviewer/

여러 하네스를 합칠 때는 팀별 하위 폴더를 만들어야 합니다. 같은 이름의 파일이 다른 하네스에 존재할 수 있기 때문입니다.

팀별 폴더 구조

# .claude/agents/
#   ├── code-reviewer/      ← 21번 하네스
#   ├── test-automation/    ← 24번 하네스
#   └── api-designer/       ← 18번 하네스

에이전트 경로 수정하기

스킬 파일 안에 에이전트 경로가 적혀 있습니다. 하위 폴더로 옮겼으면 경로를 맞춰줘야 합니다.

경로 수정 예시

# 수정 전
# | style-inspector | .claude/agents/style-inspector.md |
 
# 수정 후
# | style-inspector | .claude/agents/code-reviewer/style-inspector.md |

워크플로우 에이전트 만들기 (선택)

전문팀 위에 업무 흐름을 관리하는 상위 에이전트를 만들 수 있습니다. CTO, 기획자, 개발자, QA 같은 역할입니다.

에이전트 파일 형식 (.md)

# ---
# name: cto
# description: "기술 총괄 에이전트"
# ---
 
# CTO
 
# 당신은 기술 총괄 책임자입니다.
 
# ## 핵심 역할
# 1. 기술 방향 설정
# 2. 팀 간 조율
 
# ## 팀 통신 프로토콜
# - 기획자에게: 기술 방향 전달
# - 개발자에게: 구현 지시
# - QA에게: 검증 요청

워크플로우 스킬 만들기 (선택)

여러 에이전트가 어떤 순서로 협업하는지 정의합니다.

스킬 파일 위치

# .claude/skills/workflow/build/skill.md

스킬 파일에는 에이전트 구성, 워크플로우 순서, 에러 핸들링을 정의합니다.

CLAUDE.md 작성하기

프로젝트의 전체 구조와 사용법을 정리합니다.

CLAUDE.md 기본 구조

# 프로젝트 이름
 
# ## 프로젝트 컨텍스트
# - 언어, 프레임워크, DB 등
 
# ## 조직 구조
# (조직도)
 
# ## 사용법
# (어떤 명령어로 무엇을 할 수 있는지)
 
# ## 프로젝트 규칙
# (코드 컨벤션, 테스트 방법 등)

동작 확인

Claude Code에서 스킬을 실행해봅니다.

실행 예시

/code-reviewer   # 코드 리뷰 전문팀 실행
/build           # 전체 파이프라인 실행
/document        # 문서 작성 파이프라인 실행

사용법

기능 개발 요청

대표가 Claude Code에 입력

# 자연어로 요청
포인트 시스템을 만들고 싶어
 
# 또는 /build 명령 사용
/build 포인트 시스템 개발

전문팀 직접 사용

특정 작업만 필요할 때 전문팀을 직접 호출합니다.

전문팀 직접 호출

/code-reviewer    # 이 PR 리뷰해줘
/test-automation  # 이 서비스에 테스트 작성해줘
/api-designer     # 이 API 설계해줘

산출물 확인

모든 결과물은 _workspace/ 폴더에 저장됩니다.

_workspace/ 폴더 구조

# _workspace/
# ├── A_01_cto_initial_design.md   ← CTO 초기 설계
# ├── A_02_direction.md            ← 방향 합의
# ├── A_03_design_draft.md         ← 설계 초안
# ├── A_05_report_to_ceo.md       ← 대표 보고
# ├── B_implementation.md          ← 구현 보고
# ├── C_qa_report.md               ← QA 보고
# └── D_final_report.md            ← 최종 보고

자주 묻는 질문

Q.전문팀을 더 추가하고 싶어요

harness-100에서 원하는 하네스를 골라 같은 방식으로 복사하면 됩니다. 팀별 하위 폴더를 만들어 경로를 수정하세요.

Q.워크플로우 순서를 바꾸고 싶어요

.claude/skills/workflow/build/skill.md 파일에서 Phase 순서를 수정하면 됩니다.

Q.에이전트 역할을 수정하고 싶어요

.claude/agents/팀이름/에이전트.md 파일을 열어 내용을 수정하면 됩니다. 핵심 역할, 작업 원칙, 산출물 포맷 등을 프로젝트에 맞게 조정하세요.

Q.다른 프로젝트에도 적용할 수 있나요?

.claude/ 폴더를 복사하고 CLAUDE.md의 프로젝트 컨텍스트만 수정하면 됩니다.

Q.~/.claude/와 .claude/의 차이는?

~/.claude/는 모든 프로젝트에 적용되는 범용 설정이고, .claude/는 해당 프로젝트에만 적용됩니다. 전문팀은 반드시 프로젝트의 .claude/에 넣으세요.

Q.파일 이름이 겹치면 어떻게 하나요?

하네스 구축 가이드

목차

하네스란?

3가지 구성 요소

전체 구조 이해하기

워크플로우 비교

일방향 워크플로우

반복 설계 워크플로우

언제 어떤 것을 쓸까?

직접 만들기 (단계별 가이드)

폴더 구조 만들기

역할 정의하기

harness-100에서 전문팀 선택하기

에이전트 경로 수정하기

워크플로우 에이전트 만들기 (선택)

워크플로우 스킬 만들기 (선택)

CLAUDE.md 작성하기

동작 확인

사용법

기능 개발 요청

전문팀 직접 사용

산출물 확인

자주 묻는 질문

함께 보면 좋은 도구

하네스 구축 가이드

목차

하네스란?

3가지 구성 요소

전체 구조 이해하기

워크플로우 비교

일방향 워크플로우

반복 설계 워크플로우

언제 어떤 것을 쓸까?

직접 만들기 (단계별 가이드)

폴더 구조 만들기

역할 정의하기

harness-100에서 전문팀 선택하기

에이전트 경로 수정하기

워크플로우 에이전트 만들기 (선택)

워크플로우 스킬 만들기 (선택)

CLAUDE.md 작성하기

동작 확인

사용법

기능 개발 요청

전문팀 직접 사용

산출물 확인

자주 묻는 질문

함께 보면 좋은 도구