Claude Code 아키텍처와 내부 동작 원리 및 실전 활용법

개요

AI 코딩 도구는 단순한 코드 생성부터 파일 수정, 명령어 실행, 오류 해결까지 다양한 개발 작업을 수행할 수 있습니다.

하지만 프로젝트가 복잡해지면 기존 규칙을 따르지 않거나, 불필요하게 복잡한 코드를 작성하고, 수정한 코드에서 예상하지 못한 오류가 발생하기도 합니다.

이러한 문제를 줄이려면 프롬프트 작성뿐만 아니라 AI 코딩 에이전트가 프로젝트를 이해하고 작업을 수행하는 구조를 알아야 합니다.

Claude Code는 프로젝트 파일을 읽고, 코드를 수정하며, 명령어 실행과 결과 검증까지 수행할 수 있는 AI 코딩 에이전트입니다.

이번 글에서는 Claude Code의 기능을 단순히 나열하기보다 다음 질문을 중심으로 살펴보겠습니다.

• Claude Code는 어떤 방식으로 작업을 수행할까?
• 프로젝트의 구조와 규칙은 어떻게 전달할까?
• Context가 길어지면 어떤 문제가 발생할까?
• Rules, Skills, Subagents는 각각 언제 사용해야 할까?
• AI가 코드를 수정할 때 권한과 안전성은 어떻게 관리할까?
• 복잡한 작업을 여러 에이전트에게 나누어 맡길 수 있을까?
• 작성한 코드가 실제로 동작하는지는 어떻게 검증할까?

Claude Code란 무엇일까?

Claude Code는 Anthropic에서 제공하는 에이전트 기반 개발 도구입니다.

일반적인 채팅형 LLM이 사용자가 전달한 코드에 대해 설명하거나 수정안을 제시하는 데 주로 사용된다면, Claude Code는 접근 권한이 있는 개발 환경에서 파일을 탐색하고 직접 작업을 수행할 수 있습니다.

예를 들어 다음과 같이 요청했다고 가정해 보겠습니다.

로그인 기능에서 발생하는 오류를 찾아 수정해 줘.

Claude Code는 관련 파일을 검색하고, 오류의 원인을 분석한 뒤 코드를 수정하고 검증할 수 있습니다.

사용자 요청
↓
관련 파일 탐색 및 분석
↓
문제 원인 파악
↓
코드 수정
↓
테스트 및 검증
↓
결과 보고

물론 모든 작업이 이 순서대로 진행되는 것은 아닙니다.

Claude는 작업 상황에 따라 필요한 도구를 선택하고 실행 결과를 확인하며 다음 행동을 결정합니다.

Agent Loop: Claude Code의 핵심 동작 원리

이러한 반복적인 작업 방식을 Agent Loop라고 합니다.

Agent Loop는 AI가 한 번의 답변으로 작업을 끝내는 것이 아니라, 목표를 달성할 때까지 판단 → 도구 실행 → 결과 확인을 반복하는 과정입니다.

사용자 요청
    ↓
Claude의 판단
    ↓
도구 실행
    ↓
실행 결과 확인
    ↓
추가 작업이 필요한가?
    ├── Yes → 다시 판단
    └── No  → 결과 보고

예를 들어 TypeScript 오류를 수정한다면 파일을 읽고 코드를 변경한 다음, 타입 검사를 실행할 수 있습니다.

검사에서 새로운 오류가 발견되면 다시 코드를 수정하고 검사를 반복합니다.

중요한 점은 Claude가 코드를 생성하는 것뿐 아니라 도구의 실행 결과를 다음 판단에 활용한다는 것입니다.

Session과 Context 이해하기

Claude Code가 작업을 수행할 때 중요한 두 가지 개념이 Session과 Context입니다.

• Session: 사용자와 Claude가 작업을 이어가는 대화 단위
• Context: Claude가 현재 요청을 이해하고 판단하는 데 참고하는 정보

Session은 작업의 대화 기록에 가깝고, Context는 그중 현재 모델의 판단에 제공되는 정보라고 이해하면 쉽습니다.

Context에는 무엇이 포함될까?

Context에는 다음과 같은 정보가 포함될 수 있습니다.

• 사용자의 요청과 이전 대화
• 시스템 지침과 프로젝트 지침
• CLAUDE.md 및 관련 Rules
• Claude가 읽은 소스 코드
• 도구의 정의와 실행 결과
• 작업에 필요한 Skills와 현재 진행 상황

위 이미지는 Claude Code의 Context 사용 현황입니다.

전체 Context Window 중 약 66%가 사용되고 있으며, 각 항목이 차지하는 토큰 수와 비율을 확인할 수 있습니다.

• Messages: 사용자와 Claude의 대화, 도구 실행 결과 등 작업 과정에서 쌓인 정보
• System tools / System prompt: Claude가 사용할 도구의 정의와 기본 지침
• Memory files / Skills: 프로젝트 지침 파일과 작업에 필요한 Skills
• Autocompact buffer: Context가 가득 차기 전에 자동 압축을 수행하기 위해 확보한 공간
• Free space: 추가 대화나 작업에 사용할 수 있는 여유 공간

