TheBotCompany 입문: 사람의 개입 0에 가까운 AI 팀 개발 새로운 패러다임

30 분 안에 시작｜3인 역할의 자율 협업｜다중 Provider 백업｜요구사항부터 PR까지 전 과정 자동화

---

프로젝트 소개

TheBotCompany 는 “정말로 맡겨버릴 수 있는” AI 개발 팀 플랫폼입니다. 핵심 아이디어는 아주 간단합니다. 이제는 당신 혼자 AI와 대화하며 코드를 쓰는 방식이 아닙니다. 여러 AI Agent 로 구성된 팀을 꾸립니다. 누군가는 기획을 맡고, 누군가는 코드를 작성하며, 누군가는 검증을 담당합니다. 그들은 스스로 논의하고, 스스로 작업을 배정하며, 스스로 진행 상황을 관리합니다. 당신이 해야 할 일은, 에이전트들이 정말로 사람의 판단이 필요한 문제에 부딪혔을 때만 개입하는 것입니다.

팀에는 세 가지 고정 관리 역할이 있습니다. Athena 는 전략 기획을 맡아 마일스톤과 주기 예산을 정의하고, Ares 는 팀을 이끌며 실행을 담당해 마일스톤을 구체적인 작업으로 쪼개 작업자 Agent들에게 배분합니다. Apollo 는 인수(검수)를 담당해 Ares의 산출물을 높은 기준으로 심사하며, 기준에 맞지 않으면 다시 반려합니다. 이 전체 루프는 당신이 계속 지켜볼 필요가 없고, Dashboard 가 각 Agent가 무엇을 하고 있는지, 얼마나 비용을 썼는지, 어떤 문제가 발생했는지 실시간으로 보여줍니다.

---

목표 독자

이 글은 아래 개발자들을 위한 것입니다.

• 일정 수준의 개발 경험이 있고, 반복적인 코딩 작업을 AI Agent 팀에 맡기고 본인은 의사결정과 아키텍처에 집중하고 싶은 분
• Multi-Agent 협업, 자율 조직 팀 같은 개념에 관심이 있고 실제 사례를 찾는 분
• 이미 단일 Agent로 개발을 보조하고 있지만, 여러 방향을 동시에 처리하기 위해 다중 Agent로 확장하고 싶은 분

만약 당신이 원하는 게 “세팅만 하면 완전히 편히 누워도 되는” 도구라면, 먼저 기대치를 낮춰야 합니다. TheBotCompany는 사람의 개입을 크게 줄여주지만, 완전히 당신이 필요 없게 만들지는 않습니다.

---

핵심 의존성과 환경

---

전체 프로젝트 구조 트리

설치 후 실행하면 ~/.thebotcompany/ 디렉터리 아래에 아래와 같은 구조가 생성됩니다.

~/.thebotcompany/
├── keys.json              # 암호화 저장된 API Keys
├── db.sqlite              # Issue tracker 데이터베이스
├── config.yaml            # 전역 설정
└── logs/                  # 실행 로그

당신의 프로젝트 디렉터리/
├── workers/               # 작업자 Agent 기술 정의
│   ├── leo.md             # Frontmatter: reports_to, role, model
│   └── maya.md
├── workspace/             # 각 Agent의 작업 공간
│   ├── athena/note.md
│   ├── ares/note.md
│   └── leo/note.md
└── .tbc/                  # 프로젝트 단위 설정(프로젝트 생성 시 생성)

---

단계별 설치 방법

1단계: TheBotCompany 설치

npm install -g thebotcompany

설치 확인:

tbc --version

2단계: 서비스 시작

tbc start

첫 실행에서는 다음을 순서대로 설정하라고 요청합니다.

1. Dashboard 접근 비밀번호 — 쓰기 작업을 보호하기 위해(일시정지, 재개, 설정 수정)
2. 포트 번호 — 기본값 3100 이며, 그대로 두려면 엔터로 확인

? Set a password for dashboard write access: ********
? Port to run the dashboard (default 3100):

시작이 성공하면 Dashboard는 http://localhost:3100 에서 접속할 수 있습니다. 기본은 읽기 전용 모드이며, 로그인 후에만 조작 가능합니다.

3단계: API Key 설정

