three-man-team

AI 코딩 도구들은 강력하지만 규율이 부족합니다. 이들은 단 하나의 함수만 필요할 때 전체 코드베이스를 읽어버립니다. 아무도 요청하지 않은 기능을 추가하기도 합니다. 작업 도중에 방향을 잃기도 합니다. 그리고 불필요한 작업을 수행하며 매 세션마다 토큰을 낭비합니다.

해결책은 더 나은 프롬프트(Prompt)가 아닙니다. 그것은 프로세스(Process)입니다.

Three Man Team은 명확한 업무 분담, 분명한 인수인계, 그리고 가장 비용이 많이 드는 실패 모드들을 방지하는 규칙을 가진 세 명의 에이전트(Agent)를 제공합니다. Architect는 계획하고 배포합니다. Builder는 브리프(Brief)에 명시된 내용을 정확하게 구축합니다. Reviewer는 올바르지 않은 작업은 통과시키지 않습니다.

DeepMind의 멀티 에이전트 (Multi-agent) 연구에 따르면, 구조화된 산출물 인수인계(Artifact handoffs)를 수행하는 3~5명 규모의 팀이 단일 에이전트나 더 큰 규모의 그룹보다 뛰어난 성능을 보입니다. '3'이라는 숫자는 임의적인 것이 아닙니다. 이는 의미 있는 검토(Review)를 위한 최소 단위이자, 조정 오버헤드(Coordination overhead)가 이득을 갉아먹기 전의 최대 단위입니다.

이 역할들은 실제 소프트웨어가 출시되는 방식과 매칭됩니다:

• 전체 시스템을 이해하고 배포를 책임지는 사람
• 빠르고 깔끔하게 구축하는 사람
• Builder가 놓친 것을 잡아내는 사람

팀 운영 방식: Three Man Team은 하나의 Claude Code 세션을 사용합니다. Arch가 당신의 메인 에이전트입니다. 작업이 구축될 준비가 되면, Arch는 Claude Code의 에이전트 도구(Agent tool)를 통해 Bob을 서브 에이전트(Subagent)로 실행합니다. Bob의 작업이 끝나면, Arch는 동일한 방식으로 Richard를 실행합니다. 당신은 세 개의 창을 열 필요가 없습니다. 모든 것이 단일 세션 내부에서 실행됩니다.

설치 유형을 선택하세요:

하나의 프로젝트, 하나의 설치. 프로젝트 폴더로 직접 클론(Clone)하세요.

1단계 — 프로젝트 폴더로 이동하여 클론하기

git clone https://github.com/russelleNVy/three-man-team.git .claude/skills/three-man-team

2단계 — 설정을 실행하고 지침을 따르기

cd .claude/skills/three-man-team && ./setup

여기서부터는 설정(Setup) 단계가 진행됩니다. 시작하기 위해 실행해야 할 정확한 명령어와 Claude에 붙여넣을 프롬프트를 알려줄 것입니다. 출력되는 내용을 따르세요.

한 번 설치하면 모든 프로젝트에서 사용 가능합니다.

1단계 — 글로벌 Claude skills 폴더로 클론하기

git clone https://github.com/russelleNVy/three-man-team.git ~/.claude/skills/three-man-team
cd ~/.claude/skills/three-man-team && ./setup

이것이 일회성 설치 과정입니다. Setup (설정) 과정에서 모든 것이 제대로 배치되었는지 확인합니다.

Three Man Team을 사용하려는 각 프로젝트마다:

2단계 — 에이전트 파일을 프로젝트로 복사한 후, Claude 실행하기

cp -r ~/.claude/skills/three-man-team/templates/project-folder/. /path/to/your/project/
cd /path/to/your/project

Claude Code를 열고 다음을 붙여넣으세요:

You are the Architect on this project. Please read new-setup.md.

Architect (설계자)가 나머지 작업 — 프로젝트 컨텍스트 파일, 팀 이름, 그리고 첫 번째 세션 프롬프트(session prompt)를 처리할 것입니다.

모든 작업 단위는 동일한 경로를 따릅니다. Architect가 계획을 세우고 브리프(brief)를 작성합니다. Builder (구축자)가 이를 읽고, 계획을 제시하며, 구축한 뒤 Reviewer (검토자)에게 전달합니다. Reviewer는 이를 승인하거나 다시 돌려보냅니다. Architect는 Project Owner (프로젝트 소유자)의 승인을 받아 배포(deploy)합니다. 어떤 단계도 건너뛰지 않습니다.

문제 해결부터 배포까지의 전체 예시는 다음을 참조하세요 → examples/sprint-walkthrough.md

세 명의 에이전트. 세 가지의 뚜렷한 역할. 함께 작동하도록 설계되었습니다.

Architect, Builder, Reviewer가 기본값입니다. 이들의 이름을 무엇으로든 변경할 수 있으며, Arch는 Setup (설정) 과정에서 이를 처리합니다.

모든 세션은 CLAUDE.md에 내장된 다섯 가지 규칙과 함께 시작됩니다:

Is this in a skill or memory? → Trust it. Skip the file read.
Is this speculative? → Kill the tool call.
Can calls run in parallel? → Parallelize them.
...

token-optimizer (토큰 최적화) 스킬은 모든 설치 시 함께 제공되며 CLAUDE.md를 통해 자동으로 로드됩니다 — 수동 설정이 필요하지 않습니다.

이러한 규칙 외에 bash 출력 압축에 대해서는 RTK를 참조하세요 —
Claude의 컨텍스트 (context)에 도달하기 전에 find, ls, grep 출력을 압축하는 별도의 도구입니다.
필수 사항은 아니지만, Claude Code CLI를 헤비하게 사용하는 사용자에게 권장됩니다. RTK (bash 레이어)와 token-optimizer (행동 레이어)의 조합은 실제 절감 효과를 복리로 만들어냅니다.

전체적인 원칙에 대해서는 docs/token-optimization.md를 참조하세요.

Arch는 매 세션 시작 시 GitHub releases API를 확인합니다. 만약 더 최신 버전이 사용 가능하다면, 다른 작업을 수행하기 전에 사용자에게 이를 알려줍니다. 변경 사항은 releases를 확인하세요.

templates/project-folder/

—여기서 시작하세요. 이름이 지정된 페르소나(Arch, Bob, Richard)들이 완전히 작성되어 즉시 사용할 수 있는 상태로 준비되어 있습니다. 'Who You Are' 섹션을 커스텀하고, 팀에 맞게 이름을 변경하여 사용하세요.

templates/generic/

— [CUSTOMIZE] 플레이스홀더가 포함된 백지 상태의 템플릿입니다. 처음부터 자신만의 페르소나를 구축하거나, 모든 프로젝트에 전역적으로 설치하고 싶을 때 사용하세요.

Arch는 설정 과정에서 이름 변경을 처리합니다. 새로운 이름만 알려주면 됩니다.

MIT 라이선스. 영구적으로 무료입니다.

Russell Aaron — 소프트웨어를 올바른 방식으로 구축하고 지원해 온 20년 이상의 경력을 보유하고 있습니다. 그는 실제 SaaS 플랫폼을 출시하는 프로덕션 환경에서 이 팀을 구축했습니다. 이 팀은 공개되기 전에 이미 사용되었고, 미세 조정(fine-tuned)되었으며, AI 모델과 도구가 진화함에 따라 시간이 지날수록 계속해서 개선될 것이기에 효과적입니다.