이처럼 Context는 대화 기록뿐 아니라 다양한 지침과 도구 정보로 구성되며, 작업이 진행될수록 사용량이 증가합니다.

사용자 요청
    │
    ▼
┌────────────────────────┐
│        Context         │
│                        │
│  이전 대화               │
│  프로젝트 지침            │
│  읽은 소스 코드           │
│  도구 실행 결과           │
│  관련 Skills            │
└────────────────────────┘
    │
    ▼
Claude의 판단과 작업 수행

예를 들어 같은 React 컴포넌트를 구현하더라도 프로젝트가 Next.js와 Tailwind CSS를 사용하는지,

React와 styled-components를 사용하는지에 따라 적절한 구현 방식이 달라집니다.

Claude Code는 프로젝트 파일과 설정, 지침 등을 Context로 활용해 이러한 차이를 파악합니다.

Context가 길어지면 어떻게 될까?

Claude가 한 번에 참고할 수 있는 정보의 양에는 제한이 있습니다. 이를 Context Window라고 합니다.

프로젝트 분석, 파일 읽기, 코드 수정, 테스트 실행이 반복되면 Context에 많은 정보가 쌓입니다.

Context가 길다고 반드시 품질이 떨어지는 것은 아니지만, 현재 작업과 무관한 정보가 많아지면 중요한 내용을 활용하기 어려워질 수 있습니다.

Claude Code는 Context를 관리하기 위한 명령어를 제공합니다.

/compact은 지금까지의 내용을 요약해 필요한 정보를 남기고 Context 사용량을 줄입니다.

압축 전
├── 이전 대화
├── 코드 분석 결과
├── 테스트 로그
├── 수정 과정
└── 현재 작업
       ↓
압축 후 (/compact)
├── 핵심 프로젝트 정보
├── 중요한 결정 사항
└── 현재 작업 상태

Claude Code는 필요할 때 자동으로 압축하기도 합니다.

다만 모든 세부 정보가 원본 그대로 유지되는 것은 아니므로, 중요한 설계 결정과 규칙은 프로젝트 문서에 남기는 것이 좋습니다.

/clear는 현재 대화를 정리하고 새로운 작업을 시작할 때 유용합니다. 예를 들어 로그인 기능 개발을 마친 뒤 관련 없는 검색 기능을 구현한다면 불필요한 이전 대화를 이어갈 필요가 없을 수 있습니다.

/resume은 이전 Session을 다시 열어 작업을 이어갈 때 사용합니다.

핵심은 Session을 무조건 오래 유지하기보다 작업의 연관성에 따라 Context를 관리하는 것입니다.

CLAUDE.md로 프로젝트 지침 전달하기

Claude Code가 프로젝트의 규칙을 일관되게 따르도록 하려면 CLAUDE.md를 활용할 수 있습니다.

CLAUDE.md는 Claude가 작업할 때 참고하는 지침 파일로, 기술 스택, 실행 명령어, 코딩 규칙, 아키텍처 제약 등을 작성합니다.

예를 들어 다음과 같이 구성할 수 있습니다.

# Project

Next.js와 TypeScript로 개발한 웹 애플리케이션입니다.

## Commands

- npm run dev: 개발 서버 실행
- npm run build: 프로덕션 빌드
- npm run lint: ESLint 검사
- npm run test: 테스트 실행

## Conventions

- 새로운 파일명은 kebab-case를 사용합니다.
- TypeScript의 any 사용을 피합니다.
- 기존 디렉터리 구조를 우선 따릅니다.
- 불필요한 추상화나 방어 로직을 추가하지 않습니다.

## Validation

- 변경 후 관련 테스트를 실행합니다.
- 작업 완료 전에 타입 검사를 수행합니다.

이렇게 작성해 두면 매번 동일한 규칙을 프롬프트로 전달할 필요가 줄어듭니다.

/init으로 초안 생성하기

프로젝트에서 처음 Claude Code를 사용할 때는 /init으로 코드베이스를 분석하고 CLAUDE.md 초안을 만들 수 있습니다.

/init

자동 생성된 내용이 항상 정확한 것은 아니므로 실제 프로젝트와 비교하여 불필요한 항목을 제거하고 필요한 규칙을 보완하는 것이 좋습니다.

어떤 내용을 작성하는 것이 좋을까?

CLAUDE.md에는 프로젝트 전체에서 반복적으로 필요한 내용을 우선 작성하는 것이 좋습니다.

• 주요 기술 스택과 개발·검증 명령어
• 프로젝트 전반에 적용할 코딩 규칙
• 반드시 지켜야 하는 아키텍처 제약
• Claude가 반복해서 실수하는 부분

특정 기능의 상세 설계나 일회성 요구사항까지 모두 넣으면 지침이 지나치게 길어질 수 있습니다.

