🤖 23. 하니스 운영 실전

harness-100은 얼핏 보면 “Claude Code용 만능 프롬프트 팩”처럼 보입니다. 그런데 실제로 뜯어보면 본질은 프롬프트 모음이 아니라 팀 운영 템플릿에 가깝습니다. .claude/CLAUDE.md, 역할별 에이전트 파일, 오케스트레이터 스킬, 도메인 스킬을 한 세트로 묶어 두었기 때문입니다.

그래서 이 레포를 잘 쓰는 방법도 단순하지 않습니다. 100개를 다 가져오는 사람이 이기는 게 아니라, 내 프로젝트에 필요한 역할만 줄여서 붙이는 사람이 이깁니다. Claude Code 공식 문서를 함께 놓고 보면 그 이유가 더 또렷해집니다.

하니스를 단순 프롬프트 꾸러미로 보면 금방 실망하게 된다. 더 정확한 비유는 새 직원 온보딩 문서 + 팀 운영 계약서에 가깝다. 즉 “어떤 기준으로 일하고, 무엇을 실패로 보고, 어디서 검증할지”를 미리 고정해 두는 장치다. 이 관점을 먼저 잡아야 harness-100 같은 큰 레포도 복붙보다 감량·적용·검증 순서로 읽히기 시작한다.

flowchart LR
A[레포 발견] --> B[하니스 1개 선택]
B --> C[역할 2~3개로 감량]
C --> D[skills 중심으로 먼저 적용]
D --> E[subagents 또는 단일 세션으로 검증]
E --> F[필요할 때만 agent teams 확장]

🧠 칠판 치트시트

• harness-100은 프롬프트 팩보다 팀 운영 설계도에 가깝다.
• 첫 도입은 100개 전체가 아니라 하니스 1개 + 역할 2~3개가 맞다.
• Claude Code 기본값은 아직 agent teams보다 skills + subagents가 더 안전하다.
• 복붙보다 먼저 해야 할 일은 감량, 검증, 역할 경계 정리다.

한 줄 결론

이 레포의 핵심 가치는 “100개가 있다”가 아닙니다. Claude Code를 한 명의 비서가 아니라 작은 팀처럼 설계하는 관점을 아주 구체적으로 보여준다는 점이 핵심입니다.

왜 이 레포가 눈에 띄는가

공개 README 기준으로 이 저장소는 한국어/영어 각각 100개씩, 총 200개 하니스를 제공합니다. 에이전트 정의는 978개, 스킬은 630개, 전체 마크다운 파일은 1,808개 규모입니다.

더 중요한 건 수량보다 구조입니다. 예를 들어 ko/01-youtube-production에는 content-strategist, scriptwriter, seo-optimizer, thumbnail-designer, production-reviewer 같은 역할 파일이 들어 있고, youtube-production, hook-writing, thumbnail-psychology 같은 스킬 폴더가 따로 나뉘어 있습니다. ko/16-fullstack-webapp도 비슷합니다. architect, frontend-dev, backend-dev, devops-engineer, qa-engineer 같은 역할과 fullstack-webapp, component-patterns, api-security-checklist 같은 스킬이 분리돼 있습니다.

이 구조는 Claude Code 공식 문서의 방향과도 맞닿아 있습니다. Anthropic은 Claude Code를 단순 채팅창이 아니라 코드베이스를 읽고, 파일을 수정하고, 명령을 실행하고, 개발 도구와 연결되는 에이전트형 코딩 도구로 설명합니다.

• 공식 개요: https://code.claude.com/docs/en/overview
• 원문 레포: https://github.com/revfactory/harness-100

즉, harness-100은 새로운 기능을 발명한 레포라기보다, Claude Code 공식 기능 위에 도메인별 운영 틀을 얹어 놓은 사례집으로 보는 편이 정확합니다.

이 레포를 볼 때 제일 먼저 바꿔야 하는 오해

많은 사람이 이런 레포를 보면 “좋아, .claude 폴더를 그대로 넣으면 멀티에이전트 팀이 바로 굴러가겠네”라고 생각합니다. 그런데 실무에서는 여기서부터 흔들립니다.

왜냐하면 Claude Code의 품질은 파일 개수보다 어떤 역할을 어떤 순서로 불러오느냐에 더 크게 좌우되기 때문입니다. 공식 문서도 비슷한 방향을 말합니다. Skills 문서에서는 스킬을 SKILL.md를 통해 Claude의 도구 상자에 추가되는 재사용 가능한 절차로 설명하고, 기존 커스텀 커맨드도 이제 skills에 합쳐졌다고 적어 둡니다.

• Skills 문서: https://code.claude.com/docs/en/skills

이 말은 곧, 하니스의 진짜 가치는 “파일이 많다”가 아니라 역할·절차·도메인 지식을 반복 가능한 단위로 쪼갰다는 데 있다는 뜻입니다.

