본문으로 건너뛰기

[1편] Claude Code 하네스로 '알아서 개발하는' MVP 공장 만들기 — 하네스란 무엇인가

Todd

2026.10.09

[1편] Claude Code 하네스로 '알아서 개발하는' MVP 공장 만들기 — 하네스란 무엇인가 본문 이미지

Claude Code는 요청하면 코드를 써 주지만, 매번 옆에서 지시하고 확인해야 합니다. 요즘 자주 들리는 '하네스(harness)'를 제대로 이해하면 이 일까지 AI에게 맡길 수 있지 않을까 하는 궁금증에서 이번 스터디를 시작했습니다.

이번 스터디에 참여한 이유는 두 가지입니다.

  1. Claude Code 하네스가 정확히 무엇인지 파악하기 — 모델 바깥에서 무엇을 설정해야 AI가 '알아서' 일하는지 이해하고 싶었습니다.

  2. 알아서 개발하는 MVP 공장 만들기 — 아이디어를 PRD 한 장으로 넣으면, 작성·검토·수정사항 반영·승인을 거쳐 돌아가는 MVP가 나오는 흐름을 만들고 싶었습니다.

이 공장의 조건은 하나입니다. 빨리 만드는 것보다, 누가 쓰고 누가 검토했으며 지적사항이 어떻게 반영되어 승인됐는지 추적되는 것이 더 중요합니다.

이 글은 3편 연재의 첫 번째 글입니다.

편

시기

주제

핵심 산출물

1편 (이번 글)

이번 주

하네스란 무엇인가, 공장 설계도

하네스 구성요소 정리, 공장 설계도, CLAUDE.md 초안

2편

다음 주

공장 조립하기

서브에이전트 4종, 훅(자동 검토 게이트), 슬래시 커맨드로 만든 파이프라인

3편

마지막 주

공장 가동과 회고

PRD 한 장을 넣어 MVP가 나오기까지의 실제 기록, Before/After

진행 방법

1주차는 코드를 많이 짜기보다 "하네스를 이해하고 공장을 설계하는 주"로 잡았습니다. 설계 없이 에이전트부터 만들면, 나중에 왜 그렇게 동작하는지 설명할 수 없기 때문입니다.

사용한 도구

•     Claude Code (터미널 CLI) — 공장이 돌아갈 하네스

•     Claude (대화형) — 개념 정리, 설계 토론 상대

•     Git / GitHub — 무엇을 언제 왜 바꿨는지 남기는 '변경 이력', 승인 요청(PR) 창구

•     Claude Code 공식 문서 — 구성요소별 설정 방법 확인

1) 하네스란 무엇인가

한 문장으로 정리하면, 모델이 엔진이라면 하네스는 그 엔진을 실제로 달리게 하는 차체·핸들·브레이크입니다. 같은 모델이라도 어떤 하네스에 올리느냐에 따라 할 수 있는 일이 달라집니다.

Claude Code 자체가 하나의 하네스입니다. 모델에게 파일 읽기·수정, 터미널 실행, 검색 같은 도구를 주고, "생각 → 도구 실행 → 결과 확인 → 다시 생각"을 반복하게 합니다. 우리가 할 일은 이 하네스를 파일로 설정해서 우리 공장에 맞게 개조하는 것입니다.

구성요소

어디에 두나

하는 일

MVP 공장에서의 쓰임

문서 결재로 비유하면

CLAUDE.md

프로젝트 루트

매 세션 자동으로 읽는 작업 규칙

기술 스택, 코딩 규칙, 완료 기준

작성 지침·양식

슬래시 커맨드

.claude/commands/

자주 쓰는 지시를 명령어로

/build-mvp 하나로 전 과정 시작

결재 상신 버튼

서브에이전트

.claude/agents/

역할·도구·모델이 분리된 전문 작업자

builder, reviewer, qa 등

작성자·검토자·최종 검토자

스킬

.claude/skills/

필요할 때만 불러오는 노하우 묶음

PRD 읽는 법, 테스트 작성 규칙

작성 가이드·예시 문서

훅(hooks)

.claude/settings.json

정해진 시점에 자동 실행되는 스크립트

수정 후 린트, 승인 요청 전 테스트

