AI 튜토리얼

프로젝트 규칙, 에이전트, 훅, MCP 및 CI로 Claude Code 마스터하기

Claude Code 설치, 저장소 스타터 키트 적용, 프로젝트 컨텍스트 관리, 안정적인 워크플로 구축, 권한 구성, 스킬·서브에이전트·훅·MCP·헤드리스 모드·병렬 워크트리 사용법을 알아보세요.

2026년 10월 1일약 18분 소요

프로젝트 규칙, 에이전트, 훅, MCP 및 CI로 Claude Code 마스터하기

Claude Code PRO 과정에서 제공하는 내용

Claude Code PRO는 Claude Code를 위한 러시아어 실습 과정이자 구성 키트입니다. 설치와 프롬프트 작성부터 팀 전체 구성, 재사용 가능한 자동화, 외부 연동, CI 워크플로까지 단계적으로 학습합니다.

저장소에는 12개의 학습 모듈, 8개의 실습 과제, 프롬프트 라이브러리, 플러그인 예제, GitHub Actions 워크플로, 치트 시트, FAQ, 바로 설치할 수 있는 스타터 키트가 포함되어 있습니다. 스타터 키트에는 8개의 스킬, 5개의 서브에이전트, 4개의 훅, 규칙, 상태 표시줄, 출력 스타일이 포함됩니다.

이 튜토리얼은 저장소의 주요 워크플로를 요약하여 기존 프로젝트에서 해당 구성을 바로 사용할 수 있도록 안내합니다. 원래 과정은 러시아어로 작성되어 있지만, 아래 단계는 영어로 설명되어 있습니다.

Claude Code의 작동 방식 이해하기

Claude Code는 일반적인 자동 완성 도구가 아니라 에이전트입니다. 목표가 주어지면 파일을 확인하고, 저장소를 검색하고, 코드를 수정하고, 명령을 실행하고, 결과를 점검할 수 있습니다. 일반적인 작업 흐름은 다음과 같습니다.

프로젝트 지침, 파일, 검색 결과, 명령 출력에서 컨텍스트를 수집합니다.
필요한 변경 사항을 계획합니다.
파일을 수정하거나 도구를 호출합니다.
테스트, 린터, 빌드 또는 기타 검사를 실행합니다.
검사가 통과하거나 추가 입력이 필요할 때까지 반복합니다.

사용자가 해야 할 가장 중요한 일은 명확한 목표를 제시하고, Claude가 관련 컨텍스트를 확인하도록 안내하며, 제약 조건을 명시하고, 성공 여부를 검증할 방법을 정의하는 것입니다.

유용한 프롬프트 공식은 다음과 같습니다. 목표 + 확인할 위치 + 제약 조건 + 검증 방법

Claude Code와 스타터 키트 설치하기

1단계: Claude Code 설치

macOS, Linux 또는 Windows Subsystem for Linux에서는 공식 설치 스크립트를 사용합니다.

curl -fsSL https://claude.ai/install.sh | bash

README에는 npm 설치 방법도 나와 있습니다.

npm install -g @anthropic-ai/claude-code

2단계: 과정 저장소 복제

git clone https://github.com/justxor/claude-code-pro-course.git

3단계: 프로젝트에 스타터 키트 설치

포함된 설치 프로그램을 실행하고 대상 프로젝트의 경로를 전달합니다.

bash claude-code-pro-course/install.sh ~/path/to/my-project

이렇게 하면 저장소의 재사용 가능한 Claude Code 구성을 프로젝트에서 사용할 수 있습니다. 키트는 여러 구성 요소를 설치하므로, 버전 관리에 커밋하기 전에 생성된 변경 사항을 확인하세요.

4단계: Claude Code 시작

cd ~/path/to/my-project
claude

세션 안에서 현재 컨텍스트를 확인하고 스타터 키트의 온보딩 스킬을 실행합니다.

/context
/onboard

/context는 컨텍스트 창을 얼마나 사용하고 있는지 보여 줍니다. /onboard는 설치된 스킬을 사용해 프로젝트 개요를 제공합니다.

Claude Code 구성 정리하기