실무에서 진짜 건질 포인트 4가지

1) 이 레포는 ‘프롬프트 모음집’이 아니라 ‘팀 설계도’다

프롬프트 모음집은 보통 “이 상황에서는 이 문장을 써라”에 가깝습니다. 반면 harness-100은 “누가 먼저 생각하고, 누가 실행하고, 누가 검수할지”를 나눠 둡니다. 이 차이가 큽니다.

예를 들어 01-youtube-production은 처음부터 제작팀 구조를 상정합니다. 기획, 스크립트, SEO, 썸네일, 리뷰가 따로 나뉘어 있습니다. 이 구조를 그대로 믿고 한 번에 다 돌리기보다, 먼저 “우리 팀은 지금 어디서 가장 흔들리는가”를 잡는 게 좋습니다.

실행 순서는 이렇게 잡는 편이 안전합니다.

1. 지금 가장 흔들리는 작업 1개만 고릅니다. 예: 영상 제목/스크립트 일관성.
2. 관련 역할 2개만 남깁니다. 예: content-strategist, scriptwriter.
3. 스킬도 1~2개만 둡니다. 예: youtube-production, hook-writing.
4. 결과를 3회 정도 반복 실행해 품질 편차가 줄어드는지 먼저 봅니다.

검증은 어렵지 않습니다. 같은 입력에서 제목 톤, 도입부 훅, 구성 흐름이 덜 흔들리면 제대로 줄인 것입니다.

2) Claude Code 공식 기준으로는 ‘skills 먼저, teams는 나중’이 더 안전하다

README는 Agent Team Mode를 강하게 내세우지만, Claude Code 공식 문서를 같이 보면 중요한 현실이 하나 있습니다. Agent teams는 아직 실험 기능이고 기본 비활성화 상태입니다.

• Agent teams 문서: https://code.claude.com/docs/en/agent-teams

반대로 subagents는 이미 공식적으로 설명이 잘 되어 있고, 각 에이전트가 독립된 컨텍스트에서 특정 작업을 맡는 구조가 분명합니다.

• Subagents 문서: https://code.claude.com/docs/en/sub-agents

여기서 실무 판단 기준이 나옵니다.

• 역할끼리 서로 토론하고 중간 결과를 주고받아야 하면 agent teams
• 결과만 들고 돌아오면 되면 subagents
• 아직 기준이 안 섰으면 skills + 단일 세션

이 레포를 처음 도입할 때 가장 안전한 경로는 보통 이렇습니다.

1. 하니스 1개를 고릅니다.
2. 그 안의 오케스트레이터 스킬 1개를 먼저 읽어 Claude의 기본 진행 루틴으로 삼습니다.
3. 에이전트 파일은 전부 활성화하지 말고, 탐색 역할 1개와 실행 역할 1개만 남깁니다.
4. 서로 직접 대화가 꼭 필요한 상황이 생길 때만 teams 쪽으로 확장합니다.

이 순서로 가면 “뭔가 대단한 구조를 붙였는데 더 느리고 더 비싸졌다”는 전형적인 실패를 많이 줄일 수 있습니다.

3) 복붙보다 감량이 먼저다

이 레포는 잘 만든 샘플이지만, 그대로 붙이면 내 프로젝트 문맥과 충돌할 가능성이 큽니다. 이유는 간단합니다. 좋은 하니스는 보통 문맥을 강하게 가정하기 때문입니다.

16-fullstack-webapp를 예로 들면 프론트, 백엔드, 데브옵스, QA가 이미 분리된 팀을 상정합니다. 그런데 실제 소규모 프로젝트는 한 명이 프론트와 백엔드를 같이 보고, QA는 최소 체크리스트만 필요한 경우가 많습니다. 이때 다섯 역할을 한 번에 넣으면 오히려 조율 비용이 늘어납니다.

현장형 미니 사례를 이렇게 상상하면 쉽습니다.

• Before: 한 세션에서 “로그인 기능 만들고, API 연결하고, 배포 준비하고, 테스트도 해줘”를 한 번에 시킴
• After: architect로 설계안 1회 확인 → frontend-dev와 backend-dev만 단계별 실행 → 마지막에 api-security-checklist로 점검
• 체감 변화: 초반 속도는 약간 느려도, 후반 되돌리기와 누락이 크게 줄어듦

검증 포인트도 명확합니다.

• 설계 변경 횟수가 줄었는가
• 같은 파일을 여러 역할이 다시 건드리는 충돌이 줄었는가
• 마지막 QA에서 새로 터지는 이슈가 줄었는가

작게 시작하면 하니스의 장점이 살아나고, 크게 한 번에 넣으면 장점보다 운영비가 먼저 튀어나옵니다.

4) 이 레포의 진짜 활용법은 ‘복사’보다 ‘학습’에 가깝다

