KO
EspañolEnglishDeutschFrançaisPortuguêsTiếng Việt简体中文한국어日本語
홈 / AI & 머신러닝 / AI Agent

Claude Code의 12가지 기능: 상세 설명 및 예제

Cris The Dev · 2026. 10. 05. · 9 분 읽기 · 159
이 글에는 짧은 영상이 있습니다:TikTok

1. 개요

Claude Code는 터미널에서 실행되는 코딩 에이전트로, 프로젝트의 코드를 읽고 수정하고 명령어를 실행하며 자동으로 검증할 수 있습니다. 문제는 에이전트가 강력하지만 기본 설정으로 사용하면 “길을 잃기” 쉽다는 것입니다 - 잘못된 파일을 수정하거나, context window를 모두 소비하거나, 위험한 명령어를 실행할 수 있습니다. 이 글은 이 에이전트를 의도적으로 제어할 수 있게 도와주는 12가지 기능을 설명합니다. 이 글을 읽고 나면 CLAUDE.md, permissions, hooks, MCP 등을 구성하는 방법을 알게 되어 Claude Code가 팀의 규칙을 따르도록 만들 수 있습니다. Order, Customer, PaymentService를 포함하는 Spring Boot 예제 프로젝트를 통해 학습합니다.

2. CLAUDE.md

CLAUDE.md는 Claude Code가 매 세션 시작 시 자동으로 읽는 메모리 파일입니다. 여기서 코드 규칙, 디렉토리 구조, 빌드 명령어, 스타일 가이드 등을 선언하면, 에이전트가 매번 물어보지 않아도 됩니다.

# CLAUDE.md

## 아키텍처
- Package `com.nonladev.order`: domain Order, Customer
- Package `com.nonladev.payment`: PaymentService, PaymentGateway (interface)

## 규칙
- 새로운 public 메서드에는 항상 JUnit 5 + AssertJ 테스트를 작성하세요
- `@Autowired` 필드 주입 대신 생성자 주입만 사용하세요
- "완료"라고 보고하기 전에 `mvn verify`를 실행하세요

## 자주 사용하는 명령어
- Build: `mvn -q clean verify`
- 로컬 실행: `mvn spring-boot:run`

Claude는 세션 내 어떤 작업을 수행하기 전에 이 파일을 읽습니다. 예를 들어 “PaymentService에 환불 메서드를 추가하세요”라고 요청하면, 에이전트는 자동으로 생성자 주입을 사용하고 테스트를 함께 작성합니다 - 다시 설명할 필요가 없습니다.

주의: CLAUDE.md에 너무 많은 세부 사항을 넣지 마세요. 긴 파일은 세션 시작부터 context window를 낭비하며, 대부분의 내용이 현재 작업과 무관할 수 있습니다.

3. Permissions

Permissions은 Claude가 사용할 수 있는 도구와 차단할 도구를 제어합니다 - 에이전트가 실제 shell 명령어를 실행할 수 있기 때문에 중요합니다.

{
  "permissions": {
    "allow": [
      "Bash(mvn *)",
      "Edit(src/main/java/**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Edit(src/main/resources/application-prod.properties)"
    ]
  }
}

이 settings.json 파일은 .claude/ 디렉토리에 위치합니다. allow 줄은 에이전트가 mvn을 실행하고 src/main/java 내의 파일을 수정할 수 있게 허용하지만, deny 줄은 재귀 삭제 명령어와 프로덕션 설정 파일 수정을 절대적으로 차단합니다. Claude가 권한을 초과하려 하면 실행하기 전에 확인을 요청합니다.

흔한 실수: 너무 넓은 권한 설정(allow: ["*"])을 두면 에이전트가 확인 없이 어떤 명령이든 실행할 수 있어 민감한 설정 파일이나 시크릿에 위험합니다.

4. Plan Mode

Plan Mode는 Claude가 코드를 건드리기 전에 계획을 제시하도록 합니다. 계획을 검토하고 필요하면 수정한 후 실행하도록 합니다.

> PaymentService에 부분 환불 기능 추가