이 과정에서는 구성을 사용자, 프로젝트, 로컬 범위로 나눕니다.

사용자 구성: 개인 지침, 설정, 스킬, 에이전트, 출력 스타일이 포함된 ~/.claude/ 아래의 파일입니다.
프로젝트 구성: CLAUDE.md, .claude/rules/, .claude/settings.json, 프로젝트 스킬, 프로젝트 에이전트, .mcp.json과 같은 공유 파일입니다.
로컬 구성: CLAUDE.local.md 및 .claude/settings.local.json과 같은 컴퓨터별 파일입니다. 팀 구성으로 공유해서는 안 됩니다.
플러그인: 여러 저장소에 배포할 수 있는 스킬, 에이전트, 훅, MCP 구성의 패키지 모음입니다.

적절한 구성 메커니즘 선택하기

프로젝트 지식과 코딩 규칙에는 CLAUDE.md 또는 .claude/rules/를 사용합니다.
권한 설정을 사용해 안전한 명령을 허용하고, 민감한 작업에는 확인을 요청하며, 위험한 접근은 차단합니다.
재사용 가능한 절차나 프롬프트에는 스킬을 사용합니다.
전문성이 필요하거나 격리된 컨텍스트 창이 필요한 작업에는 서브에이전트를 사용합니다.
특정 작업이 일관되게 실행되어야 할 때는 훅을 사용합니다.
GitHub, 브라우저, 데이터베이스와 같은 외부 시스템을 연결하려면 MCP를 사용합니다.
다른 저장소나 팀원에게 완전한 구성을 배포하려면 플러그인을 사용합니다.
무인 실행에는 claude -p, GitHub Actions 또는 Agent SDK를 사용합니다.

유용한 CLAUDE.md 작성하기

CLAUDE.md는 프로젝트의 기억 역할을 합니다. Claude Code는 /init으로 초기 버전을 만들 수 있으며, /memory를 통해 메모리를 편집할 수 있습니다. 이 파일은 짧고 구체적으로 유지하세요. 명령어, 아키텍처 경계, 코딩 규칙, 명시적인 제한 사항을 포함하면 됩니다.

다음은 과정의 예제를 바탕으로 수정한 예시입니다.

# 프로젝트: Next.js 및 PostgreSQL 스토어

## 명령어
- npm run dev — 개발 환경 시작
- npm test — Vitest 테스트 실행
- npm run lint — 린터 실행
- npm run db:migrate — 확인 필요

## 아키텍처
- src/app — 라우트
- src/lib — 비즈니스 로직
- src/db — 데이터베이스 접근
- 데이터베이스 작업은 반드시 src/db를 통해야 함

## 규칙
- 엄격한 TypeScript를 사용하고 any를 피할 것
- 새 코드에 테스트를 추가할 것
- 수정하기 전에 실패하는 테스트로 버그를 재현할 것
- 명시적으로 요청하지 않는 한 src/legacy를 수정하지 말 것
- 완료 전에 npm test 및 npm run lint를 실행할 것

CLAUDE.md를 긴 핸드북처럼 만들지 마세요. 자세한 지침이나 조건부 지침은 .claude/rules/ 또는 재사용 가능한 스킬에 작성하여 필수 지침이 묻히지 않도록 하세요.

핵심 개발 워크플로 사용

이 저장소는 탐색 → 계획 → 코딩 → 검증 → 커밋 순서를 권장합니다. 사소한 영역을 넘어서는 작업이라면 Claude에게 즉시 편집을 요청하지 말고 먼저 계획 모드에서 시작하세요.

계획 모드가 활성화될 때까지 Shift+Tab을 누르세요.
변경하지 말고 관련 코드를 검사하도록 Claude에게 요청하세요.
제안된 파일, 구현 단계, 위험 요소, 확인 방법을 검토하세요.
필요하면 계획을 수정하세요.
계획이 적절하다고 판단한 후에만 구현을 허용하세요.
테스트, 린팅, 타입 검사 또는 스크린샷을 요구하세요.
커밋이나 풀 리퀘스트를 요청하기 전에 diff를 검사하세요.

좋은 탐색 프롬프트는 다음과 같습니다.