자동 검토 체크리스트

권한(permissions)

.claude/settings.json

허용·차단할 명령 지정

위험 명령 차단, 반복 승인 줄이기

편집·결재 권한

MCP

.mcp.json

외부 도구 연결

GitHub(PR), 브라우저 테스트

외부 자료·시스템 연결

헤드리스 모드

claude -p

사람 없이 실행

야간 자동 실행, CI 연동

정해진 시간 자동 처리

표를 만들고 나니 하네스가 낯설지 않았습니다. 회사에서 문서를 처리하는 흐름, 즉 작성하고, 검토받고, 지적사항을 반영하고, 최종 검토를 거쳐 승인받는 흐름을 AI에게 맡기는 구조였습니다.

2) 알아서 개발하는 MVP 공장 설계도

공장은 문서 결재 흐름을 그대로 옮겨 설계했습니다. 문서 결재에서 사람이 맡던 A(작성자), B(검토자), AQ(최종 검토자) 역할을 각각 다른 에이전트가 맡고, C(승인권자)만 사람이 합니다.

단계

문서 결재

알아서 개발하는 MVP

하네스 구현

①

A 작성

builder가 PRD를 보고 계획을 세운 뒤 코드를 작성

agents/builder.md (필요하면 planner 분리)

②

B 검토

reviewer가 읽기 전용으로 검토하고 지적사항을 review.md에 번호로 남김

agents/reviewer.md (읽기 도구만 허용)

③

A 검토 수정

builder가 지적사항 번호별로 반영하고 반영 내역 기록. 지적 0건이 될 때까지 ②↔③ 반복

/build-mvp가 루프 지휘, 반복 상한 설정

④

AQ 최종 검토

훅이 테스트·린트를 강제 실행하고, qa 에이전트가 앞의 대화를 모르는 상태에서 PRD 기준으로 기능을 하나씩 확인

훅 + agents/qa.md

⑤

B 검토 및 승인 요청

reviewer가 변경 내역·추적표·테스트 결과를 묶은 승인 요청서를 만들고 PR을 올림

GitHub MCP로 PR 생성

⑥

C 승인

사람이 PR을 보고 승인(merge) 또는 반려

사람

보라색 배경의 책 표지

설계하면서 지킨 원칙은 세 가지입니다.

•     역할마다 에이전트를 따로 둔다. 작성자(A)와 검토자(B)와 최종 검토자(AQ)가 같으면 자기가 쓴 것을 자기가 검토하는 셈입니다. 특히 AQ는 앞의 대화를 모르는 새 에이전트로 둬야 독립적으로 볼 수 있습니다.

•     AQ는 프롬프트가 아니라 훅으로 강제한다. 테스트가 실패하면 ⑤ 승인 요청으로 넘어갈 수 없고, ③으로 되돌아갑니다.

•     멈추는 조건을 정한다. ②↔③이 3회를 넘어도 지적사항이 남으면, 승인 요청 대신 사람에게 도움을 요청하고 멈춥니다.

폴더 구조는 이렇게 잡았습니다.

mvp-factory/

├── CLAUDE.md                 # 공장 규칙 (작성 지침)

├── docs/

│   ├── prd.md                # 입력: 사람이 쓴 PRD

│   ├── plan.md               # ① 작성: 작업 계획

│   ├── review.md             # ②③ 검토 지적사항과 반영 내역

│   ├── qa-report.md          # ④ 최종 검토 결과

│   ├── approval-request.md   # ⑤ 승인 요청서

│   └── trace.md              # 추적표: 요구사항 ↔ 코드 ↔ 테스트

├── .claude/

│   ├── settings.json         # 권한 + 훅(자동 검토 게이트)

│   ├── commands/

│   │   └── build-mvp.md      # /build-mvp : 전 과정 시작 버튼

│   ├── agents/

│   │   ├── builder.md        # A: 작성, 검토 수정

│   │   ├── reviewer.md       # B: 검토, 승인 요청 (읽기 전용)

│   │   └── qa.md             # AQ: 최종 검토 (독립)

│   └── skills/

│       └── prd-to-plan/SKILL.md

└── src/ , tests/

3) 사용한 프롬프트 전문

