Squad
English | 中文
모든 프로젝트를 위한 인간 주도형 AI 에이전트 팀입니다. 단 하나의 명령으로 코딩 속도를 높여주는 팀을 만드세요.
Platform
주요 변경 사항은 CHANGELOG.md에 문서화되어 있습니다.
Squad란 무엇인가?
Squad는 GitHub Copilot을 통해 인간이 지휘하는 AI 개발 팀을 제공합니다. 만들고자 하는 것을 설명하면, 프론트엔드(frontend), 백엔드(backend), 테스터(tester), 리드(lead) 등 전문 분야의 팀원들이 파일 형태로 사용자의 저장소(repo)에 거주하게 됩니다. 이들은 세션 간에도 지속되며, 코드베이스를 학습하고, 결정을 공유하며, 감독을 포기하지 않으면서도 더 빠르게 움직이도록 돕습니다.
Squad는 엔지니어, 리뷰어 또는 의사결정권자를 대체하는 것이 아니라, 인간을 위한 생산성 도구입니다. 사람들은 우선순위, 승인, 최종 변경 사항에 대한 책임(accountable)을 지니며, Squad는 조정(coordination), 반복 작업, 병렬 실행을 돕습니다.
이것은 모자만 쓰고 있는 챗봇이 아닙니다. 각 팀원은 자체적인 컨텍스트에서 작동하며, 오직 자신의 지식만을 읽고, 학습한 내용을 다시 작성하여 작업의 투명성(inspectable)을 유지합니다.
책임감 있는 AI 입장 — Squad는 인간 운영자에게 GitHub Copilot을 통해 능력을 증폭시키기 위해 구축되었으며, 인간을 루프에서 제거하기 위한 것이 아닙니다. 이를 사용하여 더 빠르게 위임하고, 더 잘 검토하며, 거버넌스를 코드에 가깝게 유지하세요.
빠른 시작 (Quick Start)
1. 프로젝트 생성
mkdir my-project && cd my-project
git init
✓ 검증: git status를 실행하면 "No commits yet"이 표시되어야 합니다.
2. Squad 설치
사용하는 플랫폼에 맞는 설치 방법을 선택하세요:
| 방법 | 명령어 |
|---|
| npm (모든 플랫폼, Node.js 22.5 이상) | npm install -g @bradygaster/squad-cli |
| ... | |
Preview 및 내부 빌드는 squad-preview와 squad-insider Homebrew cask로, 또는 bradygaster.Squad.Preview와 bradygaster.Squad.Insider WinGet 패키지로 이용할 수 있습니다.
macOS, Linux, Windows용 직접 아카이브는 GitHub Releases에서도 이용 가능합니다.
모든 방법은 동일한 CLI를 설치합니다. 독립형(Standalone) 설치는 자체 Node.js 벤더를 포함하므로, Node.js나 npm 레지스트리 접근이 필요하지 않습니다. 필수 조건 및 플랫폼 세부 정보는 전체 설치 가이드를 참조하십시오.
⚡ 1초 만에 작동하고 싶으신가요? squad init --preset default를 사용하여 멤버, 헌장(charters), 라우팅 규칙이 모두 갖춰진 완전히 구성된 Squad로 즉시 시작할 수 있습니다. 기본 squad init(플래그 없음)은 단계별 설정 과정을 안내하므로, 의도적으로 Squad를 구축하고 사용자 정의하는 것을 선호하는 경우에 이상적입니다.
✓ 검증: 프로젝트에 .squad/team.md가 생성되었는지 확인하십시오.
3. GitHub 인증하기 (Issues, PRs 및 Ralph용)
✓ 검증: gh auth status를 실행하면 "Logged in to github.com"이 표시되어야 합니다.
4. Copilot을 열고 실행하기
copilot --agent squad --yolo
왜 --yolo인가요? Squad는 일반적인 세션에서 많은 도구 호출(tool calls)을 수행합니다. 이 플래그가 없으면 Copilot이 각 호출에 대해 승인을 요청할 것입니다.
VS Code에서 Copilot Chat을 열고 Squad 에이전트를 선택하십시오.
그런 다음:
새 프로젝트를 시작합니다. 팀을 설정해 주세요.
제가 만들 것은 React와 Node로 만든 레시피 공유 앱입니다.
✓ 검증: Squad가 팀원 제안으로 응답합니다. 확인하려면 yes를 입력하십시오. 그들은 작업할 준비가 되어 있습니다.
Squad는 지속적인 테마 캐스트(thematic cast)에서 이름을 따온 팀을 제안합니다. 당신은 예라고 말합니다. 그들은 준비되었습니다.
.NET 패키지
Microsoft Agent Framework 에이전트로서 Squad 팀을 호출해야 하는 .NET 앱을 구축하시겠습니까? Squad.Agents.AI는 src/Squad.Agents.AI에 있는 NuGet 패키지입니다. 버전 1.0.0은 .NET 8, 9, 및 10을 대상으로 하며 DI(Dependency Injection)에서 Squad 기반의 AIAgent를 등록합니다. 게시 전에 설치 및 로컬 검증을 위해 패키지 README를 참조하십시오.
업그레이드하기
Squad 업그레이드는 두 단계의 과정입니다.
1단계: CLI 바이너리 업데이트
설치했던 것과 동일한 채널을 사용하십시오:
| 설치 방법 | 업데이트 명령어 |
|---|
| npm | npm install -g @bradygaster/squad-cli@latest |
| ... | |
| 단계 2: 프로젝트 내 Squad 소유 파일 업데이트 | |
squad upgrade는 squad.agent.md, .github/skills, Squad 워크플로우 및 .squad/templates/를 최신 버전으로 업데이트합니다. 이 과정에서 콘텐츠를 먼저 비교하여 재실행(또는 CRLF 체크아웃)해도 아무것도 변경되지 않도록 하며, 사용자가 커스터마이징한 파일은 덮어쓰기 전에 <file>.local-backup으로 백업합니다. 또한 .squad/ 팀 상태에는 절대 영향을 주지 않아 에이전트, 결정 및 기록이 항상 보존됩니다.
설치된 버전이 이미 최신 버전과 일치하더라도 업데이트를 다시 적용하려면 --force를 사용하십시오.
다른 AI 호스트에서 Squad 사용하기
Squad는 특정 클라이언트에 종속되지 않습니다. 프로젝트에 동일한 팀과 squad_state 백엔드를 Claude Code, Kiro, OpenCode, Cursor, OpenAI Codex 또는 Google Antigravity(Copilot와 함께)로 투사하려면 --client를 추가하십시오:
squad init --client claude,opencode
squad upgrade --client codex
각 호스트는 네이티브 코디네이터 파일과 MCP 배선을 받으며, .mcp.json, opencode.json 등의 사용자가 설정한 값은 절대 덮어쓰기(clobber)되지 않습니다. 자세한 내용은 Using Squad across clients, Squad 2.0 architecture, 그리고 multi-client quickstart를 참조하십시오.
로컬 개발 환경 설치
개발 목적으로 소스에서 Squad를 설치하고 실행하려면 다음을 따르십시오:
git clone https://github.com/github/squad.git
cd squad
...
npm run dev:link 실행 후, squad 명령어가 전역적으로 사용 가능해지며 로컬 빌드를 사용합니다. 코드 변경 후 업데이트하려면 재컴파일하기 위해 npm run build를 다시 실행하십시오.
빠른 명령어
채팅에서 **"squad commands"**라고 말하면 설치 및 업그레이드, 팀 관리, 이슈 및 PR(Pull Request), 플러그인, 모델 설정, 세션 상태 등 일반적인 작업에 대한 분류된 메뉴를 볼 수 있습니다. 또한 "state 백엔드를 어떻게 전환하나요?" 또는 "팀원을 추가하려면 어떻게 하나요?"와 같이 자연어로 질문할 수도 있습니다 — Squad는 사용자의 의도를 파악하고 단계별로 안내합니다. squad-commands 스킬은 모든 squad init 및 squad upgrade 시 기본적으로 제공됩니다 (out of the box).
모든 명령어 (17개)
| 명령어 | 기능 |
|---|
squad init | 초기화(Init) — 현재 디렉터리에 Squad를 스캐폴딩합니다 (idempotent, 여러 번 실행해도 안전함); 별칭(alias): cast; --client <list>는 Claude Code, Kiro, OpenCode, Cursor, Codex 및 Antigravity도 프로젝트에 추가합니다; 듀얼 루트 모드(dual-root mode)를 사용하려면 --mode remote <path>을 사용하세요. |
| ... | |
Watch Mode — Ralph의 자동 폴링(Automated Polling)
Ralph는 지속적으로 작업을 폴링하고 에이전트를 배포하여 처리하게 합니다. Watch 모드는 인간 팀이 민첩성을 유지하도록 돕습니다 — Ralph가 트리아지, 실행 인계(execution handoffs), 모니터링을 자동화한 다음, 판단이나 승인이 필요할 때 사람에게 다시 에스컬레이션합니다.
빠른 시작(Quick Start)
주요 플래그(Key Flags)
| 플래그 | 설명 |
|---|
--execute | 에이전트 실행 활성화 (실행 가능한 이슈에 대해 Copilot 세션 생성) |
| ... | |
Watch가 무엇을 실행할지 결정하는 방법
Ralph는 **에이전트 위임 선택 패턴(agent-delegated selection pattern)**을 사용합니다:
- Ralph는 트리아지 대상 이슈(unassigned, labeled 등)를 스캔합니다.
- Ralph는 컨텍스트 스냅샷(context snapshot): 이슈 목록, squad 상태, 최근 결정 사항을 구축합니다.
- Ralph는
-p <path> 플래그를 사용하여 이 컨텍스트를 **임시 파일(temp file)**에 작성합니다.
- Ralph는 해당 파일을 가지고 에이전트를 호출합니다:
gh copilot -p context.md.
- 에이전트가 어떤 이슈를 작업할지 그리고 어떻게 할지를 결정합니다.
- Ralph는 실행을 모니터링하고, 결과를 기록하며, 이슈 상태를 업데이트합니다.
이 설계는 폴링 루프(polling loop)를 간결하게 유지하면서도 에이전트가 팀의 규칙, 검토 게이트(review gates), 그리고 에스컬레이션 정책(escalation policy)에 따라 이슈 선택을 자동으로 처리하도록 합니다.
이슈 선택 및 에스컬레이션 (Issue Selection & Escalation)
Ralph는 에이전트에게 풍부한 프롬프트 스캐폴드(prompt scaffold)를 제공합니다:
## 작업 컨텍스트 (Work Context)
### 사용 가능한 이슈 (Available Issues) (우선순위 지정됨)
...
에이전트는 **전체 컨텍스트(full context)**를 확인하고, 무작위 작업을 맹목적으로 실행하기보다는 지능적으로 결정할 수 있습니다.
오류 복구 (오류 복구) (4단계 에스컬레이션)
Watch는 계층화된 복구 전략을 포함합니다:
- Tier 1 — 회로 차단기 리셋(Circuit Breaker Reset): 명확하게 확인하고 재시도
- Tier 2 — 인증 재검증(Auth Reprobe): 자격 증명 재확인
- Tier 3 — Git 풀(Git Pull): 로컬 상태 업데이트
- Tier 4 — 30분 일시 중지(Pause 30m): 인간의 개입을 위해 대기
이는 watch가 동일한 실패를 끝없이 스팸하는 것을 방지합니다.
상태 백엔드 (State Backends)
Watch는 다양한 방식으로 상태를 영속화할 수 있습니다:
squad watch --execute
...
안전한 종료 (Graceful Shutdown)
실행 중인 watch 프로세스를 안전하게 중지하려면:
touch .squad/ralph-stop
...
정리 (Cleanup)
Watch는 오래된 아티팩트들을 자동으로 정리합니다:
- 7일보다 오래된 스크래치 디렉토리
- 30일보다 오래된 로그 파일
- 고아 상태 오케스트레이션(Orphaned orchestration state)
Watch 모니터링 (Monitoring Watch)
실행 중인 watch를 확인합니다:
출력 예시:
Ralph Watch Status
PID: 12345
...
대화형 셸 (Interactive Shell)
⚠️ 사용 중단됨(Deprecated): 대화형 셸(squad를 인자 없이 사용)은 더 이상 지원되지 않습니다. 최고의 Squad 경험을 위해서는 대신 GitHub Copilot CLI를 사용하십시오.
copilot --agent squad
현재 옵션은 [인터페이스 선택(Choose your interface)](docs/src/content/docs/get-started/choose-your-interface.md)을 참조하십시오.
매번 명령어를 입력할 때마다 squad를 타이핑하는 것이 지겨우신가요? 대화형 셸에 진입하세요.
셸 진입 (Entering the Shell)
인자 없이 단순히 squad만 사용합니다. 다음과 같은 프롬프트가 나타날 것입니다:
이제 당신은 팀에 연결되었습니다. 그들과 대화하세요.
셸 명령어(Shell Commands)
모든 셸 명령어는 /로 시작합니다:
| 명령어 | 기능 |
|---|
/status | 팀 상태 및 진행 상황 확인 |
| ... | |
에이전트와 대화하기 (Talking to Agents)
@에이전트 이름 (대소문자 구분 안 함) 또는 쉼표를 사용한 자연어로 사용합니다:
squad > @Keaton, analyze the architecture of this project
squad > McManus, write a blog post about our new feature
squad > Build the login page
코디네이터(coordinator)가 메시지를 적절한 에이전트에게 라우팅합니다. 여러 에이전트가 병렬로 작업할 수 있으며 — 실시간으로 진행 상황을 확인할 수 있습니다.
셸의 기능 (What the Shell Does)
- 실시간 가시성(Real-time visibility): 에이전트가 작동하는 모습, 결정 사항 기록, 블로커 등을 발생 즉시 확인합니다.
- 메시지 라우팅(Message routing): 필요한 것을 설명하면, 코디네이터가 누가 처리해야 할지 파악합니다.
- 병렬 실행(Parallel execution): 여러 에이전트가 독립적인 작업을 동시에 수행합니다.
- 세션 지속성(Session persistence): 에이전트가 충돌해도 체크포인트부터 재개되므로 컨텍스트를 잃지 않습니다.
- 결정 기록(Decision logging): 모든 결정은 팀 전체가 볼 수 있도록
.squad/decisions.md에 기록됩니다.
셸 사용에 대한 더 자세한 내용은 위의 명령어 테이블을 참조하세요.
샘플 (Samples)
초급부터 고급까지 8가지 작동 예제(캐스팅, 거버넌스, 스트리밍, Docker 등)를 확인하세요. samples/README.md를 참조하세요.
에이전트는 병렬로 작동하고 — 당신은 통제권을 유지합니다 (Agents Work in Parallel — You Stay in Control)
Squad는 한 명의 인간이 더 많은 작업을 동시에 조정할 수 있도록 돕습니다. 작업을 할당하면, 코디네이터는 사용 가능한 모든 에이전트를 동시에 실행하며 — 당신은 우선순위 설정, 검토, 최종 결정을 담당합니다.
You: "Team, build the login page"
🏗️ Lead — analyzing requirements... ⎤
...
에이전트들이 작업을 완료하면, 코디네이터는 후속 작업 내용을 기록하고 출처 추적 경로(breadcrumb trail)를 남겨 당신이 모든 컨텍스트와 함께 무슨 일이 일어났는지 검토할 수 있게 합니다:
decisions.md — 모든 에이전트가 내린 결정 사항orchestration-log/ — 무엇이 생성되었고, 왜 그렇게 되었으며, 어떤 일이 발생했는지log/ — 전체 세션 기록 (검색 가능)
지식은 세션 간에 축적됩니다. 에이전트가 작업할 때마다, 그 학습 내용을 history.md 파일에 영구적으로 기록합니다. 몇 번의 세션이 지나면, 에이전트는 사용자의 규칙(conventions), 선호도(preferences), 아키텍처를 알게 됩니다. 심지어 이미 답변한 질문을 다시 묻지 않습니다.
그리고 이 모든 것이 Git에 담겨 있습니다. 사용자의 저장소(repo)를 클론하는 사람은 누구나, 그들이 축적한 모든 지식을 가진 팀 자체를 얻게 됩니다.
