(Claude) 개발자를 위한 Claude 실무 활용 완벽 가이드 2탄 - CLAUDE.md 팀 설계 + 서브에이전트 & 훅 & MCP 심화 (코딩 생산성 향상)

포스팅 목차

이 포스팅에서 다루는 것 (1탄과 달라진 점)
CLAUDE.md 실전 설계 전략 - 팀 레벨 컨텍스트 관리
Claude Code 심화 - 서브에이전트(Sub-agents)
Claude Code 심화 - 훅(Hooks)
Claude Code 심화 - MCP(Model Context Protocol) 연동
확장 포인트 총정리 - 언제 뭘 써야 할까?
공부하면서 생겼던 의문점
참고 자료

1. 이 포스팅에서 다루는 것 (1탄과 달라진 점)

1탄에서는 Claude 기본 활용법 (프롬프트 작성법, 코드 리뷰, .claude/commands 슬래시 커맨드 기초)을 다뤘습니다.

2탄은 실무에서 팀 단위로 Claude Code를 운영하는 방법에 집중합니다.

1탄 : Claude가 뭔지 알고, 기본 프롬프트 잘 쓰는 법
2탄 : 팀 프로젝트에 Claude Code를 본격적으로 녹여내는 법
3탄 : Claude API 직접 연동 + 플러그인/스킬 연동 (예정)

💡 이 포스팅 대상 : Claude Code를 써본 적 있고, 이제 팀/프로젝트 단위로 제대로 세팅하고 싶은 분들

2. CLAUDE.md 실전 설계 전략

2-1. CLAUDE.md가 왜 중요한가?

Claude Code를 실행하면 대화 컨텍스트는 매 세션마다 초기화됩니다.
어제 내가 "TypeScript strict 모드 써줘", "커밋은 한국어로 써줘" 라고 했어도, 새 세션에서는 또 말해줘야 합니다.

CLAUDE.md는 이 문제를 해결하는 프로젝트 영구 기억장치입니다.
Claude Code가 실행될 때마다 자동으로 읽어들이는 마크다운 파일로, 프로젝트 컨텍스트를 한 번 정의해두면 매 세션에 자동으로 적용됩니다.

2-2. CLAUDE.md 파일 위치와 우선순위

CLAUDE.md는 여러 위치에 계층적으로 배치할 수 있습니다.

위치	적용 범위	Git 공유
`~/.claude/CLAUDE.md`	내 컴퓨터 모든 프로젝트	개인 전용
`./CLAUDE.md` (프로젝트 루트)	해당 프로젝트 팀 전체	Git으로 공유
`./src/CLAUDE.md` (하위 폴더)	해당 폴더 관련 작업 시 자동 로드	Git으로 공유

Claude Code는 현재 작업 위치 기준으로 상위 → 하위 순서로 모든 CLAUDE.md를 자동 누적 로드합니다.
즉, 루트의 CLAUDE.md와 src/CLAUDE.md가 동시에 적용됩니다.

2-3. CLAUDE.md 실전 템플릿 (React + TypeScript 프로젝트 기준)

CLAUDE.md는 100~200줄 이내로 유지하는 것이 핵심입니다.
너무 길어지면 Claude가 중요한 지시를 놓치거나 불필요한 컨텍스트를 낭비하게 됩니다.

# 프로젝트 컨텍스트

## 기술 스택
- React 18 + TypeScript (strict mode)
- 상태관리: MobX
- 번들러: Vite
- 스타일: Tailwind CSS
- 컴포넌트 개발: Storybook
- 패키지 매니저: npm

## 프로젝트 구조
src/
├── components/     # 공통 UI 컴포넌트
├── features/       # 기능별 모듈 (도메인 단위)
├── stores/         # MobX 스토어
├── hooks/          # 커스텀 훅
├── types/          # 전역 타입 정의
└── utils/          # 유틸리티 함수

