개요
새 직원이 첫 출근을 했다. 실력은 뛰어나지만 팀의 코딩 컨벤션을 모르고, 어떤 프레임워크를 쓰는지도 모르고, PR 리뷰 기준도 모른다. 그래서 온보딩 문서를 준비하고, 코드 스타일 가이드를 알려주고, 자주 쓰는 패턴을 설명한다. 시간이 걸리지만 한 번 제대로 가르쳐 두면 그 이후로는 맥락 없이도 올바른 방향으로 일한다.
Claude Code를 쓸 때 매번 같은 설명을 반복하는 것은 이 온보딩이 매일 리셋되는 것과 같다. Harness는 이 문제를 해결하는 프레임워크다. 프로젝트의 코딩 방식, 선호하는 라이브러리, 팀의 규칙을 한 번 정의해 두면 Claude Code가 세션마다 그 맥락을 그대로 이어받는다. 설치는 한 번이지만 절약은 장기적으로 누적된다.
하니스란 무엇인가
Harness는 Claude Code에 지속적인 컨텍스트를 제공하는 구성 시스템이다. CLAUDE.md가 단일 마크다운 파일로 프로젝트 전반의 지시사항을 담는 방식이라면, Harness는 더 구조화된 방식으로 AI의 행동을 정의한다. 핵심 구성 요소는 Skills(스킬), Agents(에이전트), Commands(커맨드) 세 가지다.
Harness가 없을 때 Claude Code는 범용 AI다. FastAPI를 쓸 수도, Django를 쓸 수도 있고, 의존성을 추가하는 방식도, 에러 처리 패턴도 프로젝트마다 다를 수 있다. Harness를 설치하면 Claude Code는 이 프로젝트에서는 FastAPI를 쓰고, Pydantic v2로 스키마를 정의하고, 에러 응답은 특정 형식을 따른다는 사실을 처음부터 알고 시작한다. 이 차이는 단순히 편의의 문제가 아니라 AI 출력 품질과 일관성에 직접적으로 영향을 미친다.
Harness를 새 직원 비유로 설명하면 이해가 빠르다. 실력 있는 신입 직원도 팀 컨텍스트 없이는 엉뚱한 방향으로 일할 수 있다. 매번 팀 리더가 맥락을 설명해야 한다면 그 비용은 개인의 생산성이 아닌 팀 전체에서 반복적으로 지불된다. Harness는 이 반복 비용을 초기 설치 한 번으로 대체한다.
하니스의 3가지 핵심 개념
스킬 — 전문 지식 문서
스킬은 Claude Code에게 특정 영역의 패턴을 가르치는 마크다운 문서다. “FastAPI 백엔드를 이 프로젝트에서 어떻게 구조화하는가”, “Next.js 컴포넌트를 어떤 규칙으로 만드는가”, “Mermaid 다이어그램을 어떻게 표현하는가” 같은 전문 지식을 담는다. 스킬 파일은 Claude Code의 행동을 범용에서 전문화로 전환하는 핵심 메커니즘이다.
아래는 FastAPI 백엔드 스킬 파일이 어떤 형태를 가질 수 있는지 보여주는 예시다.
# FastAPI Backend Skill
## 프로젝트 구조
- 라우터는 `app/routers/` 에 도메인별로 분리
- 스키마는 Pydantic v2 (`app/schemas/`)
- 의존성 주입은 `app/dependencies.py`
## 응답 형식
성공 응답:
{
"success": true,
"data": { ... }
}
에러 응답:
{
"success": false,
"error": { "code": "...", "message": "..." }
}
## 코딩 규칙
- async/await 필수 — 동기 엔드포인트 금지
- 모든 엔드포인트에 response_model 명시
- HTTPException 대신 커스텀 AppException 사용
이처럼 스킬 파일은 Claude Code가 코드를 생성할 때 참조하는 팀의 결정들을 문서화한다. 스킬은 단순한 스타일 가이드가 아니라 AI의 의사결정 기준이 된다. 팀의 규칙이 바뀌면 스킬 파일을 업데이트하면 되고, 그 이후로 Claude Code의 출력도 자동으로 갱신된다.
스킬의 진가는 범위가 넓어질수록 드러난다. FastAPI 스킬, Next.js 스킬, 데이터베이스 마이그레이션 스킬, PDF 생성 스킬, Mermaid 다이어그램 스킬을 각각 정의해 두면, Claude Code는 그 스택 전반에 걸쳐 일관된 방식으로 코드를 작성한다. 모든 지식을 매번 프롬프트에 포함시킬 필요 없이 Harness가 필요한 스킬을 자동으로 불러온다.
에이전트 — 목적 특화 AI 인스턴스
에이전트는 특정 역할에 맞게 사전 구성된 Claude Code 인스턴스다. 플래너(Planner), 플랜 리뷰어(Plan Reviewer), 웹 리서치 스페셜리스트처럼 역할별로 다른 에이전트를 정의할 수 있다. 각 에이전트는 자신이 해야 할 일, 어떤 스킬을 참조해야 하는지, 어떤 도구를 사용할 수 있는지를 미리 설정해 둔다.
플래너 에이전트는 새 기능 구현 전에 세부 실행 계획을 작성하는 역할을 담당한다. 플랜 리뷰어 에이전트는 플래너가 만든 계획의 빈틈을 찾아 피드백을 제공한다. 웹 리서치 스페셜리스트는 최신 라이브러리 정보나 기술 문서를 검색하는 역할을 맡는다. 이처럼 에이전트를 역할로 분리하면 단일 범용 AI가 모든 것을 처리하려는 것보다 훨씬 예측 가능하고 신뢰할 수 있는 결과를 얻을 수 있다.
커맨드 — 슬래시 하나로 워크플로우 실행
커맨드는 반복적으로 수행하는 작업 흐름을 슬래시 명령어 하나로 실행할 수 있게 만드는 매크로다. /review-pr, /generate-schema, /write-tests 같은 커맨드를 정의해 두면, 복잡한 프롬프트를 매번 작성할 필요 없이 커맨드 하나로 전체 워크플로우를 트리거한다. 이 log-blog 프로젝트에서 쓰는 Claude Code 스킬도 같은 원리로 동작한다.
실전 스킬 목록 — FastAPI부터 Mermaid까지
Harness 생태계에서 실제로 활용되는 스킬들은 프로젝트의 기술 스택을 따라 구성된다. FastAPI 백엔드 스킬은 라우터 구조, 스키마 패턴, 에러 처리 방식을 정의하고, Next.js 프론트엔드 스킬은 컴포넌트 명명 규칙, 상태 관리 방식, API 호출 패턴을 정의한다.
Mermaid 다이어그램 스킬은 Claude Code가 다이어그램을 생성할 때 자주 발생하는 문법 오류를 방지하는 규칙을 담는다. 예를 들어, Mermaid v11에서는 \n이 노드 라벨의 줄바꿈으로 동작하지 않으며 Hugo Stack 테마에서는 <br/> 대신 <br/>를 써야 한다는 규칙을 스킬에 명시해 두면, Claude Code가 다이어그램을 만들 때마다 이 규칙을 자동으로 따른다.
# Mermaid Diagram Skill
## Hugo Stack 테마 규칙
- 노드 라벨 줄바꿈: `<br/>` 사용 (NOT `\n`, NOT `<br/>`)
- 슬래시 포함 라벨은 반드시 따옴표로 감쌀 것: `['label/text']`
- 이중 따옴표 금지 — Hugo 파싱 충돌 가능성
- 한 다이어그램의 오류가 페이지 전체 다이어그램을 숨김 처리하므로
문법 검증 철저히
## 허용 다이어그램 타입
flowchart TD, graph TD, sequenceDiagram, classDiagram
PDF 및 PPTX 문서 도구 스킬, 웹 디자인 리뷰 스킬도 각각의 도메인에서 Claude Code가 일관된 방식으로 산출물을 만들도록 가이드한다. 스킬의 수가 많아질수록 Claude Code는 프로젝트 전반에 걸쳐 더 일관되고 예측 가능한 결과를 낸다.
에이전트 팀 구성
Harness의 에이전트 설계에서 흥미로운 점은 단일 AI가 모든 역할을 수행하는 것이 아니라, 역할별로 최적화된 에이전트들이 협력하는 팀 구조를 만든다는 것이다. 개발 팀이 개발자, 리뷰어, 리서처로 역할을 나누는 것처럼 AI 에이전트도 같은 방식으로 구성한다.
플래너 에이전트는 구현에 들어가기 전에 세부 계획을 먼저 수립한다. 어떤 파일을 수정해야 하는지, 어떤 순서로 작업해야 하는지, 잠재적 위험 요소는 무엇인지를 정리한다. 플랜 리뷰어 에이전트는 이 계획을 독립적으로 검토해서 빠뜨린 엣지 케이스나 잘못된 가정을 찾아낸다. 이 두 에이전트의 협력은 단일 에이전트가 계획과 실행을 동시에 담당할 때 발생하는 자기 확증 편향을 줄인다.
웹 리서치 스페셜리스트 에이전트는 최신 API 문서, 라이브러리 변경사항, 기술적 레퍼런스를 찾는 역할에 특화된다. 범용 Claude Code에게 “최신 Pydantic v2 문서를 참고해서"라고 매번 지시하는 대신, 리서치 에이전트가 자율적으로 필요한 정보를 수집하고 정리해서 실제 구현 에이전트에 전달한다. 이 분업 구조는 각 에이전트가 자신의 역할에 집중하면서 전체 워크플로우의 품질을 높인다.
범용 AI vs 전담 전문가
Harness가 제기하는 질문은 AI 도구 사용 방식에 대한 더 근본적인 관점을 담고 있다. 범용 AI는 무엇이든 할 수 있지만 특정 맥락에서는 최적이 아닐 수 있다. 전담 전문가는 범위가 좁지만 그 범위 안에서는 훨씬 예측 가능하고 신뢰할 수 있는 결과를 낸다.
소프트웨어 개발 팀에서 모든 역할을 한 사람이 담당하는 것보다 전문화된 역할 분담이 전체 생산성을 높이는 것처럼, AI 에이전트도 마찬가지 원리가 적용된다. Harness는 Claude Code라는 강력한 범용 AI에 프로젝트별 전문성을 덧입혀 전담 직원으로 만드는 프레임워크다.
개발자가 AI를 길들이는 데 6개월이 걸렸다는 경험담은 이 과정이 단순하지 않음을 보여준다. 어떤 스킬을 정의할지, 에이전트를 어떻게 분리할지, 커맨드를 어떤 수준으로 추상화할지는 프로젝트와 팀의 특성에 따라 달라진다. 하지만 한 번 제대로 구성해 두면 그 이후의 세션마다 반복적으로 쌓이는 절약이 초기 투자를 빠르게 회수한다.
빠른 링크
- 하니스 완전 공개 — Claude Code AI를 내 전담 직원으로 만드는 법 — 메이커 에반 채널, 설치부터 스킬/에이전트/커맨드 실습까지 (5분 13초, 7,800 views)
- 개발자가 AI 길들이는 데 6개월 걸린 이유 — 메이커 에반 이전 영상, 시행착오 전부 공개 (11만 views)
인사이트
Harness는 기술적으로 새로운 발명이 아니다. 마크다운 파일과 구성 시스템의 조합으로 이루어진다. 하지만 이 단순한 조합이 Claude Code 사용 경험을 질적으로 바꾸는 이유는 AI와 일하는 방식에 대한 관점의 전환에서 비롯된다. 매 세션마다 처음부터 설명하는 방식에서, 한 번 설정하고 영구히 기억하게 만드는 방식으로의 전환이다. 스킬, 에이전트, 커맨드의 삼분 구조는 각각 지식의 문서화, 역할의 전문화, 워크플로우의 자동화라는 서로 다른 문제를 해결한다. 팀 컨텍스트를 AI에 전달하는 가장 좋은 방법은 가장 명시적인 방법이다. Harness의 스킬 파일은 팀의 암묵적 지식을 명시적 문서로 강제 전환하는 효과도 있다. 이 과정에서 팀원들이 당연하게 여기던 규칙들이 처음으로 문서화되는 부수적 효과도 생긴다. 에이전트를 역할로 분리하는 설계는 단일 AI가 자기 자신의 계획을 검토하는 자기 확증 편향을 줄이는 데 실질적 효과가 있다. 초기 설치에 투자하는 시간을 장기 절약의 관점에서 계산하면 ROI는 대부분의 개발 도구 투자보다 빠르게 나타난다. 특히 같은 기술 스택을 반복적으로 다루는 팀이나 개인 개발자일수록 Harness의 가치는 더 빠르게 체감된다.