[PLAN MODE]
1. PaymentService에 refundPartial(Order order, BigDecimal amount) 메서드 추가
2. amount <= order.getTotalPaid() 검증
3. PaymentGateway.refund(...) 호출
4. 유효한 경우와 금액 초과 경우에 대한 PaymentServiceTest 작성

이 계획을 진행하기를 원하시나요? [y/n/edit]

edit으로 답변하면 Claude는 제안(예: 감사 로그 단계 추가)에 따라 계획을 수정한 후 실제 소스 코드를 건드립니다. 이 방식은 여러 파일을 수정하는 작업에 특히 유용합니다. 계획 단계에서 바로 방향 오류를 발견할 수 있기 때문입니다. 코드가 이미 여러 곳에서 수정된 후가 아닙니다.

5. Checkpoints

Checkpoints는 세션 중 중요한 시점에서 프로젝트의 자동 스냅샷으로, 에이전트가 일을 망쳤을 때 “되감기”할 수 있게 해줍니다.

# 세션 내 checkpoint 이력 보기
/rewind

# 출력
Checkpoint 1 - 10:02 - PaymentService 수정 전
Checkpoint 2 - 10:05 - refundPartial 추가 후
Checkpoint 3 - 10:09 - 테스트 수정 후 (오류 발생)

# checkpoint 2로 돌아가기
/rewind 2

Git commit과 달리 checkpoint는 직접 만들 필요가 없습니다 - Claude Code가 각 주요 변경 전에 자동으로 저장합니다. 에이전트가 테스트를 잘못 수정하면(예: assertion을 주석 처리해 테스트를 “통과”하게 함), 수동으로 git reset하지 않고 이전 상태로 되감을 수 있습니다.

주의: checkpoint는 현재 세션 내에서만 유지되며 git을 대체하지 않습니다. 마일스톤에 도달하면 실제로 commit해야 합니다.

6. Skills

Skills는 재사용 가능한 가이드 파일로, Claude가 적절한 작업을 감지할 때 자동으로 적용합니다 - 매번 이름을 지정할 필요가 없습니다.

---
name: spring-boot-test-writer
description: Spring Boot 프로젝트의 서비스 계층 테스트 작성 필요 시 사용
---

서비스 클래스에 대한 테스트 작성 시:
1. JUnit 5 + AssertJ 사용, Hamcrest는 사용하지 말기
2. Mockito로 의존성 Mock 처리, 변수명은 `mock<Dependency>` 형식
3. 테스트 메서드명은 `should_<expected>_when_<condition>` 형식 사용

이 파일은 .claude/skills/spring-boot-test-writer.md에 위치합니다. “PaymentService에 대한 테스트 작성”을 요청하면 Claude가 자동으로 적절한 skill을 인식하고 규칙을 적용하며, 결과는 다음과 같습니다:

class PaymentServiceTest {

    private final PaymentGateway mockGateway = mock(PaymentGateway.class);
    private final PaymentService paymentService = new PaymentService(mockGateway);

    @Test
    void should_refundAmount_when_amountIsWithinPaidTotal() {
        Order order = new Order("ORD-1", BigDecimal.valueOf(200));

        paymentService.refundPartial(order, BigDecimal.valueOf(50));

        verify(mockGateway).refund(order.getId(), BigDecimal.valueOf(50));
    }

    @Test
    void should_throwException_when_amountExceedsPaidTotal() {
        Order order = new Order("ORD-2", BigDecimal.valueOf(100));

        assertThatThrownBy(() -> paymentService.refundPartial(order, BigDecimal.valueOf(150)))
            .isInstanceOf(IllegalArgumentException.class);
    }
}

Skills는 CLAUDE.md와 다릅니다: CLAUDE.md는 항상 로드되지만, skill은 컨텍스트가 필요할 때만 로드됩니다 - 많은 특화된 규칙이 있는 프로젝트의 context window를 절약합니다.

7. Hooks

Hooks는 에이전트의 lifecycle의 특정 시점에 shell script를 실행합니다. 예를 들어 PreToolUse(도구 호출 전) 또는 PostToolUse(도구 호출 후)입니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "mvn -q -pl . checkstyle:check"
      }
    ]
  }
}