## 코드 컨벤션
- TypeScript strict 모드 준수, `any` 타입 사용 절대 금지
- 컴포넌트는 함수형으로만 작성
- MobX 스토어는 `class` 기반 작성
- 파일명: PascalCase (컴포넌트), camelCase (훅/유틸)
- 임포트 순서: 외부 라이브러리 → 내부 모듈 → 타입

## Git 컨벤션
- 브랜치: `feat/기능명`, `fix/버그명`, `refactor/대상`
- base 브랜치: `develop`
- 커밋: Conventional Commits 형식, 한국어로 작성
  예) feat(auth): 소셜 로그인 기능 추가

## 검증 명령어
- 타입 체크: `npm run type-check`
- 린트: `npm run lint`
- 테스트: `npm run test`
- 빌드: `npm run build`

## 추가 규칙 참조
- 상세 코딩 스타일: @docs/coding-conventions.md
- API 연동 패턴: @docs/api-patterns.md

💡 핵심 원칙 : CLAUDE.md는 Claude의 온보딩 문서입니다. "What(무엇)", "Why(왜)", "How(어떻게)" 세 가지를 담되, 길게 쓰지 말고 중요한 것에만 집중하세요.

2-4. @import로 상세 내용 분리하기

CLAUDE.md가 길어지면 Progressive Disclosure 전략을 활용합니다.
핵심 내용만 루트에 두고, 상세 내용은 별도 파일로 분리한 뒤 참조시키는 방법입니다.

project/
├── CLAUDE.md                    # 핵심 컨텍스트 (100줄 이내)
└── docs/
    ├── coding-conventions.md    # 상세 코딩 스타일
    ├── api-patterns.md          # API 연동 패턴
    └── git-workflow.md          # 브랜치 전략 상세

CLAUDE.md에서는 @ 문법으로 파일을 참조합니다.

## 추가 참조
- 전체 프로젝트 개요: @README.md
- 설치 가능한 npm 스크립트: @package.json
- 상세 코딩 가이드: @docs/coding-conventions.md

Claude Code가 관련 작업을 할 때만 해당 파일을 읽기 때문에, 컨텍스트 윈도우를 효율적으로 사용할 수 있습니다.

2-5. 팀에서 CLAUDE.md 운영하는 방법

팀 CLAUDE.md 운영 체크리스트

[ ] 프로젝트 루트 CLAUDE.md는 반드시 Git으로 관리
[ ] 개인 설정은 ~/.claude/CLAUDE.md에 분리 (Git 미포함)
[ ] 변경 시 PR에 포함해서 팀 리뷰 진행
[ ] 큰 리팩토링 후 CLAUDE.md 내용 업데이트
[ ] 신규 팀원 온보딩 시 CLAUDE.md 검토하도록 안내

⚠️ 주의 : CLAUDE.md에 API 키, 비밀번호 등 민감 정보를 절대 포함하지 마세요. Git에 공개되는 파일입니다.

3. Claude Code 심화 - 서브에이전트(Sub-agents)

3-1. 서브에이전트란?

Claude Code를 쓰다 보면 대화가 길어질수록 컨텍스트 오염 문제가 생깁니다.
앞서 한 작업의 코드들이 컨텍스트에 쌓이면서 집중력이 흐려지고, 이후 작업의 품질이 떨어지는 현상입니다.

서브에이전트(Sub-agents)는 이 문제를 해결합니다.
메인 Claude Code가 특정 작업을 별도 컨텍스트 창을 가진 전문 에이전트에게 위임하는 방식입니다.

메인 Claude Code
  ├── 전체 작업 조율
  ├── -> db-reader 서브에이전트 위임 (DB 조회만 담당, 읽기 전용)
  ├── -> code-reviewer 서브에이전트 위임 (리뷰만 담당)
  └── -> test-writer 서브에이전트 위임 (테스트 작성만 담당)

