2026.05.11 / 동준상.넥스트플랫폼
(AWS SAA, AWS AIF, GCP GenAI Leader)
HARNESS.md, CLAUDE.md, SKILL.md, AGENTS.md: What to Use and When?
하네스, 클로드, 스킬, 에이전트 비교
https://nextplatform.net/harness-md-claude-md-skill-md-agents-md-what-to-use-and-when.html
핵심 정리
바이브코더가 경험하는 문제 상황
바이브코딩 프로젝트가 커질수록, 세션이 바뀔수록, 팀원이 늘어날수록 뭔가 어긋나기 시작한다. AI가 이전 결정을 잊어버리고, 코드 스타일이 제각각이고, 같은 설명을 반복해야 한다. 그리고 더 복잡한 앱을 만들려 하면 Claude가 중간에 흐지부지 마무리하거나 버그가 있는데 “잘 됩니다”라고 답한다.
바이브코더를 위한 HARNESS.md, CLAUDE.md, SKILL.md, AGENTS.md 비교 요약
| 문서 | 핵심 질문 | 소프트웨어 용어 비유 |
|---|---|---|
| HARNESS.md | 복잡한 빌드를 어떻게 자율 실행하는가? | CI/CD 파이프라인 + 멀티 에이전트 오케스트레이션 |
| CLAUDE.md | 이 프로젝트는 무엇인가? | README + Architecture Decision Records |
| SKILL.md | 코드를 어떻게 짜기로 했는가? | 디자인 패턴 라이브러리 + 팀 코딩 컨벤션 |
| AGENTS.md | 반복 작업을 어떻게 위임하는가? | Runbook + SOP (표준 운영 절차) |
아키텍처 레이어
네 문서는 독립적으로도 쓸 수 있지만 함께 있을 때 훨씬 강력하다. 아키텍처 레이어로 보면 이렇게 쌓인다.
┌──────────────────────────────────────────────┐
│ HARNESS.md 오케스트레이션 레이어 │
│ 복잡한 빌드를 Planner-Generator-Evaluator │
│ 멀티 에이전트로 자율 실행 │
├──────────────────────────────────────────────┤
│ AGENTS.md 행동 레이어 │
│ 반복 작업을 정형화된 지시로 Claude에게 위임 │
├──────────────────────────────────────────────┤
│ SKILL.md 패턴 레이어 │
│ 코드를 일관된 방식으로 작성하는 레시피 모음 │
├──────────────────────────────────────────────┤
│ CLAUDE.md 컨텍스트 레이어 │
│ 프로젝트의 기술 스택, 규칙, 현재 상태 정의 │
└──────────────────────────────────────────────┘
Claude는 작업 요청을 받으면 이 레이어를 아래에서 위로 참조한다. “이 프로젝트가 어떤 스택인지(CLAUDE.md) 파악하고, 그에 맞는 코드 패턴이 무엇인지(SKILL.md) 확인하고, 지금 요청받은 작업을 어떤 순서로 실행할지(AGENTS.md) 따르고, 필요하면 멀티 에이전트 파이프라인을 가동한다(HARNESS.md).”
HARNESS.md, CLAUDE.md, SKILL.md, AGENTS.md 비교
1. HARNESS.md — 멀티 에이전트 자율 실행 설계서
다른 세 문서가 단일 바이브코딩 세션에서 일관성을 높이는 도구라면, HARNESS.md는 완전히 다른 차원의 문서다. 앱 전체를 처음부터 끝까지 자율적으로 빌드하거나, 반나절 이상이 걸리는 대규모 스프린트를 인간의 개입 없이 실행하기 위한 멀티 에이전트 오케스트레이션 설계서다.
Anthropic 엔지니어링 팀이 GAN(생성적 적대 신경망)에서 영감을 받아 설계한 구조에 기반한다. 핵심은 두 가지 문제를 구조로 해결하는 것이다.
첫 번째 문제 — 컨텍스트 불안증: 대화가 길어지면 Claude는 작업을 조기에 마무리하려 한다. 코드가 쌓이면 “이 정도면 됐죠?”로 어설프게 끝낸다. 해법은 컨텍스트 리셋이다. 스프린트 단위로 세션을 구분하고 핸드오프 문서로 맥락을 전달한다.
두 번째 문제 — 자기 평가 편향: Claude에게 자신이 만든 코드를 평가하게 하면 거의 항상 “잘 됩니다”라고 답한다. 버그가 있어도, 디자인이 밋밋해도 관대하게 평가한다. 해법은 만드는 AI와 평가하는 AI를 분리하는 것이다.
HARNESS.md가 정의하는 세 에이전트는 이렇다.
Planner: 1~4문장의 아이디어를 완전한 제품 스펙으로 확장한다. 범위는 야심차게 잡되 세부 기술 구현은 명시하지 않는다. 세부 구현을 잘못 명시하면 오류가 하위 구현에 연쇄적으로 파급되기 때문이다.
Generator: Planner의 스펙을 스프린트 단위로 구현한다. 한 번에 하나의 기능 덩어리만 집중한다. 각 스프린트 시작 전에 Evaluator와 “완료”의 의미를 합의한다(스프린트 계약).
Evaluator: Generator가 만든 결과물을 브라우저에서 직접 클릭하며 검증한다. 코드를 읽는 것이 아니라 실제로 사용해보는 QA 에이전트다. 기능 완성도, 디자인 품질, 독창성, 사용성 네 가지 기준으로 점수를 매기고 8점 미만이면 Generator에게 피드백을 돌려보낸다.
Anthropic의 실험에서 단일 에이전트가 20분, $9에 앱을 만들었을 때 핵심 기능이 작동하지 않았다. 풀 하네스는 6시간, $200이 걸렸지만 실제로 플레이 가능한 게임이 나왔다. 풀 하네스 적용 버전은 비용도 20배로 월등히 높았지만 결과물의 신뢰도 또한 탁월한 수준으로 높아질 수 있음을 확인할 수 있었다.
2. CLAUDE.md — AI에게 건네는 프로젝트 온보딩 문서
신입 개발자가 팀에 합류하면 가장 먼저 받는 것이 온보딩 문서다. 기술 스택이 무엇인지, 폴더 구조가 어떻게 되는지, 이 팀에서 절대 하면 안 되는 것이 무엇인지를 담은 문서. CLAUDE.md는 정확히 그 역할이다. 단지 독자가 사람이 아니라 AI다.
CLAUDE.md가 없으면 어떤 일이 생기는가. Claude에게 “로그인 페이지 만들어줘”라고 하면 코드를 만들어주는데, 이미 프로젝트에서 TanStack Query를 쓰고 있는데 직접 fetch를 쓴다. 인증 상태 관리는 Context API로 만드는데 프로젝트는 Zustand를 쓴다. 결국 개발자가 뜯어고쳐야 한다. CLAUDE.md가 있으면 Claude는 처음부터 프로젝트의 기술 스택과 규칙을 알고 코드를 생성한다.
CLAUDE.md에 반드시 들어가야 할 것은 세 가지다. 첫째, 기술 스택과 버전이다. “React 18 + Vite 5, TypeScript strict mode”처럼 구체적인 버전까지 써야 한다. AI는 버전에 따라 문법과 API가 다르다는 것을 안다. 둘째, 디렉터리 구조다. 어느 폴더에 무엇이 들어가는지를 명시해야 새 파일을 엉뚱한 곳에 만들지 않는다. 셋째, 명시적인 금지 사항이다. “any 타입 금지”, “컴포넌트 내 직접 API 호출 금지”처럼 팀이 과거에 겪은 실수에서 나온 규칙들이 여기에 들어간다.
중요한 점은 CLAUDE.md가 살아있는 문서여야 한다는 것이다. 기술 결정이 바뀌면 업데이트하지 않으면 Claude에게 거짓말을 하는 셈이다.
3. SKILL.md — 코드 레시피북
소프트웨어 개발에는 디자인 패턴이라는 개념이 있다. 반복되는 문제에 대한 검증된 해법에 이름을 붙여 공유하는 방식이다. SKILL.md는 프로젝트 수준의 디자인 패턴 라이브러리다.
왜 필요한가. API 연동 코드를 예로 들자. 세션 1에서 게시글 목록을 가져오는 훅을 TanStack Query로 만들었다. 세션 2에서 사용자 프로필 훅이 필요해 Claude에게 맡겼더니 이번엔 queryKey 네이밍이 다르고 staleTime 설정도 없다. 기술적으로 작동하지만 코드베이스 전체의 일관성이 깨진다.
SKILL.md에 “SKILL-01. API 훅 패턴”을 정의해두면 Claude는 새 훅을 만들 때마다 동일한 구조로 생성한다. queryKey는 [도메인, 리소스, id] 형태로 계층화하고, staleTime은 5분이 기본이고, 조건부 실행은 enabled로 처리한다는 규칙이 코드 예시로 박혀있기 때문이다.
SKILL.md 작성의 핵심은 두 가지다. 패턴에 이름을 붙이고, 실제 코드 예시를 함께 제공해야 한다. “API 훅은 TanStack Query로 만든다”라고 글로 쓰는 것보다 “SKILL-01″이라는 이름과 실제 코드가 훨씬 강력하다. AI는 예시 코드를 그대로 모방하는 능력이 뛰어나다. 그리고 “언제 사용”을 함께 명시해야 한다. 패턴이 있어도 언제 그 패턴을 써야 하는지 모르면 소용없다.
SKILL.md는 비어있는 채로 시작해도 된다. 개발하면서 “이 코드 패턴이 마음에 든다”는 순간이 오면 그것을 SKILL-01로 등록한다. 스킬이 3개를 넘어가는 시점부터 AI가 일관된 코드를 생성하기 시작한다는 체감이 온다.
4. AGENTS.md — 반복 작업 위임 지시서
기업에서는 반복되는 업무에 SOP(표준 운영 절차)를 만든다. AGENTS.md는 개발 과정에서 반복되는 AI 위임 작업의 SOP다.
개발을 하다 보면 생각보다 많은 작업이 패턴화될 수 있다. 새 페이지를 만들 때, 컴포넌트가 너무 커져서 분리할 때, API 엔드포인트 하나가 생겼을 때, PR 올리기 전에 점검할 때. 이 작업들을 매번 Claude에게 자유형으로 설명하면 실행 결과가 일관되지 않는다.
AGENTS.md에 정형화된 호출 형식을 정의해두면 “AGENT: 신규 페이지 스캐폴딩 / INPUT: 이름, 경로, 기능 설명”만으로 동일한 품질의 결과가 나온다.
잘 만든 에이전트에는 네 가지가 있어야 한다. 목적(왜 이 에이전트가 존재하는가), 호출 형식(어떤 입력을 줘야 하는가), 실행 지시(Claude가 순서대로 따를 단계별 체크리스트), 출력 기대값(어떤 형태로 결과가 나와야 하는가)이다.
AGENTS.md는 CLAUDE.md, SKILL.md와 구분되는 결정적인 차이가 있다. CLAUDE.md와 SKILL.md가 “무엇인지”와 “어떻게 짜는지”를 정의하는 상태(State) 문서라면, AGENTS.md는 “어떤 작업을 어떤 순서로 실행하는지”를 정의하는 행동(Action) 문서다. 소프트웨어 아키텍처로 보면 CLAUDE.md와 SKILL.md는 데이터 모델이고, AGENTS.md는 메서드(함수)다.
5. 네 문서의 관계 — 무엇이 무엇을 참조하는가
네 문서는 단순히 병렬로 존재하지 않는다. 서로를 참조하는 관계가 있다.
HARNESS.md의 Generator는 코드를 작성할 때 CLAUDE.md의 기술 스택과 금지 사항을 따르고, SKILL.md의 패턴을 적용한다. HARNESS.md의 Planner는 CLAUDE.md의 기술 스택을 전제로 스펙을 작성한다. AGENTS.md의 에이전트들은 CLAUDE.md와 SKILL.md를 암묵적으로 전제한다.
역방향 참조도 있다. AGENTS.md의 에이전트를 실행하다가 너무 복잡한 작업이라고 판단되면 HARNESS.md를 호출한다. SKILL.md에 새 패턴을 추가할 때는 HARNESS.md의 Evaluator가 발견한 반복적인 버그 패턴이 소재가 된다.
6. 성능과 비용의 트레이드오프
네 문서를 모두 만들고 하네스를 풀가동하는 것이 항상 정답은 아니다. 작업의 복잡도와 기대하는 결과물의 신뢰도에 따라 적절한 조합이 달라진다.
| 작업 규모 | 권장 조합 | 예상 시간 | 예상 비용 | 신뢰도 |
|---|---|---|---|---|
| 컴포넌트 1~2개 추가 | CLAUDE.md + SKILL.md | 5~30분 | 수백 원 | 보통 |
| 페이지 단위 기능 구현 | + AGENTS.md | 30분~2시간 | 수천 원 | 높음 |
| 새 앱 전체 빌드 (소규모) | + HARNESS.md (경량) | 2~4시간 | 1~3만 원 | 높음 |
| 복잡한 풀스택 앱 빌드 | HARNESS.md 풀가동 | 4~8시간 | 10~30만 원 | 매우 높음 |
여기서 “비용”은 API 토큰 비용이다. Claude를 Claude.ai에서 쓰는 경우라면 구독 플랜 내에서 해결되지만, Claude Code나 API로 직접 호출하는 경우에는 토큰 비용이 실제 지출이 된다.
트레이드오프를 좀 더 구체적으로 보면 이렇다.
HARNESS.md를 추가할 때: 비용과 시간이 급격히 올라간다. 대신 인간이 중간에 개입하지 않아도 신뢰할 수 있는 결과물이 나온다. 새벽에 하네스를 실행해두고 아침에 결과를 확인하는 식으로 쓸 수 있다. 단, 이 조합이 빛을 발하는 조건이 있다. 작업이 충분히 복잡해서 단일 세션으로는 완성하기 어렵고, Evaluator가 자동으로 검증할 수 있는 명확한 완료 기준이 있어야 한다.
CLAUDE.md + SKILL.md만 사용할 때: 빠르고 저렴하지만 결과물의 일관성은 개발자의 리뷰에 의존한다. 단순한 기능 추가나 이미 구조가 잡힌 코드베이스에서는 이 조합이면 충분하다.
AGENTS.md를 추가할 때: 반복 작업의 품질이 표준화된다. “페이지 만들어줘”보다 “AGENT: 신규 페이지 스캐폴딩”이 항상 더 나은 결과를 낸다. 에이전트 정의에 투자하는 시간이 길게 보면 더 효율적이다.
비용 최적화 팁 하나: Anthropic의 실험에서 밝혀진 것처럼, 모델이 발전할수록 하네스의 일부 구성 요소가 불필요해진다. 6개월 전에 꼭 필요했던 컨텍스트 리셋이 새 모델에서는 필요 없어질 수 있다. 새 모델이 출시될 때마다 HARNESS.md를 점검하고 더 이상 필요 없는 비계(scaffold)를 제거하면 비용을 크게 줄일 수 있다.
7. 언제 어떤 문서부터 시작해야 하는가
네 문서를 한꺼번에 만들려 하면 시작부터 지친다. 개발 단계에 따라 순서가 있다.
프로젝트 첫날 — CLAUDE.md부터 만든다. 기술 스택, 디렉터리 구조, 금지 사항 세 가지만 채워도 충분하다. Claude에게 “기술 스택은 React + Vite + TypeScript야. 이를 바탕으로 CLAUDE.md 초안을 만들어줘”라고 하면 시작점을 빠르게 잡을 수 있다.
첫 번째 코드 패턴이 마음에 들 때 — SKILL.md를 시작한다. API 훅을 TanStack Query로 처음 만들고 나면 그것을 SKILL-01로 등록한다. 스킬이 3개를 넘으면 일관성이 눈에 보이기 시작한다.
같은 설명을 Claude에게 두 번 이상 반복할 때 — AGENTS.md를 만든다. “또 이 설명 해야 하네”라는 순간이 에이전트를 정의할 타이밍이다.
단일 세션으로 다루기 어려운 큰 작업이 생겼을 때 — HARNESS.md를 꺼낸다. 새 앱 전체 빌드, 대규모 리팩터링, 기능 집중 스프린트가 여기에 해당한다.
결론 — 오늘 당장 시작할 수 있는 액션 4가지
바이브코딩에서 “나중에 정리하자”는 거의 항상 “영원히 정리 못 한다”가 된다. AI가 빠르게 코드를 만들어주니 초기에는 잘 돌아가는 것 같지만, 프로젝트가 커질수록 AI가 만든 코드들이 서로 충돌하기 시작한다. 네 문서는 그 시점을 방지하는 구조적 보험이다.
액션 1. 지금 당장 CLAUDE.md 만들기 (15분)
기술 스택, 디렉터리 구조, 금지 사항만 채운다. Claude에게 “우리 프로젝트 스택은 X야, CLAUDE.md 초안을 만들어줘”로 시작하면 된다. 완벽하지 않아도 된다. 있는 것과 없는 것의 차이가 중요하다.
액션 2. 첫 번째 SKILL 등록하기 (10분)
오늘 Claude가 만들어준 코드 중 마음에 드는 패턴을 하나 골라 SKILL-01로 등록한다. API 호출 방식, 상태 관리 패턴, 폼 처리 방식 중 하나면 충분하다.
액션 3. 가장 자주 반복하는 작업을 에이전트로 만들기 (20분)
“또 이 설명 해야 하네”라고 느낀 순간을 떠올린다. 그것이 첫 번째 에이전트다. AGENT-01로 정의하고 다음번에 호출해본다.
액션 4. 다음 큰 기능 스프린트에서 HARNESS.md 사용해보기
당장은 필요 없을 수 있다. 하지만 “이건 단일 세션으로 무리겠는데”라는 순간이 오면 HARNESS.md를 꺼낸다. Planner에게 아이디어 한 문장을 주고 스펙을 만들어달라고 요청하는 것부터 시작한다.
참고자료 및 다운로드
- Harness 등 이들 문서는 바이브코딩의 속도를 포기하지 않으면서 소프트웨어 개발의 일관성과 신뢰도를 함께 가져가기 위한 컨텍스트 전달 기법
- AI와 협업하는 방식을 진지하게 설계하고, 나의 기반지식과 경험을 AI 에이전트와 공유하는 것이 바이브코딩 시대의 핵심 역량
Harness Architecture for Vibe Coding
https://drive.google.com/file/d/1z2lL89K40aWDWYbmBaiF5Xxi1QH2ESLo/view?usp=sharing
