[Part 2] Claude Code 하네스 기초 개념

Claude Code의 하네스 시스템을 구성하는 CLAUDE.md, 에이전트, 스킬의 개념과 역할 분리가 중요한 이유를 설명합니다.

2026.04.24 ·

harness claude ai

시리즈 목차

Part	제목
1	ConfigDeck 소개와 하네스 도입 배경
2	Claude Code 하네스 기초 개념 (현재 글)
3	ConfigDeck 하네스 구조 분석
4	하네스 기반 개발 과정
5	시행착오와 해결 과정
6	회고와 다음 단계

하네스란 무엇인가

하네스(Harness)는 원래 말이나 동물을 제어하기 위한 장비를 뜻한다. Claude Code에서 하네스는 AI의 행동을 프로젝트에 맞게 제어하고 가이드하는 문서와 설정의 집합이다.

Claude Code를 처음 사용하면 범용적인 AI 어시스턴트로 동작한다. 하네스를 구성하면 이 AI가 내 프로젝트를 이해하고, 내가 원하는 방식으로 일하는 전문가로 바뀐다.

Claude Code (범용)  +  하네스  =  프로젝트 전문 AI 팀

하네스의 핵심 구성요소

하네스는 크게 세 가지로 구성된다.

구성요소	역할	비유
CLAUDE.md	프로젝트 전체 맥락과 규칙	회사 핸드북
에이전트	특정 도메인의 전문가	팀원
스킬	반복 작업을 자동화하는 도구	업무 매뉴얼

CLAUDE.md — 프로젝트의 두뇌

CLAUDE.md는 프로젝트 루트에 위치하는 마크다운 파일이다. Claude Code가 대화를 시작할 때 가장 먼저 읽는 문서다.

여기에는 프로젝트의 기본 정보가 담긴다.

프로젝트가 무엇인지
어떤 기술 스택을 사용하는지
코딩 컨벤션은 무엇인지
어떤 규칙을 따라야 하는지

# CLAUDE.md 예시

## 프로젝트 개요
ConfigDeck은 개발자용 설정 파일 생성 서비스다.

## 기술 스택
- Astro 6 + Svelte 5
- TypeScript (strict)
- Tailwind CSS 4

## 코딩 컨벤션
- any 타입 사용 금지
- 함수는 화살표 함수로 작성
- 인라인 스타일 금지

CLAUDE.md가 없으면 Claude Code는 매번 프로젝트를 처음 보는 것처럼 행동한다. CLAUDE.md가 있으면 프로젝트의 맥락을 이미 아는 상태에서 대화가 시작된다.

에이전트 — 역할을 가진 전문가

에이전트는 특정 도메인에 특화된 AI 전문가다. .claude/agents/ 폴더에 마크다운 파일로 정의한다.

ConfigDeck에서는 12개의 에이전트를 구성했다. 몇 가지 예시를 보면:

qa-agent (QA 전문가)

# QA Agent

## 역할
코드 품질 검증과 테스트를 담당한다.

## 담당 업무
- 단위 테스트 작성 및 실행
- E2E 테스트 작성 및 실행
- 코드 리뷰

config-maker (설정 파일 전문가)

# Config Maker

## 역할
설정 파일의 스키마와 생성 로직을 담당한다.

## 담당 업무
- 옵션 스키마 설계
- 설정 파일 생성 로직 구현
- 새로운 설정 파일 타입 추가

에이전트는 해당 도메인의 하네스 문서를 로드하고 전문성을 발휘하도록 설계된다. QA 에이전트는 테스트 가이드라인을, config-maker는 스키마 설계 규칙을 참조한다.

스킬 — 반복 작업의 자동화

스킬은 반복되는 작업을 명령어 하나로 실행할 수 있게 해준다. .claude/commands/ 또는 .claude/skills/ 폴더에 정의한다.

에이전트가 “전문가”라면, 스킬은 “도구”다.