서브에이전트는 각자 독립된 컨텍스트 창을 가지기 때문에, 메인 컨텍스트를 오염시키지 않습니다.

3-2. 서브에이전트 파일 만들기

서브에이전트는 YAML 프론트매터가 포함된 마크다운 파일로 정의합니다.

위치 선택

위치	범위
`.claude/agents/*.md`	현재 프로젝트에서만 사용
`~/.claude/agents/*.md`	내 모든 프로젝트에서 사용

예시 1 : 코드 리뷰 전용 서브에이전트

---
name: code-reviewer
description: |
  React + TypeScript 코드 리뷰 전문 에이전트.
  PR 올리기 전 코드 품질 검증에 사용.
  "코드 리뷰해줘", "PR 리뷰해줘" 같은 요청 시 자동 호출.
tools: Read, Glob, Grep
---

너는 10년 경력의 React + TypeScript 시니어 개발자야.
아래 기준으로 코드를 리뷰해줘.

## 리뷰 기준

1. TypeScript strict 모드 준수 여부 (any 타입 사용 금지)
2. 불필요한 리렌더링 발생 여부 (useMemo, useCallback, React.memo)
3. MobX 스토어 패턴 일관성
4. 함수 단일 책임 원칙(SRP) 준수
5. 에러 핸들링 누락 여부

## 출력 형식

각 항목별로 문제가 없으면 "이상 없음"으로 표시.
문제 발견 시 코드 위치와 개선 방안을 함께 제시.

예시 2 : DB 읽기 전용 서브에이전트 (훅 활용)

---
name: db-reader
description: |
  데이터베이스 조회 전용 에이전트 (읽기 전용).
  DB 스키마 확인, 쿼리 분석 작업에 사용.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

데이터베이스 읽기 전용 쿼리만 실행할 수 있어.
SELECT 문만 허용되며, INSERT/UPDATE/DELETE/DROP은 절대 실행하지 마.

3-3. 서브에이전트 실행 방법

Claude Code에서 서브에이전트를 활용하는 방법은 세 가지입니다.

방법 1: 직접 호출 (이름으로 명시)

@code-reviewer 이 PR 코드 리뷰해줘

방법 2: Task 도구로 병렬 실행 (슬래시 커맨드 내에서)

.claude/commands/research.md 내용 예시:
allowed-tools: Task, WebSearch, Read, Grep
-> Task 도구로 아래 에이전트를 동시에 실행:
   1. 공식 문서 조사 에이전트
   2. Stack Overflow 사례 조사 에이전트
   3. 현재 코드베이스 관련 패턴 분석 에이전트

방법 3: 자연어로 대화 중 자동 위임

description에 적힌 키워드와 매칭되면 자동으로 서브에이전트 호출

💡 서브에이전트 핵심 개념 : 서브에이전트 파일의 내용은 시스템 프롬프트입니다. 작업 지시(user prompt)가 아니라 에이전트의 역할/성격을 정의하는 것입니다. 이 차이를 이해하면 훨씬 효과적으로 만들 수 있습니다.

4. Claude Code 심화 - 훅(Hooks)

4-1. 훅이란?

훅(Hooks)은 Claude Code가 특정 행동을 할 때 자동으로 실행되는 스크립트입니다.
Git hooks와 개념이 동일합니다. AI의 행동에 결정론적 제어(Deterministic Control)를 추가하는 방법입니다.

AI 행동 (파일 수정, 커맨드 실행 등)
    ↓
PreToolUse Hook 실행 (실행 전)
    ↓
실제 도구 실행
    ↓
PostToolUse Hook 실행 (실행 후)

4-2. 훅 종류

훅 이름	실행 시점	주요 용도
`PreToolUse`	도구 실행 직전	위험한 명령 차단, 권한 검증
`PostToolUse`	도구 실행 직후	자동 포맷, 린트 실행
`Notification`	Claude가 입력 대기 시	데스크탑 알림 전송
`Stop`	세션 종료 시	로그 저장, 리포트 생성
`SubagentStop`	서브에이전트 완료 시	결과 수집, 후처리

