Claude Code Skills·Hooks·MCP 실전 가이드: 설정 파일 4개로 팀 전체가 시니어급 결과물을 뽑아내는 방법

같은 Claude Code를 쓰는 10명의 팀원에게 "NestJS 서비스 레이어에 새 메서드를 추가해달라"고 요청해보자. 받아오는 코드는 제각각이다. 누군가는 팀 컨벤션에 맞는 DTO와 예외 처리까지 갖춘 코드를 받아오고, 다른 누군가는 컨트롤러에 비즈니스 로직이 뒤섞인 코드를 받아온다. 이 격차의 대가는 구체적이다. 코드 리뷰마다 같은 피드백이 반복되고, 수정 사이클이 늘어나고, 아무도 명시적으로 결정한 적 없는 기술 부채가 조용히 쌓인다.

격차의 원인은 모델 능력이 아니라 환경 설계의 차이다. Claude Code는 CLAUDE.md, Skills, Hooks, MCP라는 네 가지 레이어를 제공한다. 이 레이어들을 올바르게 조합하면, 시니어 개발자가 코드 리뷰에서만 전달하던 판단 기준을 팀 전체의 기본값으로 만들 수 있다. 새로 합류한 주니어도, 처음 보는 코드베이스에서도.

이 글을 다 읽으면 Git에 커밋 가능한 설정 파일 세트(CLAUDE.md, .claude/settings.json, Skills 파일)를 가져갈 수 있다. 사전 조건: Claude Code CLI가 설치되어 있고 기본적인 프롬프트 사용법을 아는 개발자를 대상으로 한다.

4개 레이어가 각각 해결하는 문제

전체 구조 한눈에 보기

네 가지 레이어는 각각 다른 문제를 해결한다. 먼저 전체 지도를 파악하고 시작하자.

레이어	파일 위치	역할	적용 방식
컨텍스트	`.claude/CLAUDE.md`	아키텍처 규칙, 금지 패턴 공유	Claude가 세션 시작 시 자동으로 읽음
워크플로	`.claude/commands/*.md`	표준 작업 절차 패키징	`/커맨드명` 으로 명시적 호출
가드레일	`.claude/settings.json`	품질 게이트 강제 실행	라이프사이클 이벤트에 자동 실행
외부 연동	MCP 서버 설정	티켓/PR/DB 자동 연동	도구(tool) 형태로 제공

CLAUDE.md — 팀의 코딩 헌법

CLAUDE.md는 Claude Code 세션이 시작될 때 자동으로 읽히는 문서다. 시니어 개발자가 "당연히 이렇게 해야 하는 것"으로 알고 있는 것들—어떤 패턴을 쓰지 말아야 하는지, 왜 이런 구조를 가졌는지—을 여기에 써두면 Claude Code는 모든 팀원에게 동일한 맥락에서 응답한다.

계층 구조를 활용하면 전사 규칙과 프로젝트별 규칙, 서브패키지별 규칙을 분리할 수 있다.

bash

~/.claude/CLAUDE.md          # 개인 전역 규칙 (커밋 스타일, 선호 언어 등)
.claude/CLAUDE.md            # 프로젝트 규칙 (아키텍처, 금지 패턴)
packages/frontend/CLAUDE.md  # 서브패키지 규칙 (모노레포 대응)

우선순위 규칙: 프로젝트 레벨 .claude/CLAUDE.md가 전역 ~/.claude/CLAUDE.md보다 높은 우선순위를 가지며, 서브패키지 CLAUDE.md는 해당 경로에서 추가적으로 적용된다. 충돌 시에는 더 구체적인(하위 경로의) 파일이 우선한다.

아래는 NestJS 프로젝트의 실제 CLAUDE.md 예시다.

shell

# 프로젝트 규칙
 
## 아키텍처
- 비즈니스 로직은 반드시 Service에, Controller는 얇게 유지한다
- DTO로 입력 검증, custom exception filter 사용
- `any` 타입 사용 금지 — 불가피할 경우 `unknown`과 타입 가드를 사용
 
## 금지 패턴
- `console.log` 대신 NestJS Logger 사용
- 직접 `throw new Error()` 금지 — 반드시 커스텀 예외 클래스 사용
 