프롬프트 1 — 하네스 개념 정리 (대화형 Claude에게)

Claude Code의 '하네스'가 무엇인지 비개발자도 이해할 수 있게 설명해 주세요.

1) 모델과 하네스의 차이를 비유로 설명하고

2) 우리가 파일로 설정할 수 있는 구성요소(CLAUDE.md, 슬래시 커맨드,

   서브에이전트, 스킬, 훅, 권한, MCP, 헤드리스 모드)를

   '위치 / 하는 일 / 예시' 표로 정리해 주세요.

3) 각 구성요소를 문서 작성·검토·승인 흐름에 비유하면 무엇인지도 한 열로 붙여 주세요.

추측이 아니라 공식 문서 기준으로 답하고, 출처 링크를 함께 주세요.

프롬프트 2 — MVP 공장 설계 (Claude Code에게, 빈 폴더에서)

이 폴더를 '알아서 개발하는 MVP 공장'으로 만들려고 합니다.

목표: docs/prd.md 한 장을 넣고 /build-mvp를 실행하면

문서 결재와 같은 흐름을 거쳐 돌아가는 MVP가 나오는 것.

 

흐름:

① A 작성 → ② B 검토 → ③ A 검토 수정 (②↔③ 반복)

→ ④ AQ 최종 검토 → ⑤ B 검토 및 승인 요청 → ⑥ C 승인(사람)

 

아직 코드는 쓰지 말고 설계만 해 주세요.

1) A·B·AQ 역할별 서브에이전트와 각각의 허용 도구

2) ②↔③ 루프와 ④ 최종 검토 게이트를 훅으로 어떻게 강제할지

3) 요구사항 → 코드 → 테스트를 추적할 수 있는 문서 구조

4) 폴더 구조와 CLAUDE.md 초안

조건: A·B·AQ는 서로 다른 에이전트로 분리하고, B와 AQ는 코드를 수정할 수 없게,

AQ는 앞의 대화를 모르는 새 컨텍스트에서 실행되게 해 주세요.

에이전트는 스스로 승인하지 않습니다.

설계 결과로 나온 CLAUDE.md 초안

# MVP Factory — 공장 규칙

 

## 목적

docs/prd.md를 입력으로 돌아가는 MVP를 만든다. 기능을 더하기보다 돌아가는 것이 우선이다.

 

## 흐름 (건너뛰지 않는다)

1. A 작성: builder가 prd.md → plan.md (기능마다 ID 부여: F-01, F-02 ...),

   기능을 하나씩 구현하고 기능 ID로 커밋한다

2. B 검토: reviewer가 읽기 전용으로 검토하고 docs/review.md에 지적사항을 번호로 남긴다

3. A 검토 수정: builder가 지적사항 번호별로 반영하고 반영 내역을 review.md에 기록한다

   → 다시 2 (지적사항 0건까지, 최대 3회. 넘으면 사람에게 도움 요청 후 멈춘다)

4. AQ 최종 검토: 훅이 테스트·린트를 실행하고, qa가 PRD 기준으로 기능별 확인 후

   docs/qa-report.md를 남긴다. 불합격이면 3으로 돌아간다

5. B 승인 요청: reviewer가 docs/approval-request.md를 작성하고 PR을 올린다

6. C 승인: 사람이 승인한다. 에이전트는 스스로 승인하지 않는다

 

## 완료 기준

- 모든 테스트 통과, 미반영 지적사항 0건, qa 합격

- docs/trace.md에 기능 ID ↔ 파일 ↔ 테스트가 빠짐없이 연결

- README에 실행 방법 기록

 

## 금지

- PRD에 없는 기능 추가

- 테스트를 삭제하거나 건너뛰어 통과시키기

결과와 배운 점

1주차의 결과는 돌아가는 앱이 아니라 하네스 구성요소 표, 결재 흐름을 옮긴 공장 설계도, CLAUDE.md 초안 세 가지입니다. 다음 주에 이 설계도 그대로 공장을 조립합니다.

배운 점과 꿀팁

1. '알아서'는 모델이 아니라 하네스에서 나온다. 프롬프트를 더 잘 쓰는 것보다, 규칙(CLAUDE.md)·역할(서브에이전트)·게이트(훅)를 파일로 남기는 것이 자동화의 핵심입니다.