여기서 도구란?

Claude Code는 단순히 텍스트만 생성하는 게 아니라, 실제로 사용자의 컴퓨터에서 작업을 수행합니다. 파일을 읽고, 파일을 쓰고, 터미널 명령어를 실행하죠. 이때 Claude가 "컴퓨터에 실제로 뭔가를 하기 위해" 사용하는 기능들을 도구(Tool) 라고 부릅니다.

비유하자면, 목수에게 "망치", "톱", "드라이버" 같은 연장이 있는 것처럼, Claude Code에게는 다음과 같은 도구가 있습니다.

도구 이름하는 일

Read	파일 내용을 읽음
Write	새 파일을 생성하거나 기존 파일을 덮어씀
Edit	기존 파일의 일부분만 수정
Bash	터미널 명령어 실행 (예: npm install, ls, git commit)
Glob	파일 검색 (예: */.tsx)
Grep	파일 내용에서 문자열 검색

예를 들어 사용자가 "App.tsx 파일 만들어줘"라고 하면, Claude는 내부적으로 Write 도구를 호출해서 파일을 생성합니다. "npm install 해줘"라고 하면 Bash 도구를 호출해서 명령어를 실행합니다.

4-3. 훅 설정 방법

훅은 .claude/settings.json에서 설정합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [{ "type": "command", "command": "npm run lint" }]
      }
    ], # Claude가 Write 도구로 파일을 작성한 직후, npm run lint 실행
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/validate-command.sh" }]
      }
    ] # Claude가 Bash 도구를 사용하기 직전, 프로젝트 내의 .claude/hooks/validate-command.sh 스크립트 실행
  }
}

4-4. 실전 훅 예시

예시 1 : 파일 저장 후 자동 린트 + 타입 체크

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npm run lint --fix && npm run type-check" }]
      }
    ]
  }
}

예시 2 : 위험한 명령어 차단 스크립트

# .claude/hooks/validate-command.sh

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin)['tool_input']['command'])")

if echo "$COMMAND" | grep -qE "^(rm -rf|drop table|DELETE FROM)"; then
  echo "위험한 명령어가 감지되었습니다: $COMMAND" >&2
  exit 2
fi

exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/validate-command.sh" }]
      }
    ]
  }
}

💡 훅 exit code 의미
- exit 0 : 정상 통과, 작업 계속 진행
- exit 2 : 작업 차단, 에러 메시지를 Claude에게 피드백

5. Claude Code 심화 - MCP(Model Context Protocol) 연동

5-1. MCP란?

MCP(Model Context Protocol)는 Claude Code가 외부 서비스와 연결되는 표준 인터페이스입니다.
"AI를 위한 USB-C 포트"라고 이해하면 됩니다. 어떤 서비스든 MCP 규격만 맞추면 Claude Code에 연결할 수 있습니다.

Claude Code
  ├── MCP → GitHub (이슈 조회, PR 생성)
  ├── MCP → Slack (메시지 전송)
  ├── MCP → PostgreSQL (DB 쿼리)
  └── MCP → 내부 API 서버 (회사 도메인 데이터)

5-2. MCP 서버 추가 방법

# CLI로 추가 (가장 간단한 방법)
claude mcp add <서버이름> <실행명령>

# 예시: GitHub MCP 추가
claude mcp add github npx @modelcontextprotocol/server-github

# 예시: PostgreSQL MCP 추가 (환경변수 필요)
claude mcp add postgres npx @modelcontextprotocol/server-postgres \
  -e DATABASE_URL=postgresql://user:pass@localhost/mydb

또는 .claude/settings.json에 직접 작성합니다.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "${DATABASE_URL}" }
    }
  }
}