계획 모드. 저장소를 조사하고 아키텍처,
진입점, /api/orders의 데이터 흐름, 테스트 위치,
테스트 실행 방법을 설명하세요. 아무것도 변경하지 마세요.
마지막에는 새 기여자가 실수하기 쉬운 지점 다섯 곳을 제시하세요.

검증 가능한 프롬프트 작성

“버그를 수정해”라고 말하는 대신 실패 상황과 예상 검증 방법을 설명하세요.

이메일이 비어 있으면 signup()이 TypeError로 실패합니다.
실패하는 테스트로 문제를 재현하고, 합리적으로 가장 작은 변경으로
수정한 다음 npm test를 실행하세요.

테스트 주도 기능 작업의 경우:

기능: 5000 이상인 주문에 10% 할인을 적용합니다.
먼저 4999, 5000, 0, 음수 값에 대한 테스트를 작성하세요.
새 테스트가 실패하는지 확인한 다음 해당 테스트를 변경하지 않고
기능을 구현하세요.

안전한 리팩터링의 경우:

@src/services/user.ts를 책임별 모듈로 나누세요.
동작이나 공개 API는 변경하지 마세요. 각 단계 후에 tests와 tsc를
실행하세요. 커버리지가 충분하지 않다면 먼저 특성화 테스트를 추가하세요.

컨텍스트를 의도적으로 관리

컨텍스트 창에는 시스템 지침, 프로젝트 규칙, 스킬 및 에이전트 설명, 대화 기록, 파일, 명령 출력이 포함됩니다. 관련 없는 자료가 쌓이면 응답의 정확도가 떨어질 수 있습니다.

/context를 사용하여 컨텍스트 사용량을 확인하세요.
관련 없는 작업을 시작하기 전에 /clear를 사용하세요.
중요한 결정을 보존하면서 긴 세션을 요약하려면 /compact를 사용하세요.
@src/api/client.ts와 같은 구문으로 파일을 직접 추가하세요.
!git status와 같은 구문으로 명령을 실행하고 그 출력을 컨텍스트에 추가하세요.
장시간 작업의 경우 Claude에게 PLAN.md 또는 NOTES.md를 관리하도록 요청하세요.
대규모 조사는 서브에이전트에 위임하여 요약만 기본 세션으로 반환되게 하세요.

로그를 일회성 Claude Code 호출에 파이프로 전달할 수도 있습니다.

cat error.log | claude

안전한 권한 구성

권한 규칙은 deny → ask → allow 순서로 평가됩니다. 거부 규칙은 허용 규칙보다 우선합니다. 이 과정에서는 권한 확인을 비활성화하는 대신 안전한 명령을 허용 목록에 추가할 것을 권장합니다.

팀 설정은 .claude/settings.json에 규칙을 배치할 수 있습니다.

{
  "permissions": {
    "allow": [
      "Bash(npm run test:*)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff:*)"
    ],
    "ask": [
      "Bash(git push:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(curl:*)"
    ]
  }
}

이 예시는 일상적인 테스트와 검사를 허용하고, 푸시할 때는 확인을 요청하며, 시크릿과 선택한 위험한 명령에 대한 접근을 차단합니다.

CLAUDE.md에 시크릿을 넣지 마세요.
푸시, 배포, 마이그레이션에는 확인을 요구하세요.
프로덕션 접근 권한이 없는 컨테이너 또는 샌드박스에서 자율 작업을 실행하세요.
웹사이트와 MCP 시스템이 반환하는 콘텐츠는 신뢰할 수 있는 지침이 아니라 데이터로 취급하세요.
변경 사항을 커밋하기 전에 git diff를 검토하세요.

반복 작업을 스킬로 전환

어떤 절차를 여러 번 반복한다면 스킬로 전환하세요. 릴리스 노트 작성, 풀 리퀘스트 검토, 프로젝트 온보딩과 같은 워크플로에는 스킬이 적합합니다.

이 과정에서는 프로젝트 스킬을 .claude/skills/에 저장합니다. 스킬에는 이름, Claude가 사용 시점을 판단하는 데 도움이 되는 설명, 그리고 일련의 지침을 포함할 수 있습니다. 절차의 범위를 좁게 유지하고 예상 출력을 정의하세요.

