소개글
SubAgent / Hook / Slash Command / Github Actions
- 본 문서는 Hyperithm 테크팀 IA (Intelligent Automation) 팀이, 사내 개발인력 생산성 강화를 위해 작성한 Claude Code 활용에 대한 실전 가이드입니다.
- 작성 시점은 2025년 8월 11일이며 작성자는 Hyperithm IA셀 박철완님, 이한결님입니다.
- 회사와 팀에 대한 소개는 다음에서 볼 수 있습니다.
- 홈페이지 - https://www.hyperithm.com
- 채용 - https://hyperithm.career.greetinghr.com
- CTO 양준하 https://www.linkedin.com/in/junha-y-5923061b6
- 커피챗 신청 환영입니다 - junha@hyperithm.com
Claude Code는 단순한 코딩 어시스턴트를 넘어 강력한 개발 환경 통합 도구로 활용할 수 있습니다. 특히 SubAgent를 통한 전문화된 AI 에이전트 생성, Slash Command를 활용한 워크플로우 자동화, Hook을 통한 시스템 보안 강화, 그리고 GitHub Actions와의 CI/CD 통합 등의 기능을 제대로 활용하면 개발 프로세스의 효율성과 안정성을 획기적으로 향상시킬 수 있습니다.
본 가이드에서는 이러한 심화 기능들인 SubAgent, Slash Command, Hook, Claude GitHub Actions의 실전 활용법을 단계별로 상세히 다룹니다. Claude Code의 기본적인 활용법이 궁금하시다면 이전 기초 가이드를 먼저 읽어보시는 것을 추천합니다. 기초 가이드를 통해 전체적인 개념을 이해하신 후 본문을 읽으시면 더욱 효과적으로 활용하실 수 있습니다.
서브에이전트 활용법
서브에이전트(SubAgent)는 특정 작업 유형을 처리하기 위해 Claude Code에서 사용할 수 있는 전문화된 AI 어시스턴트입니다. 자주 쓰이는 프롬프트를 서브에이전트로 만들어 독립된 세션에서 실행시킬 수 있습니다. 기존 Task 툴과 달리 고유한 목적과 전문성을 설정할 수 있고, 사용 가능한 툴도 미리 지정하여 더 안전하고 효과적으로 운용할 수 있습니다.
왜 필요할까요?
- Context 오염
- 하나의 대화로 모든 작업을 처리하면 대화가 길어질수록 성능이 떨어짐
- 길이 제한: 대화가 길어질수록 Context Window 길이 제한에 걸릴 위험
- 프롬프트 작성의 어려움
- 반복 작업마다 자세한 프롬프트를 매번 작성하기 어려움
- 변경 내용 분석 및 커밋, 특정 에러 메시지 디버깅 등 반복 이슈에 비효율적
- 병렬 작업
- 하나의 프롬프트로 여러 작업을 해야할 때 서브에이전트가 호출되도록 하면 병렬로 작업을 진행할 수 있습니다.
작동방식
서브에이전트 설정하기
서브에이전트 생성
- /agents 커맨드 입력 후 > Create new agent 선택
- 원하는 에이전트 설치 위치 선택, Project 디렉토리 혹은 유저 디렉토리
- 새로 생성할 에이전트 설명 입력
- 에이전트가 사용 가능한 툴 목록 설정
- 에이전트가 사용할 모델 선택
- 에이전트 색 선택 후 리뷰
- [테스크 설명]. use [에이전트 이름] agent 입력해서 에이전트 활용하기
서브에이전트 예시 코드 리뷰어
---
name: code-reviewer
description: 코드 작성 후 즉시 품질 검토. MUST BE USED for all code changes
tools: Read, Bash(git diff:*)
---
시니어 개발자 관점에서 Critical/Warning/Suggestion으로 분류하여 리뷰 제공.
보안, 성능, 가독성 중심으로 구체적인 개선 방안 제시.
디버거
---
name: debugger
description: 오류/테스트 실패 시 즉시 근본 원인 분석 및 수정
tools: Read, Edit, Bash, Grep
---
1. 오류 재현 → 2. 원인 분석 → 3. 최소 수정 → 4. 검증
근본 원인 해결에 집중하여 재발 방지.
서브에이전트 사용하기
SubAgent가 생성되면 두 가지 방식으로 활용할 수 있습니다:
# 자동 위임 (잘 트리거 되지 않을 수 있음)
> 이 코드를 리뷰해줘 # 자동으로 code-reviewer 호출
# 명시적 호출 (추천)
> @debugger investigate this error: [에러메시지]
Claude Code는 프롬프트 내용과 SubAgent의 이름과 description을 분석해 적절한 에이전트를 자동으로 선택합니다. 하지만 자동 위임이 원하는 대로 되지 않을 수 있으니 @를 이용해 명시적으로 서브에이전트의 이름으로 호출하는 걸 추천합니다. 반드시 자동 위임 방식으로 쓰고 싶다면 description에 “PROACTIVELY use” 혹은 “MUST use” 같은 키워드를 포함해 볼 수 있습니다.
서브에이전트를 사용하다보면 원하는대로 작동하지 않아 수정하고 싶을 수 있습니다.
그럴때는 다음과 같이 수정할 수 있습니다.
> /agents
> [수정할 SubAgent 선택]
> 2. Edit agent 선택
> Open in editor 선택으로 에이전트 파일 직접 수정 혹은 Tools / Model / Color 선택해서 수정
에이전트 파일은 이런 구조를 가지고 있습니다.
---
name: 서브에이전트 이름
description: 서브에이전트가 호출되어야 하는 상황에 대한 설명
model: sonnet # Optional - 사용할 모델 (haiku/sonnet/opus)
tools: tool1, tool2 # Optional - 사용 가능한 툴 목록, 기본은 전부 허용
---
서브에이전트의 시스템 프롬프트; 서브에이전트의 역할과 작동방식에 대한 설명
tools 목록에는 Bash, Edit, Read 등이 들어갈 수 있습니다. 전체 목록은 Claude Code 툴 목록에서 확인할 수 있습니다. 시스템 프롬프트에 MCP 툴에 대한 설명을 작성해두면 서브에이전트가 해당 툴을 사용하도록 할 수 있습니다. 예를 들어 Serena MCP 같은 메모리 관리 툴을 설명해 두면 서브에이전트가 프로젝트 맥락을 파악하는 데 도움이 됩니다. 직접 서브에이전트를 작성하는 것이 부담스럽다면, Claude Code SubAgents와 같은 오픈소스 프로젝트에서 이미 만들어진 다양한 전문 도메인별 서브에이전트를 활용할 수도 있습니다.
에이전트 추가 방법 예를 들어 code-reviewer 에이전트를 추가하고 싶다면:
- 레포지토리에서 원하는 에이전트 파일을 다운로드 (예: code-reviewer.md)
- ~/.claude/agents/ 디렉토리에 복사
- 즉시 Claude Code에서 사용 가능
# 예시: code-reviewer 에이전트 추가
curl -o ~/.claude/agents/code-reviewer.md \ https://raw.githubusercontent.com/wshobson/agents/main/code-reviewer.md
유용한 에이전트 6가지
- code-reviewer: 코드 품질, 보안, 유지보수성 관점에서 전문적인 코드 리뷰 수행
- test-automator: 단위/통합/E2E 테스트를 포함한 종합 테스트 스위트 생성
- docs-architect: 개발자 문서 작성 및 OpenAPI/Swagger 스펙 생성
- architect-reviewer: 시스템 아키텍처 설계 및 기술적 의사결정 검토
- debugger: 오류, 테스트 실패, 예상치 못한 동작에 대한 디버깅 전문가
- error-detective: 에러 로그 분석 및 근본 원인 추적 전문가
전체 에이전트 목록과 상세한 설명은 Claude Code SubAgents 레포지토리에서 확인할 수 있습니다.
커스텀 슬래시 명령어 만들기
커스텀 슬래시 명령어는 반복적인 프롬프트를 재사용 가능한 명령어로 만드는 기능입니다.
- 마크다운 파일에 프롬프트와 메타데이터를 정의
- $ARGUMENTS로 매개변수 전달
- ! 접두사로 Bash 명령 실행 결과를 포함 가능
서브에이전트와 차이점
| 기능 | 서브 에이전트 | 슬래시 커맨드 |
|---|---|---|
| 세션 | 독립된 세션 | 메인 세션 |
| 제어 가능성 | 제어 및 추가 지시 어려움 | 작업 중 멈추고 프롬프트 개선 가능 |
| 동시 작업 | 여러 작업 동시 수행 가능 | 단일 작업 수행 |
| 적합한 작업 | 덜 민감한 작업 (분석, 디버깅, 테스트를 위한 기초 계획 작성 등) | 간단하고 민감한 작업 (Write 위주 작업) |
| Context 부담 | 상대적으로 높음 | 상대적으로 낮음 |
사용방법
**/.claude/commands 디렉토리에 명령어 파일을 저장해 사용할 수 있습니다
명령어 예시: /test - 테스트 실행 + 자동 분석
# ~/.claude/commands/test.md
---
allowed-tools: Bash(npm run test:*), Bash(pytest:*), Read
description: 테스트 실행 후 실패 원인 분석 및 수정 방안 제시
argument-hint: "[테스트 명령어]"
---
## 테스트 실행 및 분석
실행할 명령어: `$ARGUMENTS`
### 테스트 결과
!$ARGUMENTS
### 요청사항
- 실패한 테스트의 근본 원인 파악
- 구체적인 수정 방법 제시 (파일명, 라인 번호 포함)
- 성능 개선 기회가 있다면 함께 제안
Claude Code 안에서 사용법:
/test npm run test:unit # 단위 테스트 + 분석
/test pytest tests/api/ # API 테스트 + 수정안
명령어 저장 위치
- 팀 공유용: .claude/commands/ (git으로 관리)
- 개인용: ~/.claude/commands/ (개인 설정)
Super Claude
슬래시 커맨드를 직접 작성하는 대신, 다른 사람들이 작성한 커맨드를 사용할 수 있습니다.
- 간단하게 사용 가능한 유용한 커맨드
- 잘 정의된 페르소나 - 맥락과 커맨드에 따라 자동으로 선택되고 직접 지정도 가능
설치방법
# uvx를 사용한 빠른 설치 (권장)
uvx install SuperClaude
SuperClaude install
# 또는 pip 사용
pip install SuperClaude
SuperClaude install --quick
# 또는 소스에서 설치
git clone https://github.com/SuperClaude-Org/SuperClaude_Framework.git
cd SuperClaude_Framework
uv sync
python3 -m SuperClaude install
커맨드 소개
커맨드 플래그 소개
- -plan: Claude Code의 Plan 모드 사용, 실행 전에 Execution Plan 표시
- -think -think-hard -ultrathink: 사용할 토큰 양 설정(~4K, ~10K, ~32K)
-
- 더 많은 토큰을 쓰면 더 좋은 결과를 얻을 수 있지만 오래 걸리고 Context Window를 빨리 채움
- -uc: 압축된 심볼을 이용해 사용하는 토큰 양을 60~80% 줄여줌
-
- 예) process_user_input(input_query) → ⍺(b)
- -safe-mode: 프로덕션 환경 혹은 위험한 작업 시 보수적으로 실행
이 외에도 수정 스코프 지정, 페르소나 지정, MCP 설정, 오케스트레이션 설정 등을 플래그로 조정할 수 있습니다. 전체 플래그 가이드를 참고해주세요.
Hook을 이용한 시스템 보호
Hook은 Claude Code가 특정 도구를 사용하기 전에 실행되는 스크립트입니다. Hook 스크립트를 통해 프로젝트 외부 파일 접근, 위험한 시스템 명령 실행, 민감 정보가 담긴 파일 조작 등을 사전에 차단할 수 있습니다.
보안 기능
- 디렉토리 탈출 방지: /etc/passwd 같은 시스템 파일 접근 차단
- 위험 명령어 차단: rm -rf, sudo 등 실행 전 차단
- 민감 파일 보호: .env, .ssh 등 중요 파일 접근 제한
- 감사 로깅: 모든 시도 내역 자동 기록
설정하기
1단계: 보안 스크립트 생성
# ~/.claude/hooks/security_hook.py
#!/usr/bin/env python3
import json, sys, os
from pathlib import Path
def is_safe_path(file_path):
try:
Path(file_path).resolve().relative_to(Path.cwd().resolve())
return True
except ValueError:
return False
def is_dangerous_command(cmd):
dangerous = ["rm -rf", "sudo", "/etc/passwd", "chmod 777"]
return any(danger in cmd.lower() for danger in dangerous)
# 메인 로직
input_data = json.load(sys.stdin)
tool_name = input_data.get('tool_name', '')
tool_input = input_data.get('tool_input', {})
# 파일 접근 검사
if tool_name in ['Read', 'Write', 'Edit']:
file_path = tool_input.get('file_path', '')
if not is_safe_path(file_path) or any(sensitive in file_path for sensitive in ['.env', '.ssh', '.aws']):
print("차단됨: 위험한 파일 접근", file=sys.stderr)
sys.exit(2)
# 명령어 검사
elif tool_name == 'Bash':
command = tool_input.get('command', '')
if is_dangerous_command(command):
print("차단됨: 위험한 명령어", file=sys.stderr)
sys.exit(2)
sys.exit(0) # 허용
2단계: Hook 등록
# ~/.claude/settings.json
{
"hooks": {
"PreToolUse": [{
"matcher": "Read|Edit|Write|Bash",
"hooks": [{"type": "command", "command": "python ~/.claude/hooks/security_hook.py"}]
}]
}
}
이제 Claude Code가 위험한 작업을 시도할 때마다 자동으로 차단됩니다.
위 예시는 기본적인 보안 검사만 포함한 간단한 버전입니다. 프로젝트와 환경에 맞는 검증 로직을 추가해 활용해주세요.
GitHub Actions에서 Claude 활용하기
Claude Code GitHub Actions는 PR이나 이슈에서 @claude를 멘션하는 것만으로 AI가 코드 분석, PR 생성, 기능 구현, 버그 수정을 자동으로 수행하도록 도와줍니다. GitHub 워크플로와 통합되어 이슈 생성부터 배포까지 전 과정에서 Claude Code를 활용할 수 있습니다.
주요 자동화 시나리오
- 이슈 → PR: 요구사항 설명만으로 완성된 PR 생성
- 자동 리뷰: PR 생성 시 즉시 품질/보안 검토
- 버그 수정: 오류 리포트에서 즉시 수정 PR 생성
- 문서 동기화: 코드 변경 시 관련 문서 자동 업데이트
설정하기
1단계, 레포지토리에 Claude Code GitHub App 설치: Claude Code GitHub App에서 레포지토리 권한 설정 2단계, 인증 설정: GitHub Repository → Settings → Secrets and variables → Actions 방법 1: API 키 사용 (모든 사용자)
Name: ANTHROPIC_API_KEY
Value: sk-ant-...
방법 2: OAuth 토큰 사용 (Pro/Max 사용자 권장)
# 로컬에서 토큰 생성
claude setup-token
Name: CLAUDE_CODE_OAUTH_TOKEN
Value: [생성된 OAuth 토큰]
3단계, 기본 워크플로우 추가
# .github/workflows/claude.yml
name: Claude Code
on:
issues:
types: [opened, assigned]
issue_comment:
types: [created]
pull_request_review:
types: [submitted]
pull_request_review_comment:
types: [created]
permissions:
contents: write
pull-requests: write
issues: write
actions: read
id-token: write
jobs:
claude:
if: |
(github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
(github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
(github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
with:
fetch-depth: 1
- name: Run Claude Code
id: claude
uses: anthropics/claude-code-action@beta
with:
# 원하는 인증 방법 사용
# anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
# claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
4단계, GitHub 안에서 사용
# 이슈에서 기능 구현 요청
@claude implement this feature based on the issue description
# PR에서 리뷰 요청
@claude review this code for security and performance issues
# 버그 수정 요청
@claude fix the TypeError in the user dashboard component
자동화 활용 예시: 자동 PR 리뷰
워크플로우 설정 파일
# .github/workflows/review-pr.yml
name: Auto Code Review
on:
pull_request:
types: [opened, synchronize]
permissions:
pull-requests: write # PR 리뷰 작성에 필요
contents: read # PR 내용 분석에 필요
id-token: write # claude-code-action OIDC 인증에 필요
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: anthropics/claude-code-action@beta
with:
# 원하는 인증 방법 사용
# anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
# claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
mode: experimental-review
custom_instructions: |
변경 내용을 코드 품질, 보안, 성능 관점에서 리뷰해주세요
Critical 이슈가 있다면 반드시 지적해주세요