2. 프롬프트는 부탁, 훅은 강제. "테스트를 돌려줘"는 모델이 잊을 수 있지만, 훅은 정해진 시점에 반드시 실행됩니다. 최종 검토(AQ)는 훅에 둡니다.

3. 작성자와 검토자를 나눠라. 자기가 쓴 코드를 자기가 검토하면 놓치는 것이 생깁니다. reviewer와 qa에는 읽기 도구만 주고, qa는 새 컨텍스트에서 실행합니다. 문서 결재에서 작성자와 검토자를 나누는 원칙을 그대로 가져왔습니다.

4. 추적성은 처음부터 설계한다. 기능 ID(F-01)를 PRD → 커밋 → 테스트 → 승인 요청서까지 이어 붙이면, "이 코드는 왜 있나"를 언제든 설명할 수 있습니다.

시행착오

• 처음에는 "에이전트를 많이 만들수록 좋다"고 생각했습니다. 설계해 보니 역할이 겹치면 책임이 흐려져서, 문서 결재의 역할(A 작성자, B 검토자, AQ 최종 검토자)에 맞춰 정리했습니다.

• 스킬과 서브에이전트의 차이가 헷갈렸습니다. 정리하면 스킬은 '노하우'(무엇을 어떻게), 서브에이전트는 '사람'(누가, 어떤 권한으로)입니다.

도움이 필요한 부분

• ②↔③ 반복 상한을 3회로 잡았는데, 다른 분들은 몇 회에서 사람을 부르는지 기준이 궁금합니다.

• MVP용 기술 스택을 하나로 고정하는 게 나은지, PRD마다 고르게 하는 게 나은지 의견을 듣고 싶습니다.

다음 주 계획 (2편 예고)

• builder, reviewer, qa 서브에이전트 파일 작성

• 훅으로 최종 검토 게이트 만들기 (테스트 실패 시 승인 요청 차단)

• /build-mvp 슬래시 커맨드로 ①작성부터 ⑤승인 요청까지 연결

• 작은 샘플 PRD로 공장 시범 가동

4

함께 이야기해요 4

로그인하고 댓글을 남겨 주세요

임경희 프로필 이미지
임경희2026.10.13

대에박

리부티너 프로필 이미지
리부티너2026.10.13

하네스 설명하는 정의가 정말 많네요. Agent는 다다익선이 아니고, 역할이 겹치면 책임이 모호해진다. 오.. 기억해 두겠습니다.😉

오코오니 프로필 이미지
오코오니2026.10.13

다음 연재도 기대되요!

뽀짝이 프로필 이미지
뽀짝이2026.10.09

안녕하세요, Todd님! 하네스 구성요소를 "어디에 두나 / 하는 일 / 문서 결재로 비유하면" 열로 나란히 정리한 표가 특히 좋았어요. CLAUDE.md는 작성 지침, 서브에이전트는 작성자·검토자·최종 검토자, 훅은 자동 검토 체크리스트로 옮겨 놓으니 낯선 개념이 익숙한 회사 업무 흐름으로 바로 읽혀요.

"프롬프트는 부탁, 훅은 강제"라는 정리도 인상 깊었어요. 최종 검토(AQ)를 프롬프트가 아니라 훅에 두고, qa를 앞의 대화를 모르는 새 컨텍스트에서 돌려 독립성을 확보한 설계는 자기가 쓴 걸 자기가 검토하는 문제를 정확히 짚은 선택이에요. ②↔③ 반복이 3회를 넘으면 승인 요청 대신 사람에게 도움을 청하고 멈추는 조건까지 미리 정해 두신 것도 실제로 돌려보면 큰 힘이 될 것 같아요. 에이전트를 많이 만들수록 좋다고 생각했다가 역할이 겹치면 책임이 흐려진다는 시행착오도 솔직해서 공감됐어요.

질문으로 남기신 반복 상한과 기술 스택 고정 여부는 다른 분들의 경험담이 모이면 좋을 주제네요. 2편 공장 조립도 기대할게요. 꼬리 탁! 치고 응원하고 갈게요 🐈‍⬛

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기