예를 들어 릴리스 노트 스킬은 Claude에게 최신 Git 태그를 찾고, 해당 태그 이후의 커밋을 수집하며, 변경 사항을 범주별로 그룹화하도록 지시할 수 있습니다. 스타터 키트에는 설치 후 살펴볼 수 있는 재사용 가능한 스킬이 이미 제공됩니다.

격리된 작업 또는 전문 작업에 서브에이전트 사용

서브에이전트는 자체 컨텍스트 창을 받고 결과를 기본 세션으로 반환합니다. 복잡한 저장소 조사, 테스트 실행, 보안 분석 또는 독립적인 검토에 유용합니다.

저장소의 검토자 예시는 .claude/agents/reviewer.md에 저장되어 있으며 에이전트에 읽기, 검색, 셸 도구를 제공합니다. 이 에이전트의 역할은 git diff에서 버그, 엣지 케이스, 시크릿 유출, 프로젝트 스타일 위반을 검사하는 것입니다.

실용적인 작성자-검토자 패턴은 다음과 같습니다.

한 Claude 세션을 사용하여 변경 사항을 구현합니다.
새 세션이나 서브에이전트를 열어 diff를 검토합니다.
검토 결과를 구현 세션으로 전달합니다.
문제를 수정하고 검증을 다시 실행합니다.

깨끗한 컨텍스트를 사용하면 긴 구현 세션 후에는 놓치기 쉬운 문제를 검토자가 발견하는 데 도움이 됩니다.

훅으로 보장 사항 강제

프로젝트 지침은 가이드 역할을 하며, 훅은 작업을 자동으로 실행하거나 차단할 수 있습니다. 이 과정에서 설명하는 유용한 훅 이벤트는 다음과 같습니다.

브랜치 또는 작업 정보를 로드하는 SessionStart.
프롬프트에 컨텍스트를 추가하는 UserPromptSubmit.
위험한 명령이나 보호된 파일의 편집을 차단하는 PreToolUse.
포맷팅, 린팅 또는 대상 테스트를 실행하는 PostToolUse.
Claude의 입력이 필요할 때 데스크톱 알림을 보내는 Notification.
최종 검증 단계를 실행하는 Stop.
컨텍스트 압축 전에 중요한 정보를 저장하는 PreCompact.

다음 예시는 파일을 편집하거나 작성한 후 Prettier를 실행합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

중요한 보호 기능에는 작성된 지침에만 의존하지 말고 permissions.deny와 PreToolUse 훅을 함께 사용하세요.

MCP로 외부 시스템 연결하기

Claude에 로컬 저장소 외부의 도구나 데이터가 필요할 때 MCP를 사용하세요. 이 과정에서는 GitHub, 브라우저, 데이터베이스 및 사용자 지정 MCP 서버를 활용한 통합을 다룹니다.

브라우저 MCP는 시각적 작업에 특히 유용합니다. Claude가 UI를 구현하고, 스크린샷을 캡처하고, 참조 이미지와 비교한 다음 차이점을 반영해 반복 개선할 수 있습니다. 외부 콘텐츠에는 신뢰할 수 없는 텍스트가 포함될 수 있으므로 MCP 접근 권한을 신중하게 검토하고 프롬프트 인젝션에 주의하세요.

헤드리스 모드로 작업 자동화하기

-p 옵션은 대화형 세션 없이 프롬프트를 실행하므로 스크립트와 CI에 적합합니다. 예를 들어 빌드 실패 로그를 전달하고 구조화된 출력을 요청할 수 있습니다.

claude -p "Find the cause of the build failure" \
  --output-format json < build.log

푸시하기 전에 현재 변경 사항을 검토하세요.

git diff main | claude -p \
  "Review this diff for bugs, edge cases, and security issues"

제한된 자동화 작업을 위해 사용할 도구와 턴 수를 제한하세요.

claude -p "Update CHANGELOG from recent commits" \
  --allowedTools "Read,Edit,Bash(git log:*)" \
  --max-turns 10