⚠️ 보안 주의 : MCP 설정 파일에 토큰이나 비밀번호를 직접 입력하지 말고, 위 예시처럼 환경변수로 분리하세요.

5-3. 실전 MCP 활용 예시

MCP가 연결되면 Claude Code가 외부 서비스를 직접 조작합니다.

# GitHub MCP 연결 후
> 현재 열려있는 이슈 목록 보여줘
> 이슈 #42의 내용을 읽고 해당 버그를 수정해줘
> 수정 완료한 PR 생성해줘

# PostgreSQL MCP 연결 후
> users 테이블 스키마 확인해줘
> 최근 7일간 신규 가입한 사용자 수 조회해줘 (읽기 전용 쿼리)

# Slack MCP 연결 후
> #dev-alert 채널에 배포 완료 메시지 보내줘

5-4. MCP 서버 범위 설정

# 프로젝트 범위 (팀 공유, .claude/settings.json)
claude mcp add --scope project github npx @modelcontextprotocol/server-github

# 개인 범위 (본인만, ~/.claude/settings.json)
claude mcp add --scope user my-tool npx my-custom-tool

# 목록 확인
claude mcp list

6. 확장 포인트 총정리 - 언제 뭘 써야 할까?

각 기능의 역할이 비슷해 보여서 헷갈리기 쉽습니다.
아래 표로 정리했습니다.

기능	한 줄 정의	언제 사용?
`CLAUDE.md`	프로젝트 영구 기억장치	항상 적용되어야 하는 컨텍스트/규칙
`.claude/commands/`	수동 실행 워크플로우	반복적으로 쓰는 특정 작업 자동화
서브에이전트	특화된 전문 에이전트	컨텍스트 분리, 병렬 작업, 역할 위임
훅(Hooks)	이벤트 기반 자동 스크립트	자동 린트, 위험 명령 차단, 알림
MCP	외부 서비스 연결	GitHub, DB, Slack 등 외부 도구 연동

작은 프로젝트 혼자 쓸 때:
  CLAUDE.md + .claude/commands/ 만으로 충분

팀 프로젝트로 규모가 커질 때:
  + 서브에이전트 (역할 분리)
  + 훅 (코드 품질 게이트)

외부 서비스 연동이 필요할 때:
  + MCP

7. 공부하면서 생겼던 의문점

Q. 서브에이전트와 슬래시 커맨드(.claude/commands)의 차이가 뭔가요?

두 가지는 목적이 다릅니다.

구분	슬래시 커맨드	서브에이전트
실행 방식	사람이 직접 `/명령어` 입력	Claude가 자동으로 위임하거나 `@이름`으로 호출
컨텍스트	메인 컨텍스트 공유	별도 독립 컨텍스트
주요 용도	반복 워크플로우 자동화	복잡한 작업의 역할 분리, 병렬 처리

간단한 반복 작업은 슬래시 커맨드로 충분합니다.
컨텍스트가 오염될 만큼 복잡하거나, 여러 작업을 병렬로 처리해야 할 때 서브에이전트가 유용합니다.

Q. 훅 스크립트에서 exit 2로 차단하면 Claude Code가 어떻게 반응하나요?

exit 2로 종료하면 Claude Code는 해당 작업을 실행하지 않고, 스크립트의 표준 에러(stderr) 출력을 읽어서 Claude에게 피드백으로 전달합니다.
Claude는 그 메시지를 보고 다른 방법을 시도하거나 사용자에게 상황을 설명합니다.

exit 0 외의 다른 코드(예: exit 1)는 훅 자체의 오류로 처리됩니다.

Q. MCP 서버를 팀에서 공유할 때 보안은 어떻게 관리하나요?

MCP 설정 자체(.claude/settings.json)는 Git으로 공유해도 됩니다.
단, 환경변수(${변수명})로 민감 정보를 분리하고, 실제 값은 각자 로컬 .env 파일에서 관리하는 방식을 권장합니다.