초보자가 이 레포를 보면 “와, 이제 템플릿만 가져오면 끝이네”라고 느끼기 쉽습니다. 그런데 오래 쓰는 사람들은 오히려 반대로 갑니다. 그대로 쓰기보다, 왜 이렇게 역할을 나눴는지 배우는 쪽으로 이동합니다.

예를 들어 01-youtube-production에서 배울 수 있는 건 “콘텐츠 제작에는 scriptwriter가 필요하다” 수준이 아닙니다. 더 중요한 건 아래 세 가지입니다.

• 기획과 작성, 유통 최적화, 품질 검수가 왜 분리되어야 하는가
• 어떤 일은 도메인 스킬로 고정하고, 어떤 일은 역할 판단에 맡겨야 하는가
• 어디서부터 병렬화하면 이득이고, 어디서부터 조율 비용이 폭증하는가

이런 관점으로 보면 harness-100은 템플릿 저장소이면서 동시에 멀티에이전트 운영 교과서처럼 쓸 수 있습니다.

20분 도입 루틴

지금 바로 Claude Code 프로젝트에 시험해 보고 싶다면 아래 순서가 가장 안전합니다.

1단계. 하니스 1개만 고른다

내 작업과 가장 가까운 것 하나만 고릅니다.

• 콘텐츠면 01-youtube-production
• 웹앱이면 16-fullstack-webapp
• 운영/이벤트면 89-event-organizer

2단계. .claude 전체를 넣기 전에 역할을 절반 이하로 줄인다

처음엔 아래 기준으로 자릅니다.

• 오케스트레이터 1개
• 핵심 실행 역할 1~2개
• 검수 역할 1개 이하
• 도메인 스킬 1~2개

3단계. Claude Code에서 작은 작업 1개만 돌린다

처음부터 큰 기능을 맡기지 말고, 작은 산출물로 시작합니다.

• 블로그면 제목/개요/도입부까지
• 개발이면 로그인 화면 한 조각 또는 API 한 개
• 운영이면 체크리스트 초안 1개

4단계. 성공 기준을 먼저 적는다

아래 3개를 사전에 적어 두면 평가가 쉬워집니다.

• 결과가 덜 흔들렸는가
• 되돌리기 횟수가 줄었는가
• 내가 다음 날 다시 같은 방식으로 돌릴 수 있는가

5단계. 두 번째 실행 전에 더 줄인다

첫 실행 뒤에는 보통 추가보다 삭제가 먼저입니다. 실제로는 역할 하나를 빼는 편이 품질이 좋아지는 경우가 많습니다.

어떤 사람에게 특히 잘 맞나

이 레포는 다음 같은 사람에게 특히 잘 맞습니다.

• Claude Code를 이미 쓰고 있는데 작업 품질 편차가 큰 사람
• 역할 분리형 운영을 배우고 싶은 사람
• 블로그, 제품 개발, 리서치, 문서화처럼 반복 업무를 팀 구조로 바꾸고 싶은 사람

반대로 지금 Claude Code도 아직 익숙하지 않은 상태라면, 100개 하니스부터 들어가기보다 공식 개요와 skills 문서를 먼저 보는 편이 낫습니다.

• https://code.claude.com/docs/en/overview
• https://code.claude.com/docs/en/skills

wrap-up

harness-100의 진짜 가치는 “하니스가 100개나 있다”가 아닙니다. Claude Code를 어떻게 팀처럼 굴릴지에 대한 사고방식이 파일 구조로 정리돼 있다는 점이 핵심입니다.

그래서 이 레포를 잘 쓰는 사람은 보통 이렇게 움직입니다.

• 많이 복사하지 않고,
• 먼저 줄이고,
• 작은 작업으로 검증하고,
• 필요할 때만 역할과 병렬화를 늘립니다.

결국 중요한 건 하니스의 숫자가 아니라, 내 일에 맞는 팀 경계를 얼마나 잘 설계하느냐입니다.

다음 읽기

• 33. Claude Code Agent Teams vs Subagent, 언제 뭘 써야 하나
• 49. Claude Code Best Practice 운영 가이드
• 59. 에이전트부터 만들지 말고 스킬부터
• 72. Claude Skills V2 업데이트

참고 메타

• 원문 레포: https://github.com/revfactory/harness-100
• 대표 예시 1: https://github.com/revfactory/harness-100/tree/main/ko/01-youtube-production
• 대표 예시 2: https://github.com/revfactory/harness-100/tree/main/ko/16-fullstack-webapp
• 공식 문서(overview): https://code.claude.com/docs/en/overview
• 공식 문서(skills): https://code.claude.com/docs/en/skills
• 공식 문서(sub-agents): https://code.claude.com/docs/en/sub-agents
• 공식 문서(agent-teams): https://code.claude.com/docs/en/agent-teams

이 문서는 생성형 AI를 활용해 초안을 구성했고, 공개 GitHub 저장소와 Claude Code 공식 문서를 교차 확인해 실무형으로 재정리했습니다.