CLAUDE.md는 프로젝트의 모든 정보를 담는 문서가 아니라, Claude가 반복해서 참고해야 하는 핵심 지침입니다.

Auto Memory와는 무엇이 다를까?

Claude Code의 Auto Memory는 작업 중 발견한 유용한 정보나 패턴을 자동으로 기록하고 이후 Session에서 참고할 수 있는 기능입니다.

Auto Memory는 편리하지만 중요한 팀 규칙을 여기에만 의존하는 것은 적절하지 않습니다.

반드시 지켜야 하는 규칙은 CLAUDE.md 또는 Rules에 명시적으로 작성하는 것이 좋습니다.

Rules와 Skills로 지침 구분하기

프로젝트가 커지면 하나의 CLAUDE.md에 모든 지침을 넣기보다 목적에 따라 분리하는 것이 관리하기 편리합니다.

Claude Code에서는 Rules와 Skills를 활용할 수 있습니다.

• Rules: 작업할 때 지켜야 하는 규칙과 제약
• Skills: 특정 작업을 수행하는 방법과 절차

Rules: 영역별 규칙 관리

Rules는 .claude/rules/ 디렉터리에서 관리할 수 있습니다.

.claude/
├── rules/
│   ├── react.md
│   ├── testing.md
│   └── database.md
└── skills/

예를 들어 React 컴포넌트에서만 적용할 규칙이라면 paths를 지정할 수 있습니다.

---
paths:
  - 'src/components/**/*.tsx'
---

# React Component Rules

- 접근성을 고려합니다.
- 불필요한 useEffect 사용을 피합니다.
- 파생 가능한 값은 별도의 state로 저장하지 않습니다.

이처럼 경로별 규칙을 분리하면 관련 작업에서 필요한 지침을 참고하도록 구성할 수 있습니다.

프로젝트 전반의 공통 규칙은 CLAUDE.md에, 특정 영역의 규칙은 Rules에 작성하는 방식이 적절합니다.

Skills: 작업 절차 재사용

Skills는 코드 리뷰, 테스트 작성, 배포 점검처럼 반복되는 작업의 수행 방법을 정의하는 기능입니다.

Custom Skill은 .claude/skills/ 아래에 디렉터리를 만들고 SKILL.md를 작성하여 정의할 수 있습니다.

.claude/
└── skills/
    └── review-code/
        └── SKILL.md

---
name: review-code
description: 변경된 코드의 품질과 잠재적인 문제를 검토합니다.
---

# Code Review

변경된 코드를 다음 순서로 검토합니다.

1. 변경 목적을 파악합니다.
2. 기존 코드와의 일관성을 확인합니다.
3. 버그나 예외 상황을 확인합니다.
4. 불필요한 복잡성이 있는지 검토합니다.
5. 테스트가 필요한 부분을 확인합니다.

문제가 있다면 중요도 순서대로 설명합니다.

이 Skill은 적절한 상황에서 Claude가 활용하거나 /review-code로 직접 호출할 수 있습니다.

Skill에는 지침 외에도 스크립트와 참고 자료를 함께 포함할 수 있습니다.

외부 Skills 활용하기

공개된 Skills를 설치하여 사용할 수도 있습니다.

예를 들어 Vercel의 React 모범 사례 Skill은 다음과 같이 설치할 수 있습니다.

npx skills add https://github.com/vercel-labs/agent-skills --skill vercel-react-best-practices

이러한 Skill은 React와 Next.js 개발에서 성능 및 구현 관련 권장 사항을 참고하는 데 도움이 됩니다.

다만 외부 Skill을 설치하기 전에는 지침과 실행 스크립트를 검토해야 합니다.

또한 권장 사항을 무조건 적용하기보다 현재 프로젝트의 요구사항에 적합한지 판단하는 것이 중요합니다.

Plan Mode로 구현 전에 설계하기

Claude Code는 요청을 받아 바로 구현할 수도 있지만, 변경 범위가 넓은 작업에서는 먼저 계획을 세우는 것이 유리합니다.

예를 들어 다음과 같은 요청을 생각해 보겠습니다.

기존 Redux 상태 관리를 Zustand로 변경해 줘.

이 작업에는 상태 구조 분석, 관련 컴포넌트 파악, 새로운 Store 설계, 기존 코드 변경, 회귀 검증 등이 필요할 수 있습니다.

Plan Mode란?

Plan Mode는 코드를 바로 수정하기보다 코드베이스를 분석하고 구현 계획을 검토하는 데 집중하는 모드입니다.

요구사항 확인
↓
코드베이스 탐색
↓
영향 범위 분석
↓
구현 계획 작성
↓
사용자 검토
↓
구현 진행

특히 프로젝트 구조 변경, 인증 설계, 상태 관리 교체, 대규모 리팩터링처럼 여러 파일에 영향을 주는 작업에 적합합니다.

구현 전에 질문하도록 요청하기

요구사항이 불명확하다면 Claude에게 먼저 질문하도록 요청할 수도 있습니다.

