MCP·훅·커스텀 명령 통합 설계 | 클로드 코드 완벽 마스터: AI 개발 워크플로우

MCP·훅·슬래시 명령 통합 — 나만의 AI 개발 시스템

MCP, Hooks, 커스텀 슬래시 명령 — 이 세 도구를 각각 배우는 것과 통합해서 설계하는 것은 다른 차원의 이야기입니다. 잘 통합된 시스템에서는 "GitHub 이슈를 받아 → 코드 구현 → 테스트 통과 → PR 생성"이 명령 하나로 실행됩니다. 이 강에서는 세 도구의 역할을 명확히 구분하고, 시너지를 만드는 통합 설계를 다룹니다.

세 도구의 역할 구분

# MCP (Model Context Protocol)
역할: Claude가 외부 세계에 접근하는 통로
언제: 외부 서비스 데이터가 필요할 때 (GitHub 이슈, DB 쿼리, Slack)
예시: "이슈 #42 읽어줘" → GitHub MCP가 이슈 데이터 반환

# Hooks (이벤트 트리거)
역할: 특정 이벤트 발생 시 자동 실행되는 사이드이펙트
언제: Claude의 행동(파일 저장, 명령 실행)에 반응할 때
예시: TypeScript 파일 저장 → ESLint 자동 실행

# 슬래시 명령 (워크플로우 압축)
역할: 반복 프롬프트를 재사용 가능한 명령으로 포장
언제: 동일한 작업 패턴이 반복될 때
예시: /review → PR 전 체크리스트 전체 실행

통합 설계: 이슈 → PR 자동화 파이프라인

# 목표: GitHub 이슈 번호 하나로 구현 → PR까지 자동화

# 1. MCP 설정 (GitHub 연결)
# .claude/settings.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx" }
    }
  }
}

# 2. 슬래시 명령 생성
# .claude/commands/implement-issue.md
GitHub 이슈 #$ARGUMENTS 를 구현해줘.

단계:
1. GitHub MCP로 이슈 #$ARGUMENTS 내용 읽기
2. 관련 파일 탐색 (읽기만)
3. 구현 계획 작성 → 내가 승인하면 실행
4. 구현 후 테스트 작성 및 통과 확인
5. PR 초안 생성 (이슈 번호 연결: Closes #$ARGUMENTS)

# 3. Hook 설정 (구현 중 품질 자동 유지)
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "if [[ '$FILE' == *.ts* ]]; then npx tsc --noEmit 2>&1 | grep 'error TS' | head -5; fi"
      }]
    }]
  }
}

이제 /implement-issue 78 한 줄로 이슈 읽기 → 구현 → 테스트 → PR 초안 전체가 실행됩니다.

통합 설계: 주간 코드 건강 검진

# .claude/commands/weekly-health.md
프로젝트 주간 건강 검진을 실행해줘.

1. 코드 품질 (자동)
   npx tsc --noEmit → 타입 오류 수
   npm run lint → 린트 오류 파일 수
   npm audit → 보안 취약점

2. 의존성 현황 (자동)
   npm outdated → 업데이트 필요 패키지

3. DB 상태 (Supabase MCP 활용)
   테이블별 레코드 수 조회
   최근 7일 에러 로그

4. 결과 정리
   health-report-$(date +%Y%m%d).md 생성

# 이 명령은 /weekly-health 로 실행
# 또는 GitHub Actions schedule로 자동 주간 실행

설정 파일 전체 구조

프로젝트/
├── CLAUDE.md                      # 프로젝트 전체 컨텍스트
├── .claude/
│   ├── settings.json              # 권한 + Hooks + MCP 서버
│   └── commands/
│       ├── review.md              # /review
│       ├── pre-pr.md              # /pre-pr
│       ├── implement-issue.md     # /implement-issue [번호]
│       ├── weekly-health.md       # /weekly-health
│       └── deploy-check.md        # /deploy-check [환경]
└── .github/
    └── workflows/
        └── ai-review.yml          # PR 자동 리뷰

통합 시 주의사항

# MCP + Hook 조합 시 무한 루프 방지
# 나쁜 예: Hook이 MCP를 호출 → MCP가 파일 생성 → Hook 재실행
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write",  // 모든 Write에 Hook
      "hooks": [{ "command": "..." }]
    }]
  }
}

# 좋은 예: 특정 경로만 Hook 적용
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "command": "if [[ '$FILE' == */app/*.ts ]]; then npx tsc; fi"
        // app/ 아래 .ts 파일만 — 설정 파일 등 제외
      }]
    }]
  }
}

팀 공유 설정 파일 관리

# .gitignore — API 키는 절대 커밋 금지
.claude/settings.local.json   # 개인 MCP 토큰 (gitignore)

# .claude/settings.json — 팀 공유 (커밋)
{
  "permissions": { ... },      # 팀 공통 권한
  "hooks": { ... },            # 팀 공통 훅
  "mcpServers": {
    "supabase": {
      "command": "npx",
      "args": ["..."],
      "env": {
        "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
        // 환경변수 참조 — 실제 값은 .env.local에
      }
    }
  }
}

세 도구의 통합 설계에서 핵심은 "각 도구가 잘하는 일을 맡기는 것"입니다. MCP는 외부 데이터 접근, Hooks는 이벤트 반응, 슬래시 명령은 워크플로우 압축. 이 경계가 명확할수록 시스템이 예측 가능하고 유지보수하기 쉬워집니다.

핵심 정리

MCP(외부 접근) + Hooks(이벤트 반응) + 슬래시 명령(워크플로우 압축) — 역할 명확히 분리해야 시스템이 예측 가능
/implement-issue [번호] 패턴 — GitHub MCP + 슬래시 명령 조합으로 이슈 → 구현 → PR 원스텝 자동화
팀 공유: settings.json 커밋 + 개인 토큰은 환경변수 참조 — API 키 유출 없이 설정 공유

관련 검색어 · 클로드 코드 MCP · Claude Code Hooks · 클로드 코드 슬래시 명령 · AI 개발 시스템 설계 · 클로드 코드 완벽 마스터 · 자동화 통합