Dashboard(http://localhost:3100)를 열고, 오른쪽 상단의 Settings 를 클릭한 뒤 Keys 패널에서 API Key를 추가하세요. 환경변수로도 첫 실행 시 자동 감지가 가능합니다.

# .bashrc 또는 .zshrc에 추가:
export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...

4단계: Dashboard로 프로젝트 생성

1. http://localhost:3100 을 엽니다.
2. New Project 를 클릭하고 다음을 입력합니다.
   • Repository URL — 당신의 GitHub Repo 주소( gh에 권한이 있어야 함 )
   • Provider — 어떤 LLM Provider를 사용할지 선택
   • Model Tier — 각 레이어에서 사용할 모델(high/mid/low)
3. Create 를 클릭하면 제어권이 Athena에게 넘어가 작업을 시작합니다.

---

3인 역할 협업 아키텍처 상세

이것이 TheBotCompany의 가장 핵심적인 설계입니다. 이것을 이해하면 전체 시스템이 어떻게 돌아가는지 알 수 있습니다.

세 가지 고정 관리 역할

전체 Cycle 루프

PLANNING 단계(Athena)
  → Athena + 그녀의 작업자 Agent들이 실행
  → 리서치, 평가, 브레인스토밍
  → 마일스톤 정의 → IMPLEMENTATION으로 진입

IMPLEMENTATION 단계(Ares)
  → Ares + 그의 작업자 Agent들이 실행(최대 N개의 Cycle)
  → Ares가 완료 선언 → VERIFICATION으로 진입
  → 주기 예산 초과 → PLANNING으로 되돌려 재평가

VERIFICATION 단계(Apollo)
  → Apollo + 그의 작업자 Agent들이 실행
  → Apollo가 인수 통과 → 다음 PLANNING으로 진입
  → Apollo가 반려 → IMPLEMENTATION으로 돌아가 수정

작업자 Agent는 어떻게 동작하나

Manager(Ares / Athena / Apollo)는 {project_dir}/workers/ 디렉터리에 .md 파일을 만들어 작업자 Agent를 “채용”합니다. 각 파일은 고정된 YAML frontmatter를 포함합니다.

---
reports_to: ares          # 누구에게 보고하는지
role: Frontend Engineer   # 책임 설명
model: mid                # 어떤 모델을 사용하는지
---

# Frontend Engineer

당신은 프론트엔드 엔지니어입니다. UI 컴포넌트와 상호작용 로직을 구현하는 일을 맡습니다.

Manager가 작업자에게 작업을 배정할 때는 “작업 1개당 주기 1개” 만 배정합니다. 한 번에 다섯 가지 작업을 몰아 넣는 것은 허용되지 않습니다. 작업자가 완료하면, Manager는 작업 공간의 note.md를 읽어 컨텍스트를 파악한 뒤 다음 단계를 결정합니다.

Agent 간 통신 방식

Agent들은 서로 직접 대화하지 않고, 내장된 Issue Tracker를 통해 협의합니다.

• Ares가 Athena의 의견이 필요할 때 → Issue Tracker에 Issue를 만들고, Athena로 지정
• Worker가 문제를 만나면 → Issue를 생성하면, Manager가 보고 처리합니다.
• 사람의 개입이 필요할 때 → GitHub Issue를 생성하고 제목을 HUMAN: 으로 시작한 뒤, 로그인하여 GitHub에서 처리

---

전체 개발 프로세스 데모

Step 1: Dashboard로 프로젝트 생성

Dashboard를 열고 New Project 를 클릭합니다.

Repository: https://github.com/your-username/your-repo
Provider: Anthropic
Model: claude-sonnet-4

프로젝트가 생성되면 Dashboard에 해당 프로젝트 카드가 나타나고, 상태가 PLANNING 으로 표시되며 Athena가 작업을 시작합니다.

Step 2: Athena의 기획 과정을 관찰

Dashboard의 Agent Reports 패널에서 Athena의 출력을 확인할 수 있습니다. 그녀가 하는 일은 다음과 같습니다.

• 프로젝트 README와 기존 코드를 읽어 현재 상태 파악
• 관련 기술 제안과 베스트 프랙티스를 검색
• 요구사항의 실행 가능성을 평가
• 첫 번째 마일스톤과 그 예산(몇 개의 Cycle)을 정의

마일스톤 정의가 끝나면, 시스템이 자동으로 IMPLEMENTATION 단계로 전환되며 Ares가 투입됩니다.

Step 3: Ares가 구현 실행

Dashboard 상태가 IMPLEMENTATION 으로 바뀌고, Ares가 작업을 시작합니다.

1. 작업자 채용 — Ares가 workers/leo.md, workers/maya.md 등 파일을 생성
2. 작업 배정 — 각 Cycle마다 작업자 1명에게 구체적인 작업 1개만 배정
3. PR 심사 — 작업자가 PR을 제출하면, Ares가 Code Review 수행
4. Cycle 제어 — 한 Cycle 안에 완료하지 못하면 반려되어 다음 Cycle에서 다시 시도

Dashboard의 Chat 패널에서 Ares에게 직접 메시지를 보내 방향을 조정하거나 컨텍스트를 보완할 수 있습니다.

Step 4: Apollo 인수(검수)

Ares가 마일스톤 완료를 선언하면, 시스템은 VERIFICATION 으로 전환되고 Apollo가 투입됩니다.

→ Apollo가 코드 변경 사항을 읽음
→ 검증 테스트 실행(GitHub Actions 통해)
→ 마일스톤 요구사항 충족 여부 확인
→ 통과 → 다음 PLANNING으로 진입
→ 불통과 → IMPLEMENTATION으로 반려되며 무엇이 잘못인지 설명

Apollo의 기준은 Ares보다 한 단계 더 높아서, “Ares는 괜찮다고 생각했는데 Apollo가 반려하는” 일이 자주 발생합니다. 이것은 정상적인 설계이며 버그가 아닙니다.

Step 5: 수동 개입(필요한 경우)

Agent가 정말로 사람의 판단이 필요한 상황을 만나면 HUMAN: 으로 시작하는 GitHub Issue를 생성합니다.

HUMAN: 로그인 페이지는 OAuth로 할까요, 아니면 아이디/비밀번호로 할까요?
이 Issue에 대해 GitHub에서 답글을 달아주세요. Agent가 답변을 바탕으로 계속 진행합니다.

당신이 답하면, Ares가 계속 실행합니다. 굳이 개입이 필요 없다고 판단되면 Dashboard에서 프로젝트를 바로 일시정지할 수 있습니다.

---

Dashboard 기능 상세

TheBotCompany의 Dashboard는 전체 시스템의 제어 센터로, 모든 상태를 한눈에 확인할 수 있습니다.

프로젝트 전체 보기

Dashboard 홈에는 모든 프로젝트 카드가 표시되며, 각 카드에는 다음이 나옵니다.

• 현재 단계(PLANNING / IMPLEMENTATION / VERIFICATION)
• 현재 Cycle / Epoch 카운트
• 마일스톤 진행률 바
• 마지막 Agent Report의 요약

Agent Reports

각 프로젝트의 Agent 출력 히스토리이며, Markdown 렌더링과 자동 요약을 지원합니다. 어떤 Cycle의 출력이 특히 길다면 Dashboard가 자동으로 압축하여 핵심 결론만 표시합니다.

Issue Tracker

Agent 간의 조정은 여기서 전부 이뤄집니다.

• 프로젝트별 필터
• 상태별(Open / In Progress / Resolved)
• Agent별 필터
• 전용 Human Issues 패널: 당신이 처리해야 하는 모든 업그레이드 요청을 나열

Chat

Dashboard 안에 내장된 직접 대화 진입점입니다. 임의의 프로젝트를 선택해 해당 Manager에게 메시지를 보내 컨텍스트를 보완하거나 방향을 조정할 수 있습니다. 스트리밍 응답과 이미지 업로드를 지원합니다.

비용 추적(Cost Tracking)

각 프로젝트와 각 Agent의 비용 내역:

• Last Cycle 비용
• 24시간 평균 비용
• 누적 총비용

Budget Controls와 함께 사용하면 24시간 롤링 예산 상한을 설정할 수 있으며, 초과 시 Agent가 자동으로 절전(휴면) 상태로 들어갑니다.

Controls

Dashboard의 빠른 제어 버튼:

• Pause / Resume — 프로젝트 일시정지/재개(로그인 필요)
• Skip Sleep — 미리 설정된 절전 간격을 건너뛰고 즉시 다음 Cycle을 시작
• Kill Run / Cycle / Epoch — 현재 실행을 강제로 종료
• Bootstrap — 지정된 마일스톤부터 재시작

---

다중 Provider와 Key Pool 관리

지원하는 Provider 목록

TheBotCompany는 15+ 종의 LLM Provider를 기본 지원합니다.

Key Pool의 동작 방식

Settings의 Keys 패널에서 동일 Provider에 여러 Key를 추가하고 우선순위 순서를 설정할 수 있습니다. 실행 시:

1. 시스템은 우선순위가 가장 높은 Key를 먼저 사용
2. 해당 Key가 레이트 리밋(429) 또는 쿼터 부족을 트리거하면 → 다음 Key로 자동 전환
3. 쿨다운 시간이 끝나면 Key가 다시 사용 가능해져 라운드 로빈에 재진입

이는 장시간 실행이 필요한 프로젝트에서 특히 유용합니다. 단일 Key가 소진되어 Agent 팀 전체가 멈출까 걱정할 필요가 없습니다.

Model Tier 설정

각 프로젝트는 계층별로 사용할 모델을 커스텀할 수 있습니다.

# 프로젝트 단위 .tbc/config.yaml
model_tiers:
  high: claude-opus-4       # 복잡한 아키텍처, 심층 추론
  mid: claude-sonnet-4      # 기본, 성능과 비용의 균형
  low: claude-haiku-3       # 단순 반복 작업, 포맷팅

또는 Settings의 Model Tier Overrides 패널에서 UI로 직접 수정할 수도 있으며, 설정 파일을 건드릴 필요가 없습니다.

---

자주 발생하는 문제 해결

Q1: tbc start 이후 Dashboard가 열리지 않고 Connection Refused가 표시됨

원인: 포트가 이미 사용 중이거나, 서비스가 정상적으로 시작되지 않았습니다.

확인 절차:

# 1. tbc가 실행 중인지 확인
tbc status

# 2. 실행 중이 아니라면 수동으로 시작하고 오류 출력 확인
tbc dev

# 3. 포트가 점유되어 있으면 다른 포트를 지정
TBC_PORT=3200 tbc start

---

Q2: Agent 팀이 계속 PLANNING 단계에 머물며 IMPLEMENTATION로 넘어가지 않음

원인: Athena가 깊은 리서치를 하고 있거나 작업자 Agent의 결과를 기다리고 있는데, 아직 마일스톤을 정의하지 못했기 때문입니다.

해결 방법:

Dashboard → Agent Reports 를 열어 Athena의 최신 출력을 확인하세요. 그녀가 어떤 작업자의 리서치 결과를 기다리고 있다면, /tbc logs로 서버 로그를 확인해 실제로 막혀 있는지 확인할 수 있습니다. 만약 확실히 막혀 있다면, Dashboard의 Chat 패널에서 Athena에게 바로 메시지를 보내세요. 「현재 정보에 기반해 첫 번째 마일스톤을 정의하세요. 추가 리서치를 기다릴 필요 없습니다.」

---

Q3: GitHub PR이 자동으로 생성되지 않고, Agent가 Issue Tracker에서 권한 오류를 보고함

원인: gh CLI 인증이 올바르게 되어 있지 않거나, Token 권한이 부족합니다.

확인 절차:

# 1. gh 로그인 상태 확인
gh auth status

# 2. 로그인되어 있지 않다면 재인증( repo 권한 필요 )
gh auth login --scopes repo

# 3. 프로젝트 디렉터리의 remote URL이 올바른지 확인
cd /path/to/your-project

git remote -v

---

Q4: Apollo가 계속 Ares의 구현을 반려해 Cycle이 데드루프로 빠짐

원인: Ares가 매번 고치는 방향이 Apollo가 기대하는 것과 일치하지 않거나, 마일스톤 정의 자체가 충분히 명확하지 않기 때문입니다.

해결 방법:

Dashboard의 Chat 패널에서 Ares에게 다음처럼 메시지를 보내세요. 「Apollo가 반려한 이유는 [Apollo Report에 있는 구체적인 의견을 붙여넣으세요]. 수정 전에 Apollo의 기준을 먼저 명확히 이해하고, Apollo와 함께 수정 방향을 확인한 뒤 진행하세요.」

Apollo의 기준이 너무 까다롭다면 PLANNING 단계에서 Athena가 마일스톤의 인수(검수) 조건을 조정할 수 있습니다.

---

Q5: 비용이 예상보다 크게 나와 모든 Agent를 즉시 일시정지하고 싶음

해결 방법:

# 방법 1: Dashboard 조작
# Dashboard 로그인 → 각 프로젝트 카드 → Controls → Pause

# 방법 2: CLI로 일시정지
tbc stop

# 방법 3: 예산 상한 설정(다음 실행 시 적용)
# Dashboard Settings → Budget Controls에서 24h 예산 상한을 설정

---

Q6: 여러 API Key를 추가했는데 Agent가 계속 같은 Key를 써서 초과가 발생

원인: Key Pool의 우선순위 순서가 올바르지 않거나, Key의 레이트 리밋 쿨다운이 아직 끝나지 않았기 때문입니다.

해결 방법:

Dashboard Settings → Keys 패널에서 각 Key의 상태를 확인하세요.

• Active — 정상 사용 중
• Cooldown — 레이트 리밋이 발생하여 냉각 중
• Exhausted — 쿼터 소진

어떤 Key가 Cooldown 상태로 오랫동안 머물고 있다면, 그 Key를 Key 목록의 맨 아래로 수동으로 옮겨 시스템이 다음 Key로 전환하도록 만드세요.

---

확장 읽기와 고급 방향

1. 작업자 Agent 기술 커스터마이즈

workers/ 디렉터리에 새로운 .md 파일을 만들어 팀의 역량을 확장할 수 있습니다.

---
reports_to: ares
role: DevOps Engineer
model: mid
---

# DevOps Engineer

당신은 DevOps 엔지니어입니다. CI/CD 파이프라인, 컨테이너화, 인프라 코드로서의 코드(IaC)에 능숙합니다.

Manager는 새로 추가된 작업자 Agent를 자동으로 감지하며, 다음 Cycle 시작 시 이들을 스케줄링할 수 있습니다.

2. 커스텀 Provider 연동

사내 내부의 LLM 서비스(OpenAI 또는 Anthropic 호환 형식)를 붙이고 싶다면, Settings → Keys → Add Custom Provider 에서 다음처럼 입력합니다.

{
  "name": "my-internal-llm",
  "baseUrl": "https://llm.internal.company.com/v1",
  "apiKey": "sk-internal-...",
  "model": "gpt-4"
}

3. GitHub Actions와의 깊은 통합

TheBotCompany의 Agent 설계는 시간이 많이 걸리는 테스트와 빌드를 GitHub Actions에서 돌리는 것을 권장합니다. 작업자 Agent의 스킬 파일에서 다음과 같이 지정하세요.

터미널에서 5분을 초과하는 테스트를 절대 직접 실행하지 마세요. 모든 테스트 슈트는 GitHub Actions로 트리거되어야 합니다.

이렇게 하면 Agent가 Cycle 타임아웃으로 kill되더라도 이미 제출된 코드와 CI 결과가 사라지지 않습니다.

4. 다중 프로젝트 관리와 총괄 보기

여러 프로젝트를 동시에 운영(오픈소스 유지보수, 사이드 프로젝트, 상업용 프로젝트 등)한다면, TheBotCompany의 통합 Dashboard에서 한 페이지로 모든 프로젝트의 상태, 비용, 문제 분포를 확인할 수 있습니다. 상단의 Project Filters로 빠르게 전환하고, Human Issues 패널에서 모든 업그레이드 요청을 한 곳에 모아 처리하며, 당신의 의사결정이 필요한 부분을 놓치지 않게 할 수 있습니다.

5. 예산과 비용의 정밀한 제어

기본 24시간 롤링 예산 상한은 전역 설정입니다. 서로 다른 프로젝트에 서로 다른 예산을 적용하고 싶다면, 여러 개의 TheBotCompany 인스턴스를 실행하면 됩니다(서로 다른 TBC_HOME 디렉터리). 각 인스턴스는 프로젝트와 예산을 독립적으로 관리하며 서로 영향을 주지 않습니다.