구현을 시작하기 전에 불명확한 요구사항을 질문해 줘. 기존 코드 구조를 확인하고 가능한 구현 방법을 비교한 뒤 계획을 제안해 줘.

이렇게 하면 Claude가 사용자의 의도를 임의로 추측해 구현하는 문제를 줄일 수 있습니다.

중요한 것은 가장 복잡한 구조를 만드는 것이 아니라 현재 요구사항에 적절한 범위와 구현 방식을 선택하는 것입니다.

Permissions와 Sandboxing으로 안전하게 실행하기

Claude Code는 파일 수정과 터미널 명령 실행이 가능하기 때문에 어떤 작업을 허용하고, 어디까지 접근할 수 있는지 관리해야 합니다.

Permissions: 작업 권한 관리

Permissions는 도구와 명령어의 실행 권한을 제어하는 기능입니다.

대표적인 권한 모드는 다음과 같습니다.

모드 이름과 지원 여부는 Claude Code 버전 및 실행 환경에 따라 달라질 수 있습니다.

특정 명령어에 대한 허용 또는 차단 규칙도 설정할 수 있습니다.

{
  "permissions": {
    "allow": ["Bash(npm run lint)", "Bash(npm run test)", "Bash(npm run build)"],
    "deny": ["Bash(rm -rf *)"]
  }
}

위 코드는 자주 사용하는 검증 명령을 허용하는 예시입니다.

실제 권한 규칙의 적용 범위는 패턴 매칭 방식에 따라 달라질 수 있습니다.

다만 위험한 명령을 일부 차단했다고 해서 모든 우회 경로가 차단되는 것은 아닙니다.

Sandboxing: 실행 환경 격리

Permissions가 어떤 작업을 실행하도록 허용할지 제어한다면, Sandboxing은 허용된 작업이 실행되는 환경에서 파일 시스템과 네트워크에 접근할 수 있는 범위를 제한하는 기능입니다.

예를 들어 Claude가 터미널 명령어를 실행할 때, Sandbox를 사용하면 프로젝트 외부의 파일에 접근하거나 허용되지 않은 네트워크로 연결하는 작업을 제한할 수 있습니다.

Claude Code
     │
     ▼
┌─────────────────────────┐
│  Sandbox                │
│                         │
│  파일 시스템 접근 제한       │
│  네트워크 접근 제한         │
│  격리된 환경에서 명령 실행    │
└─────────────────────────┘
     │
     ▼
허용된 범위 내에서 작업 수행

예를 들어 프로젝트에서 npm run build를 실행하도록 허용했다고 가정해 보겠습니다.

Permissions는 해당 명령어의 실행을 허용할지 결정하지만, 명령어가 실행되는 과정에서 접근할 수 있는 파일이나 네트워크까지 모두 제한하는 것은 아닙니다.

반면 Sandboxing을 적용하면 명령어가 실행되더라도 허용된 범위 밖의 리소스에 접근하지 못하도록 제한할 수 있습니다.

따라서 외부 저장소의 코드를 분석하거나 신뢰하기 어려운 스크립트를 실행할 때 발생할 수 있는 위험을 줄이는 데 도움이 됩니다.

다만 Sandbox도 모든 보안 문제를 해결하지는 않습니다.

허용된 범위 안에서의 잘못된 파일 수정이나 민감한 정보 노출, 악의적인 지시 등의 위험은 여전히 존재할 수 있으므로 Permissions와 함께 적절한 접근 권한을 설정하는 것이 중요합니다.

settings.json과 settings.local.json

프로젝트 설정은 다음과 같이 관리할 수 있습니다.

프로젝트/
└── .claude/
    ├── settings.json
    └── settings.local.json

• settings.json: 프로젝트 구성원과 공유할 설정
• settings.local.json: 개인 개발 환경에만 적용할 설정

프로젝트 지침 역시 공통 지침인 CLAUDE.md와 개인용 CLAUDE.local.md로 구분할 수 있습니다.

설정 파일은 Claude Code의 동작과 권한을 제어하고, 지침 파일은 Claude가 작업할 때 참고할 규칙을 전달합니다.

Subagents로 작업과 Context 분리하기

프로젝트가 커지면 모든 조사와 분석을 메인 Claude의 Context에서 처리하는 것이 비효율적일 수 있습니다.

예를 들어 인증 기능을 분석하려면 API 라우트, 세션 관리, 미들웨어, 테스트 파일 등을 살펴봐야 합니다.

하지만 메인 Claude에게 필요한 것은 탐색 과정 전체보다 핵심 구조와 문제 원인, 수정 방향일 수 있습니다.

이때 Subagents를 활용할 수 있습니다.

Subagent란?

Subagent는 메인 Claude와 분리된 Context에서 특정 작업을 수행하는 보조 에이전트입니다.

출처: DailyDoseOfCode

위 이미지처럼 메인 Claude는 사용자 요청을 분석한 뒤, 필요한 작업을 여러 Subagent에게 나누어 맡길 수 있습니다.

