실습 환경 구축

co-consult, co-deck 같은 멀티 에이전트 시스템을 사용하려면 몇 가지 도구가 필요합니다. 이 장에서는 Claude Desktop App 외에 필요한 도구를 한 번에 설치하고, 제대로 동작하는지 검증합니다.

사전 체크리스트

설치를 시작하기 전에 다음 항목들이 준비되어 있는지 확인하세요. 이 항목들은 멀티 에이전트 하네스를 사용하는 데 모두 필수입니다.

필수 구독

멀티 에이전트 하네스는 Claude Code를 기반으로 동작하며, Claude Code를 사용하려면 Claude Pro 또는 Claude Max 구독이 필요합니다.

시스템 요구사항

멀티 에이전트 하네스를 실행하려면 다음과 같은 최소 사양이 필요합니다.

RAM 8GB는 Claude Desktop App이 실행 중인 상태에서 추가 도구(Git, Bun 등)를 함께 사용할 수 있는 최소 메모리입니다. 여러 에이전트를 동시에 실행하거나 브라우저를 함께 사용한다면 16GB 이상을 권장합니다.

디스크 10GB는 각종 도구 설치와 프로젝트 파일 저장을 위한 여유 공간입니다. 향후 여러 프로젝트를 진행하려면 더 많은 공간이 필요할 수 있습니다.

setup 폴더 준비

설치 과정에서 사용할 스크립트와 설정 파일을 보관할 전용 폴더를 만듭니다. 이 폴더는 앞으로 진행할 모든 실습의 기준점이 됩니다.

폴더 생성

사용 중인 운영체제에 맞춰 아래 명령어를 실행하세요. setup 폴더는 Git 프로젝트를 저장할 위치 아래에 만듭니다.

mkdir C:\git\project\setup

mkdir -p ~/git/project/setup

이 폴더에는 향후 설치 검증 스크립트, 설정 파일, 프로젝트 템플릿 등이 저장됩니다. 폴더 위치는 언제든지 변경할 수 있지만, 이 핸드북에서는 위 경로를 기준으로 설명합니다.

폴더 구조

setup 폴더는 다음과 같은 구조로 구성됩니다. 지금은 빈 폴더이지만, 설치를 진행하면서 각 항목이 채워집니다.

MacOS 설치

MacOS에서는 Homebrew(홈브루)라는 패키지 매니저를 사용하면 필요한 도구를 간단하게 설치할 수 있습니다. Homebrew는 MacOS에서 가장 널리 사용되는 오픈소스 패키지 관리 도구입니다.

brew --version

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

brew install git

brew install gh

brew install oven-sh/bun/bun

gh auth login

Windows 설치

Windows에서는 각 도구를 개별적으로 설치합니다. PowerShell 또는 명령 프롬프트(CMD)를 사용하여 설치를 진행합니다.

winget install --id Git.Git -e --source winget

winget install --id GitHub.cli -e --source winget

powershell -c "irm bun.sh/install.ps1 | iex"

gh auth login

Linux 설치

Linux(Ubuntu/Debian 기준)에서는 apt 패키지 매니저와 공식 설치 스크립트를 사용합니다.

sudo apt update && sudo apt upgrade -y

sudo apt install -y git

(type -p wget >/dev/null || (sudo apt update && sudo apt-get install wget -y)) \
&& sudo mkdir -p -m 755 /etc/apt/keyrings \
&& out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
&& cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
&& sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
&& sudo apt update \
&& sudo apt install gh -y

curl -fsSL https://bun.sh/install | bash

source ~/.bashrc

gh auth login

설치 검증

모든 도구가 올바르게 설치되었는지 확인합니다. 터미널을 열고 다음 명령어들을 순서대로 실행하세요.

버전 확인

각 도구의 버전 번호가 정상적으로 표시되는지 확인합니다. 버전 번호가 나오면 설치가 성공한 것입니다.

git --version

예상 결과: git version 2.45.0 (버전 번호는 다를 수 있음)

gh --version

예상 결과: gh version 2.62.0 (버전 번호는 다를 수 있음)

bun --version

예상 결과: 1.1.30 (버전 번호는 다를 수 있음)

설치 검증 스크립트 실행

setup 폴더에 준비된 검증 스크립트를 실행하면 모든 도구의 설치 상태를 한 번에 확인할 수 있습니다.

git clone https://github.com/5throck/setup.git
cd setup
bun setup-common.ts       # 설치 검증 스크립트 실행

검증 스크립트는 Git, GitHub CLI, Bun의 설치 여부와 버전, 그리고 GitHub 인증 상태를 확인합니다.

검증 결과 예시

모든 도구가 정상적으로 설치되면 다음과 같은 결과가 표시됩니다.

문제 해결

설치 과정에서 자주 발생하는 문제와 해결 방법을 정리했습니다. 문제가 발생하면 아래 목록에서 해당 항목을 찾아보세요.

Bun 설치 실패: command not found: bun

원인: Bun이 설치되었지만 시스템 PATH에 등록되지 않았을 수 있습니다.

해결 방법:

echo 'export PATH="$HOME/.bun/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

$env:Path += ";$env:USERPROFILE\.bun\bin"

GitHub CLI 인증 오류: gh auth status가 실패하는 경우

원인: GitHub CLI가 브라우저 인증을 완료하지 못했거나, 인증 토큰이 만료되었을 수 있습니다.

해결 방법:

gh auth logout
gh auth login

Claude Desktop App 연결 오류

원인: 인터넷 연결 문제, Anthropic 서버 일시 중단, 또는 인증 토큰 만료일 수 있습니다.

해결 방법:

Git 설치 후 git 명령어를 인식하지 못하는 경우

원인: Git이 설치되었지만 시스템 PATH에 등록되지 않았습니다.

해결 방법:

echo $PATH

기타 문제