코드를 한 줄도 몰라도 따라 할 수 있게 만든 안내서입니다. 원본: https://github.com/tobyilee/team-bigfive

0. 한 문장 요약

여러 AI가 "한 팀"처럼 역할을 나눠 협업하게 만들어, 같은 AI로도 더 좋은 결과물을 뽑는 설정 묶음입니다.

평범한 사람을 여러 명 모아도 팀워크가 좋으면 결과가 좋아진다 — 이 팀 과학(Team Science)의 발견을 AI 에이전트에게 그대로 옮긴 것입니다. 더 똑똑한 AI를 쓰는 게 아니라, AI들끼리 더 잘 협력하게 만드는 것이 핵심입니다.

1. 먼저 알아야 할 개념 3가지

비개발자가 가장 많이 헷갈리는 부분부터 짚고 갑니다.

(1) 이것은 "프로그램"이 아니라 "설정 묶음"입니다

더블클릭하면 실행되는 앱이 아닙니다. Claude Code라는 도구 위에 얹어서 쓰는 규칙·역할 파일들의 모음입니다. 비유하자면, 요리사(AI)에게 주는 "레시피 + 주방 업무 분장표"라고 보면 됩니다.

(2) "Claude Code"가 있어야 작동합니다

Claude Code는 Anthropic이 만든, 터미널(검은 명령어 창)에서 Claude에게 일을 시키는 도구입니다. 빅파이브 하네스는 이 Claude Code의 동작 방식을 "팀 모드"로 바꿔주는 부가 설정입니다.

(3) "하네스(Harness)"라는 단어의 뜻

하네스는 원래 "말에 씌우는 마구(고삐·안장 묶음)"입니다. 여기서는 AI가 제멋대로 움직이지 않고 정해진 협업 절차를 따르도록 잡아주는 틀이라는 의미로 씁니다.

2. 왜 쓰는가 — 무엇이 좋아지나

AI 하나에게 큰 일을 한 번에 시키면 이런 문제가 생깁니다.

  • 앞에서 정한 내용을 뒤에서 잊어버린다.
  • 서로 맞물려야 하는 두 결과물(예: 앱의 화면과 뒷단)이 서로 안 맞는다.
  • 혼자 작업하다 보니 자기 실수를 스스로 못 잡는다.

빅파이브 하네스는 이걸 사람 팀이 일하는 방식으로 해결합니다.

사람 팀에서 이 하네스에서
팀장이 목표를 정하고 일을 나눔 team-lead(팀 리더 AI)
팀원들이 각자 맡은 일을 함 contributor(작업자 AI, 여러 명)
한 명이 동료들 작업을 교차 점검 performance-monitor(검수 AI)
화이트보드에 공동 목표를 적어둠 SMM.md(공유 메모 파일)
지시를 받으면 "OK, ~~하라는 거죠?" 복창 메시지 확인·재진술 절차

핵심 효과: 결과물끼리 서로 맞물려야 하는 복잡한 일일수록 효과가 큽니다.

3. 언제 쓰고, 언제 안 쓰나

가장 중요한 판단 기준입니다. 무조건 쓴다고 좋은 게 아닙니다.

쓰면 좋은 경우 (서로 맞물리는 일)

  • "이 API 설계하고 화면 연동까지 한 번에 해줘"
  • "이 주제 여러 자료 모아서 하나로 종합·검증해줘"
  • "소설 세계관이랑 줄거리를 앞뒤 안 맞게 하지 말고 같이 짜줘"

안 쓰는 게 나은 경우 (단순하거나 따로 노는 일)

  • "이 단어 영어로 뭐야?" 같은 단순 질문
  • 한 번에 끝나는 짧은 작업
  • 서로 영향 없는 독립 작업 여러 개 (이건 그냥 따로 시키는 게 빠름)

비유: 김밥 한 줄 마는 데 5명이 달라붙으면 오히려 느려집니다. 코스 요리처럼 여러 단계가 맞물릴 때 팀이 빛납니다.

4. 설치하기 (Getting Started)

비개발자 기준으로 가장 막히는 구간이라, 한 단계씩 풀어 씁니다. 순서: ① Claude Code 준비 → ② 하네스 파일 받기 → ③ 내 작업 폴더에 넣기 → ④ 실행 확인