각 Subagent는 독립된 Context에서 코드 리뷰, 디버깅, 데이터 분석, 웹 검색 등 특정 작업을 수행하고 결과를 메인 Claude에게 전달합니다.

메인 Claude는 전달받은 결과를 종합하여 다음 작업을 판단하거나 사용자에게 최종 결과를 제공합니다.

         사용자 요청
             │
             ▼
         Main Agent
             │
    ┌────────┴────────┐
    ▼                 ▼
Subagent A        Subagent B
 코드 리뷰             디버깅
    │                 │
    └────────┬────────┘
             ▼
   결과를 Main Agent에게 전달
             │
             ▼
   Main Agent가 결과 종합
             │
             ▼
    사용자에게 최종 결과 제공

이처럼 Subagent가 조사한 내용을 요약하여 전달하므로 메인 Context에 모든 탐색 기록이 쌓이는 것을 줄일 수 있습니다.

Explore Agent

Claude Code에는 코드베이스 탐색에 특화된 Explore Agent가 있습니다.

프로젝트의 파일 구조를 파악하거나 특정 기능이 여러 파일에 걸쳐 어떻게 구현되어 있는지 조사할 때 유용합니다.

예를 들어 다음과 같이 요청할 수 있습니다.

인증 관련 코드를 Explore 에이전트로 조사하고, 로그인부터 세션 검증까지의 흐름을 정리해 줘.

Explore Agent는 메인 Claude와 분리된 Context에서 관련 파일을 탐색하고 분석한 뒤, 조사 결과를 전달합니다.

이를 통해 메인 Context에 불필요한 탐색 기록이 쌓이는 것을 줄이면서 대규모 프로젝트의 구조와 기능 흐름을 효율적으로 파악할 수 있습니다.

Custom Subagents

Claude Code에서는 특정 역할을 수행하는 Custom Subagent를 직접 정의할 수도 있습니다.

예를 들어 코드 리뷰, 테스트 분석, 아키텍처 검토처럼 반복적으로 필요한 작업을 각각의 Subagent로 분리할 수 있습니다.

프로젝트 수준의 Custom Subagent는 .claude/agents/ 디렉터리에서 관리합니다.

.claude/
└── agents/
    ├── code-reviewer.md
    ├── test-analyzer.md
    └── architecture-reviewer.md

각 Subagent에는 역할별 지침뿐 아니라 사용할 도구, 모델, 권한 등을 설정할 수 있습니다.

다만 모든 작업에 Subagent가 필요한 것은 아닙니다. 단순한 파일 수정에는 오히려 추가적인 실행 비용과 관리 과정이 발생할 수 있습니다.

따라서 탐색 범위가 넓거나 독립적으로 처리할 수 있는 작업을 분리할 때 활용하는 것이 적절합니다.

병렬 실행과 Worktrees

서로 독립적인 작업이라면 여러 Subagent가 병렬로 조사할 수도 있습니다.

             Main Agent
                 │
      ┌──────────┼──────────┐
      ▼          ▼          ▼
   Agent A    Agent B    Agent C
   인증 분석    테스트 분석   API 분석
      │          │          │
      └──────────┼──────────┘
                 ▼
              결과 통합

다만 같은 파일을 동시에 수정하면 충돌이 발생할 수 있습니다.

여러 에이전트가 코드를 병렬로 수정해야 한다면 Git Worktree로 작업 디렉터리를 분리할 수 있습니다.

프로젝트 저장소
├── main 작업 공간
├── feature-auth 작업 공간
│   └── Agent A
└── feature-search 작업 공간
    └── Agent B

Worktree는 작업 공간을 분리해 직접적인 파일 충돌을 줄여주지만, 변경 사항을 통합할 때 발생하는 Git 병합 충돌까지 해결해 주지는 않습니다.

따라서 병렬 작업을 시작하기 전에 작업 간 의존성과 파일 수정 범위를 확인하는 것이 중요합니다.

/batch로 대규모 작업 병렬 처리하기

/batch는 코드베이스 전반의 큰 변경 작업을 여러 독립적인 단위로 나누고 병렬로 진행하는 명령어입니다.

먼저 작업 계획을 제안하고, 사용자가 승인하면 각 작업을 별도의 Git Worktree에서 Subagent가 수행하도록 구성합니다.

예를 들어 아래와 같이 사용할 수 있습니다.

/batch src 디렉터리의 컴포넌트를 새로운 패턴으로 마이그레이션해 줘

Git 저장소가 필요하며, 서로 독립적인 대규모 변경에 적합합니다.

Hooks로 특정 이벤트 자동화하기

Hooks는 Claude Code에서 특정 이벤트가 발생했을 때 미리 정한 작업을 자동으로 실행하도록 구성하는 기능입니다.

예를 들어 Claude가 파일을 수정한 뒤 Prettier를 실행하거나, 위험한 명령어 실행을 차단하고, 사용자 승인이 필요할 때 알림을 보내도록 설정할 수 있습니다.

