{"id":51436843,"url":"https://github.com/claude-code-expert/subagents","last_synced_at":"2026-07-05T07:07:35.296Z","repository":{"id":348434743,"uuid":"1198041266","full_name":"claude-code-expert/subagents","owner":"claude-code-expert","description":"개발 계획, 코드 리뷰, 리팩터링, QA, 디버그, 보안 점검, 문서 작성등의 기능을 별도의 Subagent로 처리하고 알림을 보내주는 개발 보조팀 Squad 입니다.","archived":false,"fork":false,"pushed_at":"2026-04-11T07:40:31.000Z","size":183,"stargazers_count":13,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-11T09:08:27.400Z","etag":null,"topics":["claude","claudecode","subagent"],"latest_commit_sha":null,"homepage":"https://www.brewnet.dev","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/claude-code-expert.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-01T04:31:11.000Z","updated_at":"2026-04-11T07:40:36.000Z","dependencies_parsed_at":"2026-04-01T08:01:56.588Z","dependency_job_id":null,"html_url":"https://github.com/claude-code-expert/subagents","commit_stats":null,"previous_names":["claude-code-expert/subagents"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/claude-code-expert/subagents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claude-code-expert%2Fsubagents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claude-code-expert%2Fsubagents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claude-code-expert%2Fsubagents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claude-code-expert%2Fsubagents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/claude-code-expert","download_url":"https://codeload.github.com/claude-code-expert/subagents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/claude-code-expert%2Fsubagents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35146128,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude","claudecode","subagent"],"created_at":"2026-07-05T07:07:30.451Z","updated_at":"2026-07-05T07:07:34.614Z","avatar_url":"https://github.com/claude-code-expert.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Squad Agent\n\n**[English](README.en.md)** | **[한국어](README.md)**\n\n**Claude Code 서브에이전트 시스템 — 리뷰, 기획, 리팩토링, QA, 디버깅, 문서, GitOps, 보안 감사를 전문 에이전트에 위임합니다.**\n\n![Squad Pipeline](docs/pipeline-diagram.svg)\n\n---\n\n## 빠른 시작\n\n### 방법 1: 원라인 설치 (curl) — 권장\n\n```bash\ncurl -sL https://raw.githubusercontent.com/claude-code-expert/subagents/main/install.sh | bash\n```\n\n### 방법 2: 클론 후 설치\n\n```bash\ngit clone https://github.com/claude-code-expert/subagents.git\ncd subagents\nbash install.sh\n```\n\n### 방법 3: 릴리스 다운로드\n\n[Releases](https://github.com/claude-code-expert/subagents/releases) 페이지에서 최신 `squad-agents-vX.Y.Z.tar.gz`를 다운로드하세요.\n\n```bash\ntar xzf squad-agents-v*.tar.gz\nbash install.sh\n```\n\n### 설치 후\n\n1. **Claude Code를 재시작합니다**\n2. `/agents`로 등록을 확인합니다\n3. `/squad-review`로 시작해보세요\n\n설치 스크립트가 3개 훅(SubagentStart, SubagentStop, UserPromptSubmit)을 `~/.claude/settings.json`에 자동 등록합니다.\n\n---\n\n## 서브에이전트 동작 원리\n\n### 서브에이전트란?\n\n서브에이전트는 메인 Claude Code 세션 안에서 **독립된 컨텍스트 윈도우**를 갖고 동작하는 전문화된 AI 인스턴스입니다. 일반 대화에서 \"코드 리뷰해줘\"라고 하면 모든 분석 과정이 하나의 컨텍스트에 쌓이지만, 서브에이전트에 위임하면 분석은 별도 윈도우에서 일어나고 메인에는 요약만 돌아옵니다.\n\n### 내부 동작\n\n서브에이전트는 Claude Code의 **Agent 도구**를 통해 호출됩니다. `bash`로 `claude -p`를 실행하는 것이 아닙니다.\n\n```\n1. 사용자: \"/squad-review src/auth/\"\n\n2. 메인 세션 → Agent(subagent_type=\"squad-review\", prompt=\"...\")\n   Agent 도구로 위임\n\n3. 새 컨텍스트 윈도우 생성:\n   - squad-review.md의 시스템 프롬프트 로드\n   - frontmatter에 명시된 도구만 사용 가능\n   - frontmatter에 명시된 모델 사용\n\n4. 서브에이전트가 자체 컨텍스트에서 작업:\n   - git diff, 파일 읽기, 분석 — 모두 서브에이전트 컨텍스트에만 남음\n   - 메인 세션 컨텍스트는 증가하지 않음\n\n5. 결과 반환:\n   - 최종 메시지만 메인 세션에 반환\n   - 서브에이전트 컨텍스트는 폐기\n```\n\n### 버전\n\n**v1.3.2** (현재) — [전체 변경 이력](CHANGELOG.md)\n\n| 버전 | 주요 변경 |\n|------|----------|\n| v1.3.2 | 자동 테스트 145건, pre-commit hook, 라우터 위임 강제, `run-all.sh` |\n| v1.3.1 | README 구조 개편 (KO/EN 분리), CI shellcheck 수정, 훅 메커니즘 문서화 |\n| v1.3.0 | Squad Router 훅 추가 (80 키워드, 3단계 매칭, context injection) |\n| v1.2.1 | 크로스 플랫폼 알림 (macOS/Linux/WSL), 서브에이전트 검증 완료 |\n| v1.1.3 | SubagentStart/Stop 배너, SHA256 체크섬, 자동 훅 등록 |\n| v1.1.0 | 에이전트 안전 규칙 추가, 파이프라인 컨텍스트, 도구 순서 표준화 |\n| v1.0.0 | 8개 에이전트, 9개 커맨드, SubagentStop 훅, 설치 스크립트 |\n\n\u003c!--\n### 솔직한 토큰 비용 구조\n\n\u003e **\"서브에이전트가 토큰을 절약한다\"는 흔한 오해입니다. 실제로는 더 씁니다.**\n\n서브에이전트의 가치는 토큰 절약이 아니라 **메인 컨텍스트 품질 유지**입니다.\n\n#### 예시: 20개 파일 변경 리뷰\n\n**인라인 (서브에이전트 없음):**\n\n```\n메인 컨텍스트: 24k (대화) + 30k (git diff) + 16k (파일 읽기) + 15k (분석) = 85k\n코딩 가능 용량: 115k / 200k\n총 토큰 소비: ~85k\n```\n\n**squad-review 서브에이전트 사용:**\n\n```\n메인 컨텍스트:       24k (대화) + 2k (반환된 요약) = 26k\n서브에이전트 컨텍스트: 4k (시스템) + 30k (diff) + 16k (읽기) + 15k (분석) + 4k (오버헤드) = 69k (폐기됨)\n코딩 가능 용량: 174k / 200k\n총 토큰 소비: ~95k (인라인보다 더 많음)\n```\n\n| 지표 | 인라인 | 서브에이전트 |\n|------|--------|------------|\n| 메인 컨텍스트 사용 | 85k | 26k |\n| 총 토큰 소비 | 85k | **95k (+12%)** |\n| 작업 가능 공간 | 115k | **174k (+51%)** |\n| 세션 후반 품질 | 저하 (context rot) | **유지** |\n\n#### 병렬 실행 비용\n\nAnthropic 문서에 따르면 멀티 에이전트 워크플로우는 단일 에이전트 대비 **4~7배의 토큰**을 소비합니다. 실측 보고에 따르면 Pro plan에서 5개 병렬 서브에이전트를 실행하면 15분 만에 사용량 한도에 도달합니다 (순차 처리 시 30분).\n\n#### 가치 있는 경우\n\n| 가치 있음 | 비효율적 |\n|----------|---------|\n| 대량 출력 (큰 diff, 로그) | 단일 파일 조회 |\n| 긴 세션 (context rot 방지) | 짧은 세션 |\n| 읽기 중심 탐색·분석 | 코드베이스 전체 추론 |\n| 병렬 독립 분석 | 순차 의존 작업 |\n| 도구 제한 강제 (Read-only) | 모든 도구 필요 작업 |\n\n\u003e **결론:** 서브에이전트는 **컨텍스트 위생 도구**입니다. 총 토큰은 더 쓰지만, 메인 세션이 깨끗하게 유지되어 세션 후반부 품질 저하를 방지합니다.\n--\u003e\n\n### 쓰는 이유\n\n1. **컨텍스트 격리 및 메인 컨텍스트 오염 방지** — 30k git diff가 서브에이전트에만 남고, 메인에는 요약 2k만 반환, 메인 컨텍스트가 늘어나면 토큰 소모도 비례하여 올라가므로 이를 서브에이전트로 분리하여 관리 \n2. **도구 제한** — squad-review는 Read-only. 도구 레벨 하드 제약 (프롬프트가 아님)\n3. **병렬 실행** — 여러 모듈을 동시에 분석\n4. **모델 라우팅** — 보안은 opus, 커밋 메시지는 haiku로 비용 최적화\n\n\u003e **왜 장기적으로 토큰을 절약하는가?**\n\u003e\n\u003e 1. 단일 연산 기준으론 서브에이전트가 더 비쌈 (85k vs 95k)\n\u003e 2. 하지만 메인 컨텍스트에 85k가 쌓이면, 이후 **매 턴마다** 그 85k가 input token으로 재전송됨\n\u003e 3. 서브에이전트로 분리하면 메인은 26k만 유지 → 이후 매 턴의 input 비용이 59k씩 절감\n\u003e 4. 10턴만 지나도 `59k × 10 = 590k` 토큰 차이 — 초기 10k 오버헤드를 훨씬 상회\n\u003e\n\u003e 세션이 길어질수록 서브에이전트의 가치는 기하급수적으로 증가합니다.\n\n### 에이전트 정의 형식\n\n```markdown\n---\nname: squad-review                    # 에이전트 ID\ndescription: \u003e                        # 자동 위임 트리거\n  Use PROACTIVELY after code changes.\ntools: Read, Grep, Glob, Bash         # 허용 도구 (하드 제약)\nmodel: opus                           # 모델\nmaxTurns: 15                          # 안전 제한\n---\n당신은 시니어 스태프 엔지니어...       # 시스템 프롬프트\n```\n\n---\n\n## 에이전트\n\n| 에이전트 | 역할 | 모델 | 도구 |\n|---------|------|------|------|\n| `squad-review` | 코드 리뷰 | opus | Read, Bash, Glob, Grep |\n| `squad-plan` | 기획 \u0026 와이어프레임 | opus | Read, Write, Edit, Bash, Glob, Grep |\n| `squad-refactor` | 리팩토링 | opus | Read, Write, Edit, Bash, Glob, Grep |\n| `squad-qa` | 테스트 \u0026 QA | sonnet | Read, Bash, Glob, Grep |\n| `squad-debug` | 디버깅 | opus | Read, Bash, Glob, Grep |\n| `squad-docs` | 문서 작성 | sonnet | Read, Write, Edit, Glob, Grep |\n| `squad-gitops` | Git 자동화 | haiku | Read, Bash, Glob, Grep |\n| `squad-audit` | 보안 감사 | opus | Read, Bash, Glob, Grep |\n\n---\n\n## 파이프라인\n\n코어 파이프라인은 에이전트를 자동으로 체이닝합니다:\n\n```\nsquad-plan → [구현] → squad-review → squad-qa → squad-gitops\n                           │    ▲\n                           │    │\n                           ▼    │\n                      squad-refactor\n                       (변경 요청 시)\n```\n\n언제든 호출 가능한 **온디맨드 에이전트**:\n\n- `squad-debug` — 근본 원인 분석\n- `squad-audit` — 보안 스캐닝\n- `squad-docs` — 문서 생성\n\n---\n\n## 훅 시스템\n\n3개의 훅이 자동화 레이어를 구동합니다. `install.sh`가 모두 자동 등록합니다.\n\n### 1. Squad Router (UserPromptSubmit)\n\n![Squad Router Flow](docs/wireframes/squad-router-flow.svg)\n\n자연어 자동 라우팅 — 슬래시 커맨드 없이도 키워드를 감지하여 적절한 서브에이전트로 위임합니다.\n\n#### 동작 원리\n\nClaude Code의 `UserPromptSubmit` 훅은 사용자가 프롬프트를 제출할 때마다 실행됩니다. Squad Router는 이 메커니즘을 활용합니다:\n\n```\n┌──────────────────────────────────────────────────────────────────┐\n│ 1. 사용자가 프롬프트 입력                                              │\n│    \"이 코드 보안 검사해줘\"                                            │\n│                                                                  │\n│ 2. Claude Code가 훅 실행 (프롬프트가 Claude에 전달되기 전)                │\n│    stdin → {\"prompt\": \"이 코드 보안 검사해줘\"}                        │\n│                                                                  │ \n│ 3. squad-router.sh가 키워드 매칭                                    │\n│    \"보안\" 감지 → AGENT=\"squad-audit\"                               │\n│                                                                  │ \n│ 4. stdout으로 JSON 출력 (context injection)                        │\n│    {\"hookSpecificOutput\": {                                      │\n│      \"hookEventName\": \"UserPromptSubmit\",                        │\n│      \"additionalContext\": \"[Squad Router] Use the squad-audit...\"│\n│    }}                                                            │\n│                                                                  │\n│ 5. Claude가 주입된 컨텍스트를 보고 서브에이전트에 위임                      │\n│    → Agent(subagent_type=\"squad-audit\", prompt=\"...\")            │\n└──────────────────────────────────────────────────────────────────┘\n```\n\n핵심은 `hookSpecificOutput.additionalContext`입니다. 이 필드로 출력한 텍스트는 Claude가 프롬프트를 처리할 때 system-reminder로 주입되어, Claude가 자연스럽게 해당 서브에이전트를 호출하도록 유도합니다. 프롬프트 자체는 변경되지 않습니다.\n\n```\n\"이 코드 리뷰해줘\"    → squad-review\n\"에러가 나요\"          → squad-debug\n\"보안 검사해줘\"        → squad-audit\n\"테스트 돌려줘\"        → squad-qa\n\"기획해줘\"             → squad-plan\n\"리팩토링 해줘\"        → squad-refactor\n\"문서 작성해줘\"        → squad-docs\n\"커밋 메시지 작성해\"   → squad-gitops\n```\n\n**80개 키워드** (한국어 42 / 영어 38)가 8개 에이전트에 매핑됩니다. 3단계 매칭:\n\n1. **스킵** — 슬래시 커맨드, `--no-route`, `SQUAD_ROUTER=off`\n2. **충돌 해결** — 다단어 패턴 (예: \"PR 리뷰\" → review, \"PR 작성\" → gitops)\n3. **일반 키워드** — 우선순위 기반 단일 단어 매칭\n\n**비활성화:**\n\n| 방법 | 범위 | 예시 |\n|------|------|------|\n| `--no-route` 프롬프트에 추가 | 건별 | \"리뷰해줘 --no-route\" |\n| `SQUAD_ROUTER=off` | 전역 (환경변수) | 전체 비활성화 |\n| `/squad-*` 슬래시 커맨드 | 자동 | 자동 스킵 |\n\n전체 키워드 목록은 [docs/SQUAD-ROUTER-KEYWORDS.md](docs/SQUAD-ROUTER-KEYWORDS.md)를 참고하세요.\n\n### 2. 파이프라인 체이닝 (SubagentStart / SubagentStop)\n\n`subagent-chain.sh` 훅이 시작/종료 이벤트를 모두 처리합니다:\n\n- **SubagentStart** — OS 알림: \"Squad: {agent} RUNNING\"\n- **SubagentStop** — OS 알림: \"Squad: {agent} COMPLETED\" + 다음 단계 안내\n\n에이전트별 다음 단계 안내:\n\n| 에이전트 | 완료 시 |\n|---------|---------|\n| squad-plan | → implement, then /squad-review |\n| squad-review | → /squad-refactor or /squad-qa |\n| squad-refactor | → /squad-review to verify |\n| squad-qa | → /squad-gitops commit |\n| squad-debug | → implement the fix |\n| squad-docs | Documentation updated. |\n| squad-gitops | Git artifacts generated. |\n| squad-audit | Address findings before deploy. |\n\n### 3. 알림 시스템 (크로스 플랫폼)\n\n서브에이전트 시작/종료 시 OS 네이티브 알림이 발생합니다:\n\n| 플랫폼 | 방식 | 사운드 |\n|--------|------|--------|\n| macOS | `osascript` (알림 센터) | `afplay` (Pop/Glass) |\n| Linux | `notify-send` | `paplay` / `aplay` |\n| Windows/WSL | PowerShell 팝업 | — |\n\n**알림 비활성화:**\n\n```bash\n# ~/.claude/settings.json에서 SubagentStart/SubagentStop 훅 제거\n# 또는 ~/.claude/hooks/subagent-chain.sh의 notify() 호출 주석 처리\n```\n\n### 훅 등록 (settings.json)\n\n```jsonc\n{\n  \"hooks\": {\n    \"UserPromptSubmit\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"bash ~/.claude/hooks/squad-router.sh\" }]\n      }\n    ],\n    \"SubagentStart\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"zsh ~/.claude/hooks/subagent-chain.sh\" }]\n      }\n    ],\n    \"SubagentStop\": [\n      {\n        \"matcher\": \"\",\n        \"hooks\": [{ \"type\": \"command\", \"command\": \"zsh ~/.claude/hooks/subagent-chain.sh\" }]\n      }\n    ]\n  }\n}\n```\n\n---\n\n## 커맨드\n\n| 커맨드 | 예시 |\n|--------|------|\n| `/squad-review` | `/squad-review src/auth/` |\n| `/squad-plan` | `/squad-plan payment system` |\n| `/squad-refactor` | `/squad-refactor src/utils/` |\n| `/squad-qa` | `/squad-qa` |\n| `/squad-debug` | `/squad-debug TypeError: Cannot read...` |\n| `/squad-docs` | `/squad-docs readme` |\n| `/squad-gitops` | `/squad-gitops pr` |\n| `/squad-audit` | `/squad-audit` |\n| `/squad` | `/squad review src/auth/` (통합 커맨드) |\n\n---\n\n## 사용 예시\n\n### 새 기능 개발\n\n```\n/squad-plan user profile editing       → 기획\n[구현]                                  → 코드 작성\n/squad-review                          → REQUEST_CHANGES\n/squad-refactor src/profile/           → 리팩토링\n/squad-review                          → APPROVE\n/squad-qa                              → PASS\n/squad-audit src/auth/                 → 보안 점검\n/squad-gitops pr                       → PR 생성\n```\n\n### 프로덕션 버그\n\n```\n/squad-debug \"TypeError: Cannot read properties of undefined\"\n[수정]\n/squad-qa → /squad-gitops commit\n```\n\n### 레거시 정리\n\n```\n/squad-review src/legacy/              → 문제 식별\n/squad-refactor src/legacy/utils/      → 리팩토링\n/squad-qa                              → 회귀 테스트\n/squad-docs readme                     → 문서 업데이트\n```\n\n---\n\n## 모델 라우팅\n\n| 에이전트 | 모델 | 이유 |\n|---------|------|------|\n| squad-review | opus | 보안·로직은 깊은 추론 필요 |\n| squad-plan | opus | 설계와 엣지케이스 |\n| squad-refactor | opus | 안전한 구조 변환 |\n| squad-qa | sonnet | 테스트 실행·결과 정리 |\n| squad-debug | opus | 근본 원인 분석 |\n| squad-docs | sonnet | 코드→문서화 |\n| squad-gitops | haiku | 패턴 작업, 비용 최적화 |\n| squad-audit | opus | 보안은 놓치면 안 됨 |\n\n전역 오버라이드: `export CLAUDE_CODE_SUBAGENT_MODEL=sonnet`\n\n---\n\n## 프로젝트별 오버라이드\n\n프로젝트에 `.claude/agents/squad-review.md`를 두면 전역 버전보다 우선합니다:\n\n```markdown\n---\nname: squad-review\ndescription: \u003e\n  Expert code review for MyProject.\ntools: Read, Grep, Glob, Bash\nmodel: opus\n---\n\n## MyProject Rules\n- TypeScript `any` PROHIBITED\n- All API responses must use Result type\n...\n```\n\n---\n\n## 제거\n\n```bash\nbash install.sh --uninstall\n```\n\nSquad Agent 파일만 `~/.claude/`에서 제거합니다. 백업 파일(`.bak`)은 유지됩니다.\n\n\u003e 참고: `~/.claude/settings.json`의 훅 항목은 수동 제거가 필요합니다.\n\n---\n\n## 아키텍처\n\n상세 아키텍처 문서는 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)를 참고하세요.\n\n---\n\n## 기여\n\n새 에이전트 추가나 개선 방법은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참고하세요.\n\n---\n\n## 라이선스\n\n[Apache License 2.0](LICENSE)\n\n---\n\n## 참고 자료\n\n- [Claude Code Sub-agents (공식)](https://docs.anthropic.com/en/docs/claude-code/sub-agents)\n- [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents/agent-sdk)\n- [shanraisshan/claude-code-best-practice](https://github.com/shanraisshan/claude-code-best-practice)\n- [VoltAgent/awesome-claude-code-subagents](https://github.com/VoltAgent/awesome-claude-code-subagents)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaude-code-expert%2Fsubagents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclaude-code-expert%2Fsubagents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclaude-code-expert%2Fsubagents/lists"}