// Git 공유 가능한 설정
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

# 각자 로컬에만 존재하는 .env (Git 미포함)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxx

8. 참고 자료

Claude Code 공식 문서: https://code.claude.com/docs
Claude Code 서브에이전트 가이드: https://code.claude.com/docs/en/sub-agents
Claude Code 훅 가이드: https://platform.claude.com/docs/en/agent-sdk/hooks
Claude Code Best Practices (공식): https://code.claude.com/docs/en/best-practices
CLAUDE.md 작성 가이드 (HumanLayer): https://www.humanlayer.dev/blog/writing-a-good-claude-md
MCP 공식 문서: https://modelcontextprotocol.io

Claude를 공부하면 할수록 결과물 품질이 확연히 좋아지는 걸 체감하고 있어요.
오늘도 개발자 여러분 모두 화이팅~!!

저작자표시 비영리 변경금지 (새창열림)

'AI 활용 개발' 카테고리의 다른 글

(Claude) 개발자를 위한 Claude 실무 활용 완벽 가이드 - 코드 리뷰부터 문서 자동화, GitHub 커맨드 생성까지 (코딩 생산성 향상) (1)	2026.04.25

코드짜는 문과녀

포스팅 목차

1. 이 포스팅에서 다루는 것 (1탄과 달라진 점)

2. CLAUDE.md 실전 설계 전략

2-1. CLAUDE.md가 왜 중요한가?

2-2. CLAUDE.md 파일 위치와 우선순위

2-3. CLAUDE.md 실전 템플릿 (React + TypeScript 프로젝트 기준)

2-4. @import로 상세 내용 분리하기

2-5. 팀에서 CLAUDE.md 운영하는 방법

3. Claude Code 심화 - 서브에이전트(Sub-agents)

3-1. 서브에이전트란?

3-2. 서브에이전트 파일 만들기

3-3. 서브에이전트 실행 방법

4. Claude Code 심화 - 훅(Hooks)

4-1. 훅이란?

4-2. 훅 종류

4-3. 훅 설정 방법

4-4. 실전 훅 예시

5. Claude Code 심화 - MCP(Model Context Protocol) 연동

5-1. MCP란?

5-2. MCP 서버 추가 방법

5-3. 실전 MCP 활용 예시

5-4. MCP 서버 범위 설정

6. 확장 포인트 총정리 - 언제 뭘 써야 할까?

7. 공부하면서 생겼던 의문점

8. 참고 자료

'AI 활용 개발' 카테고리의 다른 글

댓글

티스토리툴바

포스팅 목차

1. 이 포스팅에서 다루는 것 (1탄과 달라진 점)

2. CLAUDE.md 실전 설계 전략

2-1. CLAUDE.md가 왜 중요한가?

2-2. CLAUDE.md 파일 위치와 우선순위

2-3. CLAUDE.md 실전 템플릿 (React + TypeScript 프로젝트 기준)

2-4. @import로 상세 내용 분리하기

2-5. 팀에서 CLAUDE.md 운영하는 방법

3. Claude Code 심화 - 서브에이전트(Sub-agents)

3-1. 서브에이전트란?

3-2. 서브에이전트 파일 만들기

3-3. 서브에이전트 실행 방법

4. Claude Code 심화 - 훅(Hooks)

4-1. 훅이란?

4-2. 훅 종류

4-3. 훅 설정 방법

4-4. 실전 훅 예시

5. Claude Code 심화 - MCP(Model Context Protocol) 연동

5-1. MCP란?

5-2. MCP 서버 추가 방법

5-3. 실전 MCP 활용 예시

5-4. MCP 서버 범위 설정

6. 확장 포인트 총정리 - 언제 뭘 써야 할까?

7. 공부하면서 생겼던 의문점

8. 참고 자료

'AI 활용 개발' 카테고리의 다른 글

관련글

댓글

티스토리툴바