CLAUDE.md에 작성한 규칙은 Claude가 참고하는 지침이지만, Hooks는 특정 이벤트가 발생했을 때 설정된 작업을 직접 실행한다는 차이가 있습니다.

Claude가 파일 수정
↓
PostToolUse 이벤트 발생
↓
설정된 Hook 실행
↓
Prettier 자동 실행
↓
파일 포맷팅 완료

Hooks 설정 방법

Hooks는 Claude Code에서 /hooks 명령어로 등록된 설정을 확인하거나, settings.json에 직접 작성하여 구성할 수 있습니다.

설정 파일은 적용 범위에 따라 구분됩니다.

• ~/.claude/settings.json: 사용자 전체 프로젝트에 적용
• .claude/settings.json: 현재 프로젝트에 적용하며 팀과 공유 가능
• .claude/settings.local.json: 현재 프로젝트의 개인 설정에 적용

예를 들어 Claude가 파일을 수정할 때마다 Prettier를 실행하도록 설정해 보겠습니다.

먼저 프로젝트의 .claude/settings.json에 다음 내용을 추가합니다.

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

각 설정의 역할은 다음과 같습니다.

위 예시에서 jq는 Claude가 수정한 파일 경로를 추출하고, npx prettier --write는 해당 파일에 Prettier를 실행합니다.

따라서 프로젝트에 Prettier가 설치되어 있어야 하며, jq도 사용할 수 있어야 합니다. macOS에서는 brew install jq로 설치할 수 있습니다.

설정을 완료했다면 Claude Code에서 /hooks를 실행해 등록 여부를 확인하고, 실제 파일을 수정하도록 요청하여 포맷팅이 적용되는지 테스트할 수 있습니다.

이 예시는 Claude가 Edit 또는 Write 도구로 수정한 파일에 반응하며, 터미널 명령어 등 다른 방식으로 변경된 모든 파일까지 감지하는 것은 아닙니다.

주요 Hook 이벤트

Claude Code는 다양한 이벤트를 제공합니다.

Hooks는 주로 셸 명령어를 실행하지만, HTTP 요청이나 LLM 기반 판단 등 다른 실행 방식도 지원합니다.

다만 모든 Hook이 동일하게 동작하는 것은 아니며, 이벤트별로 실행 시점과 차단 가능 여부가 다릅니다.

또한 자동 실행되는 명령어는 실제 파일과 개발 환경에 영향을 줄 수 있으므로, 신뢰할 수 있는 명령어만 등록하고 적용 범위를 필요한 만큼 제한하는 것이 중요합니다.

Rules, Skills, Hooks 비교

세 기능은 모두 Claude의 작업을 보조하지만 목적이 다릅니다.

Rules  → 무엇을 지켜야 하는가?
Skills → 어떻게 작업해야 하는가?
Hooks  → 특정 상황에서 무엇을 실행할 것인가?

세 기능은 서로 대체하는 관계가 아니라 함께 사용할 수 있습니다.

MCP로 외부 도구 연결하기

Claude Code는 기본적으로 프로젝트 파일을 읽고 수정하거나 터미널 명령을 실행할 수 있습니다.

하지만 개발 과정에서는 외부 문서, 데이터베이스, 오류 모니터링 서비스, 이슈 관리 도구 등의 정보가 필요할 수 있습니다.

이때 활용할 수 있는 표준이 MCP(Model Context Protocol) 입니다.

MCP는 AI 애플리케이션이 외부 도구와 데이터에 연결할 수 있도록 하는 프로토콜입니다.

┌─────────────────────────────────────────┐
│ Claude Code                             │
│ 사용자 요청을 이해하고 필요한 도구 선택           │
└─────────────────────────────────────────┘
                    │ 1. 외부 도구 호출 요청
                    ▼
┌─────────────────────────────────────────┐
│ MCP Client                              │
│ MCP Server와 통신하고 요청·응답 전달          │
└─────────────────────────────────────────┘
                    │ 2. MCP 프로토콜로 도구 호출
                    ▼
┌─────────────────────────────────────────┐
│ MCP Server                              │
│ 요청받은 도구를 실행하고 외부 시스템 연결         │
│  ├── 외부 API                            │
│  ├── 데이터베이스                          │
│  └── 문서 및 개발 도구                      │
└─────────────────────────────────────────┘
                    │ 3. 실행 결과 반환
                    ▼
               MCP Client
                    │ 4. 결과를 Claude에 전달
                    ▼
              Claude Code
          결과 분석 후 사용자에게 응답

예를 들어 Cloudflare 공식 문서를 조회할 수 있는 MCP 서버를 연결할 수 있습니다.

claude mcp add --scope user --transport http cloudflare-docs https://docs.mcp.cloudflare.com/mcp

연결한 MCP 서버가 제공하는 도구를 Claude가 관련 작업에 활용할 수 있습니다.

다만 외부 MCP 서버를 사용할 때는 서버의 신뢰성과 접근 권한을 확인해야 합니다.

특히 데이터를 조회하는 도구와 실제로 수정하는 도구는 위험 수준이 다릅니다.