Claude가 파일 수정을 완료할 때마다(Edit 도구), hook이 자동으로 checkstyle:check를 실행합니다. 명령어가 실패하면 출력이 Claude로 반환되고, 에이전트는 스타일 오류에 따라 코드를 자동으로 수정한 후 작업 완료를 보고합니다 - 수동으로 검사를 실행할 필요가 없습니다.

[PostToolUse] mvn checkstyle:check
오류: PaymentService.java:42: 줄 길이가 120 문자를 초과
→ Claude가 자동으로 42줄을 단축하고 검사를 다시 실행

언제 사용하면 안 되는가: hook은 도구가 호출될 때마다 실행되므로, 무거운 스크립트(전체 프로젝트 빌드)면 세션이 상당히 느려집니다. 빠른 검사가 필요한 lifecycle 이벤트에만 hook을 설정하세요.

8. MCP

MCP(Model Context Protocol)는 Claude를 외부 시스템 - 데이터베이스, 내부 API, 이슈 트래커 등과 연결합니다. 표준화된 도구처럼 작동합니다.

{
  "mcpServers": {
    "postgres-orders": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/orders_db"]
    }
  }
}

.claude/settings.json에서 이 서버를 등록한 후 직접 질문할 수 있습니다:

> 테이블 orders에서 PENDING 상태인 Order가 몇 개인가요?

[MCP: postgres-orders] SELECT COUNT(*) FROM orders WHERE status = 'PENDING';
→ 37개의 PENDING 주문

Claude가 자동으로 SQL을 생성하고, MCP 서버를 통해 호출하여 데이터베이스에서 실제 결과를 반환합니다 - 수동으로 다른 터미널에 쿼리를 복사할 필요가 없습니다.

9. Plugins

Plugin은 관련된 skills, MCP 서버 및 hooks를 미리 패키징한 번들로, 각 부분을 따로 구성하지 않고 한 번에 설치할 수 있습니다.

/plugin install spring-boot-toolkit

이 명령어는 다음을 포함하는 가정의 plugin을 설치합니다: Spring Boot 테스트 작성 skill, 매 수정 후 mvn verify를 실행하는 hook, Spring Boot Actuator 엔드포인트에 연결하여 에이전트가 헬스 체크를 자동 검증하는 MCP 서버. 섹션 6-8처럼 3개의 별도 구성 파일(skill, hook, mcp)을 작성하는 대신, plugin이 이를 패키징하여 한 줄의 명령어로 전체 팀과 공유할 수 있는 패키지로 만듭니다.

10. Context

Context는 현재 세션의 context window입니다 - 읽은 모든 파일, 대화 이력, 명령어 출력입니다. /context 명령어는 현재 사용 중인 양을 보여줍니다.

/context
Context usage: 48,200 / 200,000 tokens (24%)
- CLAUDE.md: 1,200 tokens
- Files read: PaymentService.java, Order.java, PaymentServiceTest.java (6,400 tokens)
- 대화 이력: 38,000 tokens
- Tool outputs: 2,600 tokens

대화 이력이 대부분을 차지하면, compact하거나 새 세션을 시작해야 한다는 것을 알 수 있습니다. Context가 가득 차서 세션 초반의 중요한 세부 사항을 Claude가 “잊게” 되는 것을 방지하기 위함입니다.

11. Slash Commands

Slash command는 반복적으로 실행하는 작업의 바로가기입니다 - /를 입력하고 이름을 지정하면 되며, 매번 긴 프롬프트를 다시 작성할 필요가 없습니다.

---
name: review-pr
description: 표준 체크리스트에 따라 현재 diff 검토
---

체크리스트를 사용하여 현재 코드 diff 검토:
1. 새로운 로직에 대한 테스트가 있나요?
2. 민감한 정보(카드 번호, 비밀번호)를 기록하지는 않나요?
3. 생성자 주입 규칙을 위반하지는 않나요?

각 항목에 대해 PASS/FAIL 형식으로 답변하고 이유를 포함하세요.

이 파일을 .claude/commands/review-pr.md에 저장한 후 호출하세요:

/review-pr
1. PASS - refundPartial에 대한 PaymentServiceTest가 있음
2. FAIL - log.info가 58줄에서 order.getCardNumber()를 포함
3. PASS - 생성자 주입을 사용함

Slash command는 skill과 다릅니다: skill은 컨텍스트에 따라 자동 활성화되지만, slash command는 명시적으로 이름을 호출해야 합니다 - PR 검토, 릴리스 노트 같은 고정 체크리스트에 적합합니다.

12. Compaction

Compaction은 긴 대화 이력을 요약본으로 압축하여 중요한 정보를 잃지 않으면서 토큰을 해제합니다.

/compact
압축 전: 182,000 / 200,000 tokens
압축 후: 24,000 / 200,000 tokens

보관된 요약:
- 진행 중: PaymentService에 refundPartial 추가
- 완료됨: PaymentServiceTest (2개 테스트 케이스 통과)
- 남은 것: /refund 엔드포인트에 대한 OpenAPI 스펙 업데이트

Context가 가득 차서 에이전트가 이력을 완전히 잊는 대신, compaction이 중요한 마일스톤(진행 중인 작업, 완료된 작업, 남은 작업)을 짧은 요약본으로 유지하고, 대부분 비어있는 context로 세션을 계속합니다. 큰 작업 단계를 완료한 후 다음 작업으로 전환하기 전에 주동적으로 /compact를 호출해야 합니다.

13. Subagents

Subagents는 Claude Code가 여러 에이전트 자식을 생성하여 병렬로 실행하도록 하며, 각 에이전트는 큰 workflow의 독립적인 부분을 담당합니다.

---
name: test-writer
description: 지정된 클래스에 대한 단위 테스트 작성 전문
tools: Read, Edit, Bash
---

테스트만 작성하고 비즈니스 로직을 수정하지 마세요. JUnit 5 + AssertJ를 사용하세요.

.claude/agents/test-writer.md의 이 subagent 파일을 사용하면, 큰 작업을 메인 에이전트에 할당할 수 있고, 메인 에이전트가 자동으로 작업을 분담합니다:

> 환불 모듈 완성: 로직 추가, 테스트 작성, 문서 업데이트

[메인 에이전트] 3개의 subagent에 병렬로 작업 분담:
  → subagent "code-writer": PaymentService에 refundPartial 추가
  → subagent "test-writer": PaymentServiceTest 작성
  → subagent "doc-writer": README.md 업데이트

[3개 subagents 병렬 실행] ... 42초 후 완료

메인 에이전트가 순차적으로 각 단계를 처리하는 대신(코드 → 테스트 → 문서, 3배 시간 소요 가능), subagents는 독립적인 부분을 동시에 처리합니다 - 서로 밀접히 의존하지 않는 많은 단계의 workflow에 유용합니다.

언제 사용하면 안 되는가: 단계가 순차적으로 의존하면(예: 테스트 작성이 완성된 코드를 필요로 해 인터페이스를 알아야 함), 병렬 실행은 subagent 테스트가 코드가 존재하기 전에 실행되어 오류를 일으킵니다. 정말로 독립적으로 분리 가능한 작업에만 subagents를 사용하세요.

14. 결론

위의 12가지 기능은 세 가지 명확한 그룹으로 나뉩니다: 에이전트 방향 설정 그룹(CLAUDE.md, Skills, Plan Mode), 안전 제어 그룹(Permissions, Checkpoints, Hooks), 기능 확장 그룹(MCP, Plugins, Subagents). Context, Slash Commands 및 Compaction은 에이전트가 긴 세션에서 효율적으로 실행되도록 하는 기반 계층입니다. 12개를 모두 동시에 사용할 필요는 없습니다 - 현재 프로젝트의 CLAUDE.md와 Permissions부터 시작한 후, workflow가 정말로 필요할 때 Hooks나 MCP를 추가하세요.

Claude CodeAI AgentDevToolsSpring Boot생산성
저자의 앱HoanTien.proCashback on Shopee, TikTok Shop and Lazada (Vietnam)iOS · Android · Web

같은 주제의 글