## 빌드 명령
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`

Skills — `/커맨드` 하나로 실행되는 표준 절차

Skills(커스텀 슬래시 커맨드)는 .claude/commands/ 디렉터리에 저장하는 Markdown 파일이다. 팀원이 /커맨드명을 입력하면 해당 파일의 내용이 Claude의 지침으로 로드되어 실행된다.

중요: Skills는 자동으로 실행되지 않는다. 사용자가 명시적으로 /pr-review처럼 슬래시 커맨드를 입력해야 발동된다. 파일 내 "언제 실행한다"는 설명은 사람이 읽는 안내 문구이며, 시스템이 파싱해 자동 실행하는 규칙이 아니다.

파일 하나를 .claude/commands/pr-review.md에 저장하면 팀 전원이 동일한 PR 리뷰 절차를 /pr-review 한 번으로 실행할 수 있다.

Hooks — Claude의 판단을 우회하는 강제 실행

Hooks는 CLAUDE.md와 근본적으로 다르다. CLAUDE.md에 ".env 파일을 수정하지 마라"고 써도 Claude가 판단해서 따를 뿐이다. 반면 Hook으로 설정하면 Claude의 의도와 관계없이 항상 실행되거나 차단된다.

Hooks는 Claude Code의 라이프사이클 이벤트에 shell 명령을 바인딩한다.

이벤트	시점
`PreToolUse`	도구 실행 직전
`PostToolUse`	도구 실행 직후
`SessionStart`	세션 시작 시
`UserPromptSubmit`	사용자 입력 제출 시

Hook 실패 시 동작: Hook 명령이 **0이 아닌 종료 코드(non-zero exit code)**를 반환하면, PreToolUse에서는 해당 도구 실행이 즉시 중단되고, PostToolUse에서는 오류 메시지가 출력된다. lint 오류가 발생하면 Claude Code는 편집을 계속 진행하지 않고 멈춘다.

프롬프트 지시 vs. Hook: 프롬프트 지시는 "지침"이고, Hook은 "강제"다. 팀 표준을 진지하게 적용하려면 Hook이 필요하다.

MCP — 외부 시스템 연동의 표준 인터페이스

MCP(Model Context Protocol)는 Anthropic이 2024년 11월 오픈소스로 공개한 AI-도구 연동 표준 프로토콜이다. 2025년 3월 OpenAI가 공식 채택하면서 사실상 업계 표준(de-facto standard)으로 자리잡았다. 현재 수천 개의 MCP 서버가 커뮤니티에 의해 빌드되어 있다.

MCP를 사용하면 Claude Code가 GitHub, Jira, Slack, 데이터베이스 등 외부 시스템을 직접 도구(tool)로 조작할 수 있다. 이전까지 각 도구마다 별도로 작성해야 했던 통합 로직이 표준화된 하나의 인터페이스로 수렴된다.

코드로 보는 3가지 적용 시나리오

예시 1: Hook으로 품질 게이트 강제하기

.claude/settings.json을 Git에 커밋하면 팀원 모두가 동일한 Hook을 실행하게 된다. 아래는 두 가지를 동시에 적용하는 설정이다. 파일 편집 후 자동 lint와 타입 체크를 실행하고, main 브랜치 직접 수정 시도를 차단한다.

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm lint --fix && pnpm tsc --noEmit"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "scripts/check-branch-protection.sh"
          }
        ]
      }
    ]
  }
}

matcher 필드: 정규식(regex) 패턴이다. "Write|Edit"은 Claude Code가 Write 또는 Edit 도구를 사용할 때 Hook이 발동된다는 의미다. ".*"을 쓰면 모든 도구에 적용된다.

check-branch-protection.sh의 핵심 로직은 다음과 같다.

bash

#!/bin/bash
# scripts/check-branch-protection.sh
# main 브랜치에서 직접 commit/push 명령을 차단한다
 
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
COMMAND_ARGS="${CLAUDE_TOOL_INPUT:-}"
 
if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
  if echo "$COMMAND_ARGS" | grep -qE '\bgit\s+(commit|push)\b'; then
    echo "ERROR: main 브랜치에 직접 커밋/푸시할 수 없습니다. feature 브랜치를 사용하세요." >&2
    exit 1
  fi
fi
 
exit 0

이 스크립트가 exit 1을 반환하는 순간, PreToolUse Hook이 Bash 실행을 중단시키고 Claude Code는 해당 명령을 실행하지 않는다. 팀원이 실수로 main에 직접 푸시하는 일이 구조적으로 불가능해진다.

예시 2: Skills로 PR 리뷰 절차 표준화하기

시니어 개발자의 PR 리뷰 절차를 Skill로 패키징하면, 주니어도 동일한 품질의 리뷰를 수행할 수 있다.

yaml

---
name: pr-review
description: Pull Request를 팀 표준에 따라 리뷰한다
---
 
# PR 리뷰 절차
 
이 커맨드는 현재 브랜치의 변경 사항을 팀 표준에 따라 검토한다.
 
1. `git diff main` 으로 변경 파일 목록을 파악하고 컨텍스트를 이해한다
2. 팀 아키텍처 규칙(CLAUDE.md) 위반 여부를 확인한다
   - 비즈니스 로직이 컨트롤러에 있지 않은지
   - `any` 타입이 사용되지 않았는지
3. 보안 취약점(OWASP Top 10 기준) 스캔
4. 테스트 커버리지 확인 — 새로운 공개 메서드에 테스트가 있는지
5. 한국어로 리뷰 코멘트를 작성한다. 각 코멘트는 [심각도: 높음/중간/낮음] 레이블을 포함한다

이 파일을 .claude/commands/pr-review.md에 저장하면, /pr-review를 입력하는 것만으로 팀 표준 리뷰 프로세스가 매번 동일하게 실행된다. 이 파일을 Git에 커밋하는 것이 곧 팀 전체 배포다.

예시 3: MCP로 Jira-코드-GitHub를 하나의 흐름으로

MCP 서버를 설정하면 Claude Code가 외부 시스템을 직접 조작한다. "JIRA-1234 티켓을 구현해줘"라는 한 마디로, Jira 티켓 내용을 읽고 → 코드를 구현하고 → Jira 상태를 업데이트하고 → GitHub PR을 생성하는 과정이 처리된다.

bash

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "jira": {
      "command": "npx",
      "args": ["mcp-atlassian"],
      "env": {
        "ATLASSIAN_URL": "${JIRA_URL}",
        "ATLASSIAN_API_TOKEN": "${JIRA_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}

팀에서 자주 사용하는 MCP 서버 목록은 다음과 같다.

카테고리	패키지	용도
소스 관리	`@modelcontextprotocol/server-github`	PR, 이슈, 코드 검색
프로젝트 관리	`mcp-atlassian`	Jira 티켓 읽기/업데이트
데이터베이스	`@modelcontextprotocol/server-postgres`	쿼리 실행
파일 시스템	`@modelcontextprotocol/server-filesystem`	디렉터리 접근 제어
문서화	Confluence MCP Server	위키 읽기/쓰기

MCP 보안 주의: MCP 서버는 외부 시스템에 광범위한 접근권을 가질 수 있다. 팀 전체에 배포하기 전에 각 서버의 접근 범위(scope)를 명시적으로 최소화하라. 코드 리뷰용 GitHub MCP 서버는 읽기 권한만, PR 생성용은 쓰기 권한을 별도로 부여하는 것이 권장 패턴이다.

장단점 분석

장점

항목	내용
일관성 보장	Hook은 프롬프트 지시와 달리 예외 없이 실행되므로 팀 표준이 반드시 적용된다
지식 자산화	시니어 개발자가 코드 리뷰에서만 전달하던 판단 기준을 CLAUDE.md와 Skills에 인코딩해 주니어도 동등한 품질로 작업할 수 있다
크로스플랫폼	Skills 파일 하나로 Claude Code CLI, Claude Desktop, Claude.ai 웹 모두에서 동작한다
점진적 도입	CLAUDE.md → Skills → Hooks → MCP 순서로 단계적으로 확장 가능하다
변경 이력 추적	`.claude/` 디렉터리 전체를 Git으로 관리하면 팀 표준의 변경 이력이 코드와 함께 추적된다

단점 및 주의사항

항목	내용	대응 방안
초기 설정 비용	CLAUDE.md 작성, Skills 설계, Hook 스크립트 개발에 투자 시간이 필요하다	CLAUDE.md 한 파일부터 시작해 점진적으로 확장한다
유지보수 부담	오래된 지침은 없는 것보다 못한 잘못된 맥락을 제공하게 된다	분기별 리뷰 일정을 캘린더에 등록하고 Documentation Maintainer 역할을 명시적으로 지정한다
Hook 성능 영향	PostToolUse Hook에 무거운 테스트를 걸면 편집 속도가 급격히 저하된다	빠른 명령(lint, tsc)은 PostToolUse에, 전체 테스트는 PreCommit Hook에 배치한다
MCP 보안	MCP 서버가 외부 시스템에 광범위한 접근권을 가질 수 있다	최소 권한 원칙(least privilege)으로 각 서버의 권한 범위를 설계한다
모델 의존성	Claude 버전 업데이트로 Skills 동작 방식이 변할 수 있다	핵심 Skills 동작을 정기적으로 검증하는 루틴을 만든다
거버넌스 부재	담당자가 없으면 CLAUDE.md와 Skills가 현실과 멀어진다	팀 내 Documentation Maintainer 역할을 명시적으로 지정한다

실무에서 가장 흔한 실수

CLAUDE.md를 한 번 쓰고 업데이트하지 않는다. 프로젝트가 진화하면서 CLAUDE.md가 현실과 멀어지면, 없는 것보다 못한 잘못된 맥락을 제공하게 된다. 분기별 리뷰 일정을 팀 캘린더에 등록하라.
Hook에 너무 많은 검사를 넣는다. 모든 편집마다 전체 테스트 스위트를 실행하면 개발 속도가 급격히 떨어진다. PostToolUse에는 빠른 lint와 타입 체크만, 무거운 테스트는 PreCommit Hook에 배치하라.
MCP 서버 권한을 편의상 관리자 수준으로 설정한다. 광범위한 권한을 주는 순간 MCP 서버가 공격 표면이 된다. 팀 전체에 배포하기 전에 각 서버의 접근 범위를 명시적으로 정의하라.

마치며

결국 CLAUDE.md, Skills, Hooks, MCP 설정은 팀의 집단 지식을 코드로 버전 관리하는 행위다. 시니어 개발자의 판단 기준이 Slack 메시지나 코드 리뷰 코멘트로만 전달되면 그 지식은 휘발된다. .claude/ 디렉터리에 담기면, 팀원이 바뀌어도 프로젝트가 두 배로 커져도 사라지지 않는다.

지금 바로 시작할 수 있는 3단계:

.claude/CLAUDE.md 파일을 만든다. 무엇을 써야 할지 모르겠다면 지난 한 달간 코드 리뷰에서 반복된 코멘트를 찾아라. 같은 피드백이 세 번 이상 반복됐다면, 그것이 CLAUDE.md에 들어가야 할 첫 번째 규칙이다.
팀에서 가장 반복적으로 수행하는 작업 하나를 .claude/commands/ 아래에 파일로 작성하고, /커맨드명으로 팀원들과 공유한다. PR 리뷰, 스프린트 회고 요약, 마이그레이션 스크립트 생성 등 무엇이든 좋다.
.claude/settings.json에 PostToolUse Hook을 추가해 파일 편집 후 pnpm lint가 자동으로 실행되도록 설정하고, 이 파일을 Git에 커밋한다. 이 세 파일이 레포지터리에 들어가는 순간, 팀에 합류하는 모든 신규 팀원은 git clone 한 번으로 동일한 AI 개발 환경을 갖추게 된다. README에 "Claude Code 사용 시 .claude/ 디렉터리 설정이 자동으로 적용됩니다"라는 한 줄을 추가해두면 온보딩이 완성된다.

다음 글: Claude Code Subagents와 오케스트레이터 패턴으로 복잡한 멀티스텝 작업을 자동화하는 방법

참고 자료

Claude

Claude Code Skills·Hooks·MCP 실전 가이드: 설정 파일 4개로 팀 전체가 시니어급 결과물을 뽑아내는 방법

4개 레이어가 각각 해결하는 문제

전체 구조 한눈에 보기

네 가지 레이어는 각각 다른 문제를 해결한다. 먼저 전체 지도를 파악하고 시작하자.

레이어	파일 위치	역할	적용 방식
컨텍스트	`.claude/CLAUDE.md`	아키텍처 규칙, 금지 패턴 공유	Claude가 세션 시작 시 자동으로 읽음
워크플로	`.claude/commands/*.md`	표준 작업 절차 패키징	`/커맨드명` 으로 명시적 호출
가드레일	`.claude/settings.json`	품질 게이트 강제 실행	라이프사이클 이벤트에 자동 실행
외부 연동	MCP 서버 설정	티켓/PR/DB 자동 연동	도구(tool) 형태로 제공

CLAUDE.md — 팀의 코딩 헌법

계층 구조를 활용하면 전사 규칙과 프로젝트별 규칙, 서브패키지별 규칙을 분리할 수 있다.

bash

~/.claude/CLAUDE.md          # 개인 전역 규칙 (커밋 스타일, 선호 언어 등)
.claude/CLAUDE.md            # 프로젝트 규칙 (아키텍처, 금지 패턴)
packages/frontend/CLAUDE.md  # 서브패키지 규칙 (모노레포 대응)

우선순위 규칙: 프로젝트 레벨 .claude/CLAUDE.md가 전역 ~/.claude/CLAUDE.md보다 높은 우선순위를 가지며, 서브패키지 CLAUDE.md는 해당 경로에서 추가적으로 적용된다. 충돌 시에는 더 구체적인(하위 경로의) 파일이 우선한다.

아래는 NestJS 프로젝트의 실제 CLAUDE.md 예시다.

shell

# 프로젝트 규칙
 
## 아키텍처
- 비즈니스 로직은 반드시 Service에, Controller는 얇게 유지한다
- DTO로 입력 검증, custom exception filter 사용
- `any` 타입 사용 금지 — 불가피할 경우 `unknown`과 타입 가드를 사용
 
## 금지 패턴
- `console.log` 대신 NestJS Logger 사용
- 직접 `throw new Error()` 금지 — 반드시 커스텀 예외 클래스 사용
 
## 빌드 명령
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`

Skills — `/커맨드` 하나로 실행되는 표준 절차

중요: Skills는 자동으로 실행되지 않는다. 사용자가 명시적으로 /pr-review처럼 슬래시 커맨드를 입력해야 발동된다. 파일 내 "언제 실행한다"는 설명은 사람이 읽는 안내 문구이며, 시스템이 파싱해 자동 실행하는 규칙이 아니다.

파일 하나를 .claude/commands/pr-review.md에 저장하면 팀 전원이 동일한 PR 리뷰 절차를 /pr-review 한 번으로 실행할 수 있다.

Hooks — Claude의 판단을 우회하는 강제 실행

Hooks는 Claude Code의 라이프사이클 이벤트에 shell 명령을 바인딩한다.

이벤트	시점
`PreToolUse`	도구 실행 직전
`PostToolUse`	도구 실행 직후
`SessionStart`	세션 시작 시
`UserPromptSubmit`	사용자 입력 제출 시

Hook 실패 시 동작: Hook 명령이 **0이 아닌 종료 코드(non-zero exit code)**를 반환하면, PreToolUse에서는 해당 도구 실행이 즉시 중단되고, PostToolUse에서는 오류 메시지가 출력된다. lint 오류가 발생하면 Claude Code는 편집을 계속 진행하지 않고 멈춘다.

프롬프트 지시 vs. Hook: 프롬프트 지시는 "지침"이고, Hook은 "강제"다. 팀 표준을 진지하게 적용하려면 Hook이 필요하다.

MCP — 외부 시스템 연동의 표준 인터페이스

코드로 보는 3가지 적용 시나리오

예시 1: Hook으로 품질 게이트 강제하기

json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "pnpm lint --fix && pnpm tsc --noEmit"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "scripts/check-branch-protection.sh"
          }
        ]
      }
    ]
  }
}

matcher 필드: 정규식(regex) 패턴이다. "Write|Edit"은 Claude Code가 Write 또는 Edit 도구를 사용할 때 Hook이 발동된다는 의미다. ".*"을 쓰면 모든 도구에 적용된다.

check-branch-protection.sh의 핵심 로직은 다음과 같다.

bash

#!/bin/bash
# scripts/check-branch-protection.sh
# main 브랜치에서 직접 commit/push 명령을 차단한다
 
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null)
COMMAND_ARGS="${CLAUDE_TOOL_INPUT:-}"
 
if [[ "$CURRENT_BRANCH" == "main" || "$CURRENT_BRANCH" == "master" ]]; then
  if echo "$COMMAND_ARGS" | grep -qE '\bgit\s+(commit|push)\b'; then
    echo "ERROR: main 브랜치에 직접 커밋/푸시할 수 없습니다. feature 브랜치를 사용하세요." >&2
    exit 1
  fi
fi
 
exit 0

예시 2: Skills로 PR 리뷰 절차 표준화하기

시니어 개발자의 PR 리뷰 절차를 Skill로 패키징하면, 주니어도 동일한 품질의 리뷰를 수행할 수 있다.

yaml

---
name: pr-review
description: Pull Request를 팀 표준에 따라 리뷰한다
---
 
# PR 리뷰 절차
 
이 커맨드는 현재 브랜치의 변경 사항을 팀 표준에 따라 검토한다.
 
1. `git diff main` 으로 변경 파일 목록을 파악하고 컨텍스트를 이해한다
2. 팀 아키텍처 규칙(CLAUDE.md) 위반 여부를 확인한다
   - 비즈니스 로직이 컨트롤러에 있지 않은지
   - `any` 타입이 사용되지 않았는지
3. 보안 취약점(OWASP Top 10 기준) 스캔
4. 테스트 커버리지 확인 — 새로운 공개 메서드에 테스트가 있는지
5. 한국어로 리뷰 코멘트를 작성한다. 각 코멘트는 [심각도: 높음/중간/낮음] 레이블을 포함한다

예시 3: MCP로 Jira-코드-GitHub를 하나의 흐름으로

bash

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "jira": {
      "command": "npx",
      "args": ["mcp-atlassian"],
      "env": {
        "ATLASSIAN_URL": "${JIRA_URL}",
        "ATLASSIAN_API_TOKEN": "${JIRA_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_CONNECTION_STRING": "${DATABASE_URL}"
      }
    }
  }
}

팀에서 자주 사용하는 MCP 서버 목록은 다음과 같다.

카테고리	패키지	용도
소스 관리	`@modelcontextprotocol/server-github`	PR, 이슈, 코드 검색
프로젝트 관리	`mcp-atlassian`	Jira 티켓 읽기/업데이트
데이터베이스	`@modelcontextprotocol/server-postgres`	쿼리 실행
파일 시스템	`@modelcontextprotocol/server-filesystem`	디렉터리 접근 제어
문서화	Confluence MCP Server	위키 읽기/쓰기

MCP 보안 주의: MCP 서버는 외부 시스템에 광범위한 접근권을 가질 수 있다. 팀 전체에 배포하기 전에 각 서버의 접근 범위(scope)를 명시적으로 최소화하라. 코드 리뷰용 GitHub MCP 서버는 읽기 권한만, PR 생성용은 쓰기 권한을 별도로 부여하는 것이 권장 패턴이다.

장단점 분석

장점

항목	내용
일관성 보장	Hook은 프롬프트 지시와 달리 예외 없이 실행되므로 팀 표준이 반드시 적용된다
지식 자산화	시니어 개발자가 코드 리뷰에서만 전달하던 판단 기준을 CLAUDE.md와 Skills에 인코딩해 주니어도 동등한 품질로 작업할 수 있다
크로스플랫폼	Skills 파일 하나로 Claude Code CLI, Claude Desktop, Claude.ai 웹 모두에서 동작한다
점진적 도입	CLAUDE.md → Skills → Hooks → MCP 순서로 단계적으로 확장 가능하다
변경 이력 추적	`.claude/` 디렉터리 전체를 Git으로 관리하면 팀 표준의 변경 이력이 코드와 함께 추적된다

단점 및 주의사항

항목	내용	대응 방안
초기 설정 비용	CLAUDE.md 작성, Skills 설계, Hook 스크립트 개발에 투자 시간이 필요하다	CLAUDE.md 한 파일부터 시작해 점진적으로 확장한다
유지보수 부담	오래된 지침은 없는 것보다 못한 잘못된 맥락을 제공하게 된다	분기별 리뷰 일정을 캘린더에 등록하고 Documentation Maintainer 역할을 명시적으로 지정한다
Hook 성능 영향	PostToolUse Hook에 무거운 테스트를 걸면 편집 속도가 급격히 저하된다	빠른 명령(lint, tsc)은 PostToolUse에, 전체 테스트는 PreCommit Hook에 배치한다
MCP 보안	MCP 서버가 외부 시스템에 광범위한 접근권을 가질 수 있다	최소 권한 원칙(least privilege)으로 각 서버의 권한 범위를 설계한다
모델 의존성	Claude 버전 업데이트로 Skills 동작 방식이 변할 수 있다	핵심 Skills 동작을 정기적으로 검증하는 루틴을 만든다
거버넌스 부재	담당자가 없으면 CLAUDE.md와 Skills가 현실과 멀어진다	팀 내 Documentation Maintainer 역할을 명시적으로 지정한다

실무에서 가장 흔한 실수

CLAUDE.md를 한 번 쓰고 업데이트하지 않는다. 프로젝트가 진화하면서 CLAUDE.md가 현실과 멀어지면, 없는 것보다 못한 잘못된 맥락을 제공하게 된다. 분기별 리뷰 일정을 팀 캘린더에 등록하라.
Hook에 너무 많은 검사를 넣는다. 모든 편집마다 전체 테스트 스위트를 실행하면 개발 속도가 급격히 떨어진다. PostToolUse에는 빠른 lint와 타입 체크만, 무거운 테스트는 PreCommit Hook에 배치하라.
MCP 서버 권한을 편의상 관리자 수준으로 설정한다. 광범위한 권한을 주는 순간 MCP 서버가 공격 표면이 된다. 팀 전체에 배포하기 전에 각 서버의 접근 범위를 명시적으로 정의하라.

마치며

지금 바로 시작할 수 있는 3단계:

.claude/CLAUDE.md 파일을 만든다. 무엇을 써야 할지 모르겠다면 지난 한 달간 코드 리뷰에서 반복된 코멘트를 찾아라. 같은 피드백이 세 번 이상 반복됐다면, 그것이 CLAUDE.md에 들어가야 할 첫 번째 규칙이다.
팀에서 가장 반복적으로 수행하는 작업 하나를 .claude/commands/ 아래에 파일로 작성하고, /커맨드명으로 팀원들과 공유한다. PR 리뷰, 스프린트 회고 요약, 마이그레이션 스크립트 생성 등 무엇이든 좋다.
.claude/settings.json에 PostToolUse Hook을 추가해 파일 편집 후 pnpm lint가 자동으로 실행되도록 설정하고, 이 파일을 Git에 커밋한다. 이 세 파일이 레포지터리에 들어가는 순간, 팀에 합류하는 모든 신규 팀원은 git clone 한 번으로 동일한 AI 개발 환경을 갖추게 된다. README에 "Claude Code 사용 시 .claude/ 디렉터리 설정이 자동으로 적용됩니다"라는 한 줄을 추가해두면 온보딩이 완성된다.

다음 글: Claude Code Subagents와 오케스트레이터 패턴으로 복잡한 멀티스텝 작업을 자동화하는 방법

4개 레이어가 각각 해결하는 문제

전체 구조 한눈에 보기

CLAUDE.md — 팀의 코딩 헌법

Skills — /커맨드 하나로 실행되는 표준 절차

Hooks — Claude의 판단을 우회하는 강제 실행

MCP — 외부 시스템 연동의 표준 인터페이스

코드로 보는 3가지 적용 시나리오

예시 1: Hook으로 품질 게이트 강제하기

예시 2: Skills로 PR 리뷰 절차 표준화하기

예시 3: MCP로 Jira-코드-GitHub를 하나의 흐름으로

장단점 분석

장점

단점 및 주의사항

실무에서 가장 흔한 실수

마치며

참고 자료

4개 레이어가 각각 해결하는 문제

전체 구조 한눈에 보기

CLAUDE.md — 팀의 코딩 헌법

Skills — /커맨드 하나로 실행되는 표준 절차

Hooks — Claude의 판단을 우회하는 강제 실행

MCP — 외부 시스템 연동의 표준 인터페이스

코드로 보는 3가지 적용 시나리오

예시 1: Hook으로 품질 게이트 강제하기

예시 2: Skills로 PR 리뷰 절차 표준화하기

예시 3: MCP로 Jira-코드-GitHub를 하나의 흐름으로

장단점 분석

장점

단점 및 주의사항

실무에서 가장 흔한 실수

마치며

참고 자료

Skills — `/커맨드` 하나로 실행되는 표준 절차

Skills — `/커맨드` 하나로 실행되는 표준 절차