긴 작업과 반복 작업 관리하기

Claude Code는 개발 서버처럼 오래 실행되는 프로세스나 반복적인 확인 작업을 관리하는 기능도 제공합니다.

Background Tasks

개발 서버나 테스트 Watch 모드는 실행 후에도 프로세스가 계속 동작합니다.

npm run dev
npm run test -- --watch

Background Task를 활용하면 이러한 명령을 실행한 상태에서 다른 작업을 이어갈 수 있습니다.

개발 서버 실행
     ├── 백그라운드에서 유지
     ▼
Claude가 코드 수정
     │
     ▼
실행 결과 확인

/tasks를 통해 실행 중인 작업을 확인하거나 관리할 수 있습니다.

/loop와 Routines

/loop는 현재 Session에서 특정 작업을 일정한 간격으로 반복하도록 설정하는 기능입니다.

예를 들어 PR의 CI 상태를 주기적으로 확인하는 데 활용할 수 있습니다.

반면 Routines는 일정이나 이벤트를 기반으로 반복 작업을 실행하는 기능으로, 별도의 클라우드 실행 환경을 활용할 수 있습니다.

Routines는 현재 실험적 기능으로 제공되므로, 지원 범위와 사용 조건은 변경될 수 있습니다.

/goal로 완료 조건 설정하기

/goal은 작업의 완료 조건을 지정하고, 해당 조건을 충족할 때까지 Claude가 여러 차례 작업을 이어가도록 하는 명령어입니다.

예를 들어 아래와 같이 사용할 수 있습니다.