저장소에는 이슈와 풀 리퀘스트에서 @claude를 호출하고 자동화된 검토를 수행하는 GitHub Actions 예시도 포함되어 있습니다.

Git 워크트리로 여러 작업 실행하기

병렬 작업을 진행하려면 각 작업에 별도의 워크트리와 브랜치를 생성하세요. 그러면 각 Claude 세션이 서로 다른 디렉터리에서 작동하므로 여러 에이전트가 동일한 작업 트리를 동시에 편집하는 일을 방지할 수 있습니다.

git worktree add ../app-auth -b feature/auth
cd ../app-auth && claude

청구 기능, 버그 수정 또는 기타 독립적인 작업에도 이 패턴을 반복할 수 있습니다. 일반적인 Git 워크플로를 사용해 각 브랜치를 병합하거나 검토하세요.

유용한 세션 제어

Esc는 세션 컨텍스트를 삭제하지 않고 Claude를 중단합니다.
Esc Esc 또는 /rewind는 이전 코드 및 대화 상태로 돌아갑니다.
Shift+Tab은 일반 모드, 편집 자동 승인 모드, Plan 모드를 순환합니다.
/model은 활성 모델을 변경합니다.
/permissions, /hooks, /agents, /mcp는 관련 구성 워크플로를 엽니다.
claude --continue는 가장 최근 세션을 재개합니다.
claude --resume은 이전 세션을 선택할 수 있게 합니다.

고급 팁과 일반적인 실수

계획부터 시작하세요: 여러 파일에 걸치거나 상당한 위험이 있는 변경에는 Plan 모드를 사용하세요.
항상 피드백을 제공하세요: 테스트, 타입 검사, 린터, 빌드, 스크린샷 또는 정확한 예상 출력이 있으면 에이전트가 스스로 수정할 수 있습니다.
세션의 초점을 유지하세요: 하루 종일 하나의 세션을 유지하기보다 관련 없는 작업 사이에서는 컨텍스트를 초기화하세요.
실패한 접근 방식은 되돌리세요: 수정에 반복해서 실패하면 잘못된 컨텍스트를 계속 쌓기보다 /rewind를 사용하고 작업을 다시 설명하세요.
변경 사항을 무작정 수락하지 마세요: 직접 변경 사항을 검사하거나 독립적인 검토 서브에이전트에게 요청하세요.
제한 없는 권한을 피하세요: 안전 검사를 우회하는 대신 허용 목록과 샌드박스를 사용하세요.
반복 절차를 자동화하세요: 반복 작업은 스킬로, 반드시 적용해야 하는 동작은 훅으로 전환하세요.
진행 상황을 외부에 보존하세요: 장시간 작업 중에는 계획 또는 메모 파일을 유지해 /clear 이후에도 작업을 이어갈 수 있게 하세요.

전체 학습 경로 따라가기

저장소의 모듈은 설치, 프롬프트 작성, 프로젝트 메모리, 설정, 전문적인 워크플로, 스킬, 서브에이전트, 훅, MCP, 플러그인, 헤드리스 CI 및 고급 기법 순으로 진행됩니다. 8개의 실습은 온보딩, 권한, TDD, 스킬 생성, 서브에이전트, 훅, MCP 및 자동화를 다룹니다.

빠른 시작 설치와 기본 컨텍스트 명령부터 시작하세요. 다음으로 간결한 CLAUDE.md와 안전한 권한 정책을 만드세요. 그런 다음 MCP, 플러그인 및 비대화형 CI 실행으로 넘어가기 전에 계획 수립, TDD, 스킬, 서브에이전트 및 훅을 차례로 학습하세요.

결론

Claude Code는 채팅 인터페이스가 아니라 구성 가능한 개발 에이전트로 활용할 때 가장 효과적입니다. 집중된 컨텍스트를 제공하고, 계획에 합의하고, 객관적인 검증을 적용하며, 권한과 훅으로 중요한 경계를 강제하세요. Claude Code PRO 저장소는 개인 개발부터 팀 자동화까지 이러한 워크플로를 적용할 수 있도록 체계적인 과정, 실습 및 재사용 가능한 템플릿을 제공합니다.