단계 ① Claude Code 준비

빅파이브 하네스는 Claude Code 위에서 돕니다. 아직 없다면 Claude Code를 먼저 설치해야 합니다.

  • Claude Code는 터미널에서 쓰는 도구이며, Anthropic 계정(Claude 구독)이 필요합니다.
  • 설치 방법은 Anthropic 공식 문서를 따르는 것이 가장 정확합니다. ("Claude Code 설치"로 검색)
  • 설치가 끝나면, 작업할 폴더에서 claude 라고 입력했을 때 Claude Code가 켜집니다.

터미널이 처음이라면: Mac은 "터미널", Windows는 "PowerShell" 또는 "명령 프롬프트"가 그 검은 창입니다.

단계 ② 하네스 파일 받기

GitHub 페이지(https://github.com/tobyilee/team-bigfive)에서 파일을 가져옵니다. 두 가지 방법 중 편한 쪽을 고르세요.

방법 A — 버튼으로 받기 (제일 쉬움, 추천)

  1. 위 GitHub 주소로 들어갑니다.
  2. 초록색 Code 버튼을 누릅니다.
  3. Download ZIP 을 누릅니다.
  4. 받은 압축 파일을 풉니다.

방법 B — 명령어로 받기 터미널에 아래를 그대로 붙여넣습니다.

git clone https://github.com/tobyilee/team-bigfive.git

단계 ③ 내 작업 폴더에 넣기

이게 핵심입니다. 하네스의 뇌에 해당하는 폴더는 .claude와CLAUDE.md 파일입니다.

  1. 받은 파일 안에서 .claude라는 폴더와CLAUDE.md 파일을 찾습니다.
    • (.으로 시작하는 폴더는 숨김 처리되어 안 보일 수 있습니다. 파일 탐색기에서 "숨김 파일 보기"를 켜세요.)
  2. 이 두 가지를, 당신이 실제로 작업할 프로젝트 폴더에 통째로 복사해 넣습니다.

복사 후 내 작업 폴더 모습:

나의-프로젝트-폴더/
├── .claude/          ← 하네스의 역할·절차 정의 (복사해 넣음)
├── CLAUDE.md         ← 하네스 안내 파일 (복사해 넣음)
└── (내 작업 파일들…)

단계 ④ 실행 확인

  1. 그 폴더에서 터미널을 열고 claude 를 입력해 Claude Code를 켭니다.
  2. 아래 4장 "사용 예"의 트리거 문장을 입력해 봅니다.
  3. AI가 혼자 답하지 않고 "팀을 구성한다 / 역할을 나눈다"는 식으로 움직이면 정상 작동입니다.

요점만 다시: 설치 = .claude 폴더와 CLAUDE.md를 내 작업 폴더에 넣는 것. 그게 전부입니다.

5. 사용하는 법 — "트리거 문장"이 전부

설치를 마쳤다면, 복잡한 명령어는 필요 없습니다. 평소처럼 한국어로 부탁하되, 아래 "마법의 단어"를 한 개만 넣으면 팀 모드가 켜집니다.

트리거 단어 (이 중 하나만 들어가면 됨)

  • 팀으로
  • 에이전트 팀
  • 팀 빅파이브
  • 고성과 팀
  • 여러 에이전트로
  • 협업으로 처리

문장 만드는 공식

[하고 싶은 일]+[트리거 단어]+해줘

이게 끝입니다.

6. 실제 사용 예시 4가지

비개발자도 그대로 따라 칠 수 있는 예시입니다.

예시 1 — 웹사이트 만들기 (개발 작업)

회사 소개 페이지랑 문의 폼을 만들고 둘이 잘 연결되게 팀으로 해줘

한 AI는 화면을, 다른 AI는 폼 동작을, 검수 AI가 "둘이 잘 맞물리는지"를 점검합니다.

예시 2 — 자료 조사·보고서 (비개발 작업)

2025년 전기차 시장 트렌드를 여러 자료로 조사하고 하나로 종합해서 에이전트 팀으로 정리해줘

여러 작업자 AI가 나눠서 조사 → 검수 AI가 자료 간 모순을 잡음 → 팀장 AI가 하나의 보고서로 통합.

예시 3 — 글쓰기·기획 (창작 작업)

판타지 소설의 세계관 설정과 1~3화 줄거리를 앞뒤 안 맞는 부분 없이 팀 빅파이브로 짜줘

세계관 담당과 줄거리 담당이 "공유 메모(SMM)"를 같이 보며 충돌을 막습니다.

예시 4 — 분석 + 검증 (실무 작업)

이 엑셀 매출 데이터를 분석하고, 분석이 맞는지 교차 검증까지 고성과 팀으로 처리해줘

분석 담당과 검증 담당이 분리되어, 혼자 작업할 때 놓치는 오류를 잡아냅니다.

7. 작동하는 동안 무슨 일이 벌어지나 (안심용)

화면에 어려운 말이 지나가도 당황하지 않게, 흐름을 미리 알려드립니다.

  1. 준비 — 팀장 AI가 목표와 "완료 기준"을 공유 메모(SMM.md)에 적습니다.
  2. 팀 구성 — 작업자 AI 여러 명 + 검수 AI 1명을 만듭니다.
  3. 협업 실행 — 작업자들이 공유 메모를 보며 일하고, 서로 결과를 넘길 때 "이거 이렇게 이해한 거 맞죠?" 하고 확인합니다.
  4. 검수 — 검수 AI가 결과물들이 서로 잘 맞물리는지 교차 점검합니다.
  5. 종합 — 팀장 AI가 모든 결과를 하나로 합쳐 최종본을 만듭니다.

결과물은 보통 _workspace/final/ 라는 폴더에 정리됩니다.

8. 자주 막히는 부분 (FAQ)

Q. 그냥 Claude 앱(웹/모바일)에서도 되나요?아니요. 이 하네스는Claude Code(터미널 도구)전용입니다. 웹·모바일 Claude 앱에서는 동작하지 않습니다.Q. .claude 폴더가 안 보여요..으로 시작하는 폴더는 기본적으로 숨겨져 있습니다. 파일 탐색기 설정에서 "숨김 항목 표시"를 켜세요. (Mac 파인더: Cmd + Shift + .)Q. 트리거 단어를 넣었는데 그냥 평범하게 답해요.세 가지를 확인하세요. ① .claude와 CLAUDE.md가현재 작업 폴더 안에 있는지, ② 그 폴더에서 Claude Code를 켰는지, ③ 트리거 단어의 철자가 정확한지.

Q. 매번 팀으로 시키면 더 좋은 거 아닌가요?아닙니다. 단순한 일에 팀을 쓰면 오히려 느리고 비효율적입니다. "서로 맞물리는 복잡한 일"에만 쓰세요. (3장 참고)Q. 결과물이 마음에 안 들면? 그냥 이어서 한국어로 수정 요청하면 됩니다. 하네스는 매 작업 후 피드백을 반영해 개선되도록 설계돼 있습니다.

9. 한눈에 보는 치트시트

[설치]
1) Claude Code 설치
2) GitHub에서 ZIP 다운로드 (Code → Download ZIP)
3) .claude 폴더 + CLAUDE.md 를 내 작업 폴더에 복사
4) 그 폴더에서 'claude' 실행

[사용]
"(하고 싶은 일) + (트리거 단어) + 해줘"

[트리거 단어]
팀으로 / 에이전트 팀 / 팀 빅파이브 / 고성과 팀 / 여러 에이전트로 / 협업으로 처리

[쓸 때] 결과물이 서로 맞물리는 복잡한 일
[안 쓸 때] 단순 질문, 짧은 작업, 따로 노는 일

이론적 배경 (더 알고 싶다면)

이 하네스는 팀 과학의 고전 논문 Salas, Sims & Burke (2005), "Is there a 'Big Five' in Teamwork?" 에 근거합니다. 좋은 팀 성과는 5가지 행동(팀 리더십, 상호 점검, 백업, 적응성, 팀 지향성)과 이를 떠받치는 3가지 토대(공유 정신 모델, 폐쇄 루프 소통, 상호 신뢰)에서 나온다는 것이 골자입니다. 자세한 해설은 원본 저장소의 docs/TEAM-SCIENCE.md에 있습니다.