/goal 모든 TypeScript 타입 오류가 해결될 때까지 수정하고 검사해 줘`처럼 사용할 수 있습니다.

/loop가 일정한 간격으로 작업을 반복한다면, /goal은 목표 달성 여부를 기준으로 작업을 이어간다는 차이가 있습니다.

/goal clear로 활성 목표를 해제할 수 있습니다.

Remote Control

Remote Control은 로컬 컴퓨터에서 실행 중인 Claude Code Session을 다른 기기에서 이어서 제어할 수 있는 기능입니다.

로컬 컴퓨터에서 Claude Code 실행
↓
Remote Control 연결 (/remote-control)
↓
휴대폰 또는 다른 컴퓨터에서 작업 상태 확인 및 제어

/remote-control 또는 /rc를 통해 연결할 수 있습니다.

프로젝트와 실행 환경은 로컬에 유지하면서 다른 기기에서 진행 상황을 확인하거나 질문에 응답할 때 유용합니다.

답변과 작업 기록 관리하기

Output Styles

Output Styles는 Claude의 답변 방식과 형식을 조정하는 기능입니다.

예를 들어 다음과 같은 지침을 적용할 수 있습니다.

• 변경 사항을 간결하게 요약합니다.
• 불필요한 서론을 작성하지 않습니다.
• 작업 결과와 검증 결과를 구분합니다.
• 기술적인 설명은 필요한 경우에만 자세히 작성합니다.

Custom Output Style은 .claude/output-styles/에서 관리할 수 있습니다.

/rewind

Claude Code가 여러 파일을 수정한 뒤 이전 상태로 돌아가고 싶다면 /rewind를 활용할 수 있습니다.

Claude Code는 작업 중 생성한 Checkpoint를 기반으로 지원되는 범위에서 대화나 코드 변경을 되돌릴 수 있습니다.

Checkpoint A
↓
코드 수정
↓
Checkpoint B
↓
추가 수정
↓
문제 발견
↓
/rewind

Rewind는 편리하지만 Git의 완전한 대체 수단은 아닙니다.

데이터베이스 변경이나 외부 API 호출, 배포처럼 파일 수정 이외의 부작용을 모두 복구하지는 못합니다.

/fork로 대화 분기하기

/fork는 현재 Session의 대화 내용을 기준으로 별도의 대화 분기를 만드는 명령어로, /branch의 별칭입니다.

기존 대화를 유지한 채 다른 구현 방향을 시도하거나 비교할 때 유용하며, /resume으로 이전 대화에 돌아갈 수 있습니다.

단, 대화 분기는 Git 브랜치나 작업 디렉터리를 자동으로 분리하는 기능과는 다릅니다.

작성한 코드는 어떻게 검증할까?

AI 코딩 에이전트를 사용할 때 가장 중요한 원칙 중 하나는 코드를 작성했다는 것과 정상적으로 동작한다는 것은 다르다는 점입니다.

Claude가 기능 구현을 완료했다고 답변하더라도 다음과 같은 문제가 남아 있을 수 있습니다.

• TypeScript 또는 ESLint 오류
• 잘못된 API 요청
• 예외 상황 처리 누락
• 기존 기능의 회귀 오류
• 실제 브라우저에서 발생하는 UI 문제

따라서 구현 후에는 작업 범위에 맞는 검증 과정이 필요합니다.

기본 검증 흐름

코드 구현
↓
타입 및 린트 검사
↓
관련 테스트 실행
↓
필요한 경우 빌드
↓
실제 기능 확인
↓
변경 사항 검토

모든 수정에서 전체 테스트와 빌드를 실행할 필요는 없습니다.

변경 범위와 영향도에 맞춰 필요한 검증 수준을 선택하는 것이 좋습니다.

코드 리뷰와 검증 기능

Claude Code에는 코드 검토와 개선에 활용할 수 있는 명령어 및 Skill이 있습니다.

예를 들어 로그인 기능을 구현했다면 타입 검사뿐 아니라 실제 로그인 과정을 실행해 확인하는 것이 좋습니다.

로그인 기능 구현
↓
앱 실행
↓
로그인 페이지 접근
↓
사용자 입력 및 요청
↓
결과 확인

검증에 필요한 브라우저 자동화 도구가 연결되어 있다면 Claude가 실제 애플리케이션을 실행하고 사용자 동작을 재현하며 확인할 수 있습니다.

대표적으로 Playwright나 Chrome DevTools MCP 등을 활용할 수 있습니다.

• Playwright: 브라우저를 자동으로 조작하여 페이지 이동, 버튼 클릭, 입력, 화면 상태 확인 등을 수행할 수 있습니다.
• Chrome DevTools MCP: Chrome 브라우저와 연결하여 페이지를 조작하고, 콘솔 오류나 네트워크 요청 등을 확인할 수 있습니다.

예를 들어 로그인 기능을 구현했다면 Claude가 브라우저에서 로그인 페이지에 접근하고, 이메일과 비밀번호를 입력한 뒤 로그인 성공 여부나 오류 메시지를 확인하도록 할 수 있습니다.

Claude Code를 실제 개발에서 활용하는 흐름

1. 요구사항 확인

기능의 목적, 사용자 시나리오, 필수 요구사항, 제외할 범위, 완료 조건을 정의합니다.

요구사항이 불명확하다면 구현 전에 질문하도록 요청합니다.

2. 코드베이스 분석

관련 파일과 기존 구현 패턴을 조사합니다.

탐색 범위가 넓다면 Explore Agent를 활용해 분석 작업을 분리할 수 있습니다.

3. 구현 계획 수립

여러 파일을 수정하거나 기존 구조에 영향을 주는 작업이라면 Plan Mode에서 변경 범위와 구현 순서를 검토합니다.

4. 코드 구현

CLAUDE.md와 Rules를 통해 프로젝트 규칙을 참고하고, 필요한 경우 Skills를 활용합니다.

독립적인 작업이 많다면 Subagents나 Worktrees를 검토할 수 있습니다.

5. 테스트 및 검증

타입 검사, 린트, 관련 테스트를 실행하고 필요하면 실제 브라우저에서 동작을 확인합니다.

6. 변경 사항 검토

마지막으로 다음 사항을 확인합니다.

• 요구사항을 충족했는가?
• 기존 코드 스타일과 일관성이 있는가?
• 불필요한 추상화나 복잡성이 추가되지 않았는가?
• 기존 기능에 영향을 주지는 않는가?
• 실제로 검증한 내용과 미검증 내용을 구분했는가?

각 단계에서 활용할 수 있는 기능을 정리하면 다음과 같습니다.

정리

Claude Code는 단순히 코드를 생성하는 도구가 아니라 프로젝트의 맥락을 이해하고 여러 도구를 사용해 개발 작업을 수행하는 AI 코딩 에이전트입니다.

핵심 개념을 정리하면 다음과 같습니다.

• Agent Loop: 판단, 도구 실행, 결과 확인을 반복하며 작업을 수행합니다.
• Session과 Context: 작업 대화와 판단에 필요한 정보를 관리합니다.
• CLAUDE.md와 Rules: 프로젝트의 공통 규칙과 영역별 제약을 전달합니다.
• Skills: 반복적인 작업의 수행 방법을 재사용합니다.
• Plan Mode: 구현 전에 요구사항과 변경 범위를 검토합니다.
• Permissions와 Sandboxing: 작업 권한과 실행 환경의 접근 범위를 관리합니다.
• Subagents와 Worktrees: 독립적인 작업과 작업 공간을 분리합니다.
• Hooks와 자동화 기능: 이벤트나 일정에 따라 반복 작업을 수행합니다.
• MCP: 외부 도구와 데이터에 연결합니다.
• 테스트와 검증: 작성한 코드가 실제 요구사항을 충족하는지 확인합니다.

결국 중요한 것은 Claude에게 모든 작업을 무조건 맡기는 것이 아닙니다.

프로젝트의 맥락과 규칙을 명확하게 전달하고, 적절한 작업 범위와 권한을 설정하며, 결과를 검증하는 개발 과정을 만드는 것입니다.

Claude Code의 다양한 기능은 이러한 개발 과정을 더 효율적이고 일관되게 수행하기 위한 도구라고 이해할 수 있습니다.

참고 자료

• Claude Code 공식 문서
• Claude Code MCP
• Agent Skills
• skills.sh