/create-pr feature/1.7.0

이 명령어 하나로 다음이 자동으로 진행된다:

커밋 히스토리 분석
변경 파일 확인
PR 본문 작성
적절한 라벨 선택
PR 생성

스킬 파일은 이런 형태로 작성한다:

# /create-pr

PR을 생성한다.

## 입력
- $ARGUMENTS: base 브랜치명

## 실행 절차
1. git log로 커밋 히스토리 확인
2. 변경 파일 목록 분석
3. PR 템플릿에 맞춰 본문 작성
4. gh pr create 실행

에이전트와 스킬의 차이

처음에는 이 둘의 구분이 명확하지 않았다. 사용하면서 깨달은 차이점이 있다.

구분	에이전트	스킬
역할	전문가	도구
범위	도메인 전체 (설계 + 구현 + 검증)	단일 작업 (검사, 생성, 보고)
호출 방식	복잡한 작업에서 자동 위임	`/스킬명`으로 직접 호출
예시	”SEO 전략 수립부터 구현까지"	"이 페이지 SEO 검사해줘”

스킬은 망치, 에이전트는 목수라고 생각하면 된다.

/lint-check → “이 코드 린트 검사해줘” (도구 사용)
qa-agent → “이 기능 전체를 검증해줘” (전문가에게 위임)

같은 도메인에 스킬과 에이전트가 모두 있는 것은 의도적이다. 작업 규모에 따라 적절한 것을 선택한다.

왜 역할 분리가 중요한가

처음에는 역할 구분 없이 사용해도 알아서 잘 동작할 줄 알았다. 그게 아니었다.

문제 상황

역할이 모호하면 이런 일이 생긴다:

간단한 린트 검사를 요청했는데 전체 코드 리뷰를 시작한다
전문적인 분석이 필요한데 표면적인 답변만 돌아온다
비슷한 요청에 매번 다른 방식으로 응답한다

해결 방법

에이전트와 스킬의 역할을 CLAUDE.md에 명확히 정의했다.

## 스킬과 에이전트의 역할 구분

- **스킬 = 도구**: 한 가지 명확한 작업을 수행한다
- **에이전트 = 전문가**: 특정 도메인의 종합적 전문성을 발휘한다

### 에이전트 위임 필수 조건

다음 요청은 반드시 전문 에이전트에게 위임한다:

| 요청 패턴 | 위임 대상 |
|-----------|-----------|
| "전반적으로 분석해줘" | 해당 도메인 에이전트 |
| "설계해줘" | ux-designer |
| "컴포넌트 구현해줘" | ui-publisher |

역할을 명확히 정의하니, 요청의 규모에 맞는 응답이 돌아오기 시작했다.

하네스 폴더 구조

ConfigDeck의 .claude/ 폴더 구조를 간략히 보면:

.claude/
├── CLAUDE.md              # 프로젝트 맥락과 규칙
├── settings.json          # 권한과 자동화 설정
├── agents/                # 에이전트 정의
│   ├── qa-agent.md
│   ├── config-maker.md
│   └── ...
├── skills/                # 스킬 정의
│   ├── create-pr/
│   ├── lint-check/
│   └── ...
├── conventions/           # 코딩/스타일링 규칙
├── decisions/             # ADR (의사결정 기록)
└── ia/                    # 기획 문서

각 폴더의 상세 내용은 Part 3에서 다룬다.

정리

구성요소	역할	파일 위치
CLAUDE.md	프로젝트 맥락, 전체 규칙	프로젝트 루트
에이전트	도메인 전문가	`.claude/agents/`
스킬	반복 작업 자동화	`.claude/skills/`

하네스의 핵심은 AI가 프로젝트를 이해하고, 일관된 방식으로 일하게 만드는 것이다. CLAUDE.md로 맥락을 주고, 에이전트로 전문성을 부여하고, 스킬로 반복 작업을 자동화한다.