클로드 코드(Claude Code) 완전 분석 - 20년 차 개발자가 6개월간 주력으로 사용해 본 후기

 

터미널에 익숙한 개발자분들이라면 한 번쯤은 생각해 봤을 거예요.

"VS Code 안에 있는 AI 말고 터미널에서 바로 실행할 수 있는 건 없나?"

저는 처음에 Chat GPT를 이용해서 오류를 복붙하며 사용하기 시작했어요.

물론 그것도 너무 잘했는데 코드 조각만 보고 답변을 주는 거라 가끔 헤매는 경우도 있어서 프로젝트를 잘 이해해서 해줄 수는 없을까 생각했어요.

그러던 중 터미널에서 사용할 수 있는 클로드 코드를 알게 되었고 사용하기 전부터 너무 기대감에 설레었던 거 같네요.

그렇게 지난 6개월간 거의 모든 프로젝트의 주력 도구로 사용해왔습니다.

물론 초기에는 내가 짠 코드를 망가트리지 않을까 하는 걱정에 소극적으로 사용했지만 지금은 많을 영역에 사용을 하고 있어요.

Spring Boot + React 기반의 커머스 플랫폼, WMS, 커뮤니티 서비스, 그리고 React Native 변환 작업까지 해보면서 솔직히 도구 하나에 이렇게 깊이 의존하게 될 줄은 몰랐어요.

오늘은 그 경험을 정리해 보려고 해요.

---

3줄 요약

• Claude Code는 AI 자동완성이 아니라 프로그래머블한 코딩 플랫폼이에요. 챗봇처럼 사용하면 80%를 놓쳐요.
• CLAUDE.md, Hooks, Subagents, Skills, MCP 이 다섯 가지를 이해해야 진짜 가치가 나와요.
• 다중 리팩토링, 운영 코드 수정, 한국어 문서화에 현존 제일 좋아요.(개인적인 생각)
• 비용이 좀 들어요. 하지만 일주일만 진지하게 써보면 본전을 뽑을 거예요.

 

---

1. Claude Code가 뭐지?

간단히 말하면, 터미널에서 동작하는 Anthropic의 코딩 에이전트에요.

Cursor나 Windsurf 같은 IDE 통합형 도구와는 달리, 터미널에서 독립적으로 동작해요. 그래서 어떤 IDE를 쓰더라도 상관없이 사용할 수 있어요.

Vim, VS Code, Intelli J 어떠한 걸 쓰더라도, 터미널에 Claude Code를 띄워두기만 하면 돼요.

 

설치는 간단

# 네이티브 인스톨 (권장)
curl -fsSL https://claude.ai/install.sh | bash

# 또는 npm
npm install -g @anthropic-ai/claude-code

 

처음 시작할 때

cd my-project
claude

 

프로젝트 디렉터리로 이동한 후 claude 명령어를 치면 세션이 시작돼요.

처음에는 "이 코드 리팩토링해줘", "여기 버그 수정해 줘"처럼 챗봇처럼 써보세요.

그런데 계속 그렇게 사용하는 건 Claude Code의 20%만 사용하는 셈이에요.

 

---

2. 진짜 가치는 다섯 가지 확장 포인트에 있어요

다른 AI CLI와 Claude Code의 결정적 차이는 확장성이에요. Anthropic은 Claude Code를 단일 도구가 아니라 플랫폼으로 설계했어요. 그 확장 포인트가 다섯 가지나 있어요.

 

2-1. CLAUDE.md - 프로젝트의 헌법

프로젝트 루트 경로에 CLAUDE.md 파일을 생성해두면, Claude는 매 세션마다 이 파일을 읽고 시작해요.

코딩 스타일, 빌드 명령어, 아키텍처 노트, 금지 사항 등을 적어두면 돼요.

 

내가 쓰는 예시:

# 프로젝트: 원이지(OneEasy) 백엔드

## 스택
- Java 17 / Spring Boot 3.2 / JPA / MySQL 8
- 빌드: `./gradlew build`
- 테스트: `./gradlew test`

## 코딩 규칙
- 모든 API 응답은 ApiResponse<T> 래퍼로 감싼다
- 트랜잭션은 서비스 레이어에서만 시작한다
- 엔티티는 직접 컨트롤러로 노출하지 않는다 (DTO 변환 필수)

## 절대 하지 말 것
- @Transactional을 컨트롤러에 붙이지 말 것
- application.yml의 prod 설정을 건드리지 말 것

 

중요한 팁을 하나 드리자면 CLAUDE.md는 200줄을 넘기지 않는 게 좋아요. Anthropic 공식 권장 사항이기도 하고, 길어질수록 Claude가 일부 내용을 무시하는 빈도가 늘어나기 때문이에요.

Claude에게 "이 줄을 지우면 Claude가 실수할까?"라고 물어보고 지우는 방법도 괜찮은 거 같아요.

 

그리고 CLAUDE.md는 어디까지나 권고사항이지 절대 지켜라 하는 사항은 아니에요. 약 80% 정도 지킨다고 생각하고 100% 강제하고 싶다면 다음에 나오는 Hooks를 쓰면 돼요.

 

2-2. Hooks - 결정론적 가드레일

Hooks는 Claude Code의 생애 주기 이벤트에 훅을 걸어서 셀 명령어를 실행하도록 해줘요.

AI의 해석에 의존하지 않고 100% 실행되어요.

 

예시 - 파일 수정 후 자동 포맷팅:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          { "type": "command", "command": "./scripts/format.sh" }
        ]
      }
    ]
  }
}

 

어떤 상황에 쓰면 좋을지 예를 들면 "절대 메인 브랜치에 force push 하지 마라" 같은 규칙은 CLAUDE.md에 적어두면 80% 정도만 지켜질 수 있어요. 운 나쁘게 새벽에 돌려놓다가 대형 사고가 날수 있어서 그런 종류는 무조건 Hook으로 막아야 해요.

 

내가 실제로 운영하는 Hook들:

• PreToolUse에서 rm -rf 차단
• PostToolUse에서 Java 파일 수정되면 자동으로 ./gradlew spotlessApply
• Stop에서 변경된 파일 목록을 Slack에 알림

 

2-3. Subagents - 컨텍스트 오염을 막는 결정적 무기

Claude Code의 가장 강력한 기능 중 하나인데, 별도의 Claude 인스턴스를 띄워서 작업을 위임하고, 결과 요약만 받아와요.

이게 중요한 이유는 큰 코드 베이스를 탐색하다 보면 메인 컨텍스트가 금방 오염되거든요. "이 파일 읽어봐, 저 파일도 읽어봐" 하다 보면 정작 본 작업을 시작할 때쯤이면 컨텍스트가 오염돼서 너덜너덜해져요. Subagent는 깨끗한 컨텍스트에서 탐색을 하고 요약만 다시 전달해 줘요.

 

.claude/agents/code-reviewer.md 같은 식으로 정의하면 돼요

---
name: code-reviewer
description: 코드 품질, 보안, 베스트 프랙티스 관점에서 리뷰. 코드 변경 후 자동 실행.
tools: Read, Glob, Grep
model: sonnet
---

당신은 시니어 코드 리뷰어다.
다음을 중점적으로 본다:
1. SQL 인젝션, XSS 같은 보안 이슈
2. N+1 쿼리 같은 성능 이슈
3. 트랜잭션 경계가 적절한지
4. 테스트 커버리지가 충분한지

구체적이고 실행 가능한 피드백만 준다.

 

이제 메인 세션에서 "방금 작성한 결제 모듈 리뷰해 줘"라고 하면 Claude는 code-reviewer 서브 에이전트를 띄워서 리뷰하고 요약을 받아와요. 메인 컨텍스트는 깨끗하게 유지가 돼요!

 

2-4. Skills - 재사용 가능한 지식 패키지

Skills는 .claude/skills/<skill-name>/SKILL.md 구조로 정의되는 재사용 가능한 작업 지침이에요. 특정 도메인의 노하우(예: Spring Boot에서 Oauth2 설정하기, STOMP WebSocket 디버깅)를 패키지로 만들어두면, Claude가 해당 작업이 필요할 때 자동으로 로드해서 사용해요.

 

JIT (Just-In-Time) 로딩이라는 점이 핵심인데 모든 Skill을 항상 컨텍스트에 들고 있는 게 아니라, 딱 필요한 순간 그때만 불러와요. 그래서 Skill을 100개 만들어둬도 토큰 부담을 줄일 수 있어요.

 

2-5. MCP (Model Context Protocol) - 외부 도구 연결

MCP는 Claude를 외부 시스템과 연결하는 표준 프로토콜이에요. GitHub, Slack, 데이터베이스, 회사 내부 API 등을 도구로 연결할 수 있어요.

예를 들어 GitHub MCP를 붙이면 Claude가 PR 생성, 이슈 코멘트, 브랜치 관리를 직접 하게 돼요. 데이터 베이스 MCP를 붙이면 스키마를 직접 들여다보면서 쿼리를 짠다고 하는데 데이터 베이스 쪽은 아직 걱정돼서 사용은 안 해봤어요; MCP를 사용함으로써 AI가 코드만 쓰는 게 아니라, 운영 환경과 직접 상호작용까지 하는 단계로 넘어가게 돼요.

 

---

3. 실전 워크플로우 - 내가 실제로 일하는 방식

20년 개발하면서 정착한 흐름이 있어요. Research -> Plan -> Annotation -> Implementation. Claude Code는 이 흐름이 정말 잘 맞는 거 같아요.

 

단계 1 : Research (탐색)

새 기능을 구현해야 할 때, 절대 코드부터 바로 짜지 않아요.

> 우리 코드베이스에서 결제 관련 로직이 어디 어디에 흩어져 있는지 
  서브에이전트 띄워서 정리해줘. 의존성 그래프도 같이.

 

Subagent가 코드 베이스를 탐색하고 요약을 돌려줘서 메인 컨텍스트는 깨끗하게 유지돼요.

 

단계 2 : Plan (계획)

> 이 결제 모듈에 카카오페이 연동을 추가하려고 해. 
  먼저 구현 계획부터 세워줘. 코드는 아직 쓰지 마.

 

프롬프트에서 "코드는 아직 쓰지 마"는 정말 중요해요. Claude는 시키면 우선 코드부터 쓰려고 하기 때문에 계획 단계임을 말해줘야 해요.

 

단계 3 : Annotation (주석/설계 문서화)

계획인 마음에 든다면, 실제 코드를 쓰기 전에 주석으로 의도를 먼저 적게 하세요.

> 이제 PaymentService.kakaoPayApprove() 메서드를 만들 건데, 
  메서드 시그니처와 상세 주석부터 먼저 짜줘. 본문 구현은 다음 단계.

 

이 단계가 생각보다 중요한데, AI가 코드를 잘못 짜는 대부분의 이유가 의도를 정확히 이해하지 못한 상태로 코드부터 쓰기 때문이에요. 주석을 먼저 쓰게 하면 의도 검증을 코드 작성 전에 끝낼 수 있어요.

 

단계 4 : Implementation (구현)

이제야 드디어 코드를 짜요. 앞에서 계획과 주석이 잘 잡혀 있다면, 이 단계는 거의 기계적으로 코드를 짜요. (기계가 맞긴 하지만...)

> 이제 위 주석에 맞춰서 본문 구현해줘. 
  완료 후 code-reviewer 서브에이전트로 리뷰까지 돌려줘.

 

 

---

4. 장점 - 솔직한 체감

# 다중 파일 리팩토링이 압도적이에요

Spring Boot 프로젝트에서 도메인 모델 하나 바꾸려면 엔티티, 리포지토리, 서비스, DTO, 컨트롤러, 테스트까지 6~7개 파일을 같이 바꿔야 해요. Claude Code는 이걸 한 흐름으로 처리해요. 다른 도구는 "이 파일 바꿨으니 저 파일도 바꿔야 하지 않을까요?"라고 묻는다면 Claude는 그냥 다 같이 한 번에 봐요.

 

# 한국어 처리가 자연스러워요

주석, 커밋 메시지, README, 사용자용 에러 메시지까지 한국어로 시켜도 후처리 거의 없이 그대로 사용하는 편인 거 같아요. 일본어, 대만어(번체)도 마찬가지로 좋은 거 같고요. 이건 다국어 Youtube 채널 스크립트 작업할 때 결정적이 차이로 느껴진 거 같아요. 역시 글쓰기는 클로드!!

 

# TODO 기반 상태 관리가 길게 가도 안 무너져요

장시간 작업 시켜놓고 잠깐 한눈팔다 돌아오면 Claude는 자기 TODO 리스트를 갱신해가면 작업하고 있어요. 멀티 에이전트 같은 거창한 구조가 아닌데도 제대로 잘하는 거 같아요. 의외로 단순한 구조가 실무에선 가장 안정적인 느낌이에요.

 

# 확장 포인트가 풍부해요

위에서 본 다섯 가지 확장점이 프로젝트마다 다른 워크플로우를 정착시키기 좋아요. 우리 회사 같은 경우 프로젝트 5~6개를 동시에 돌리는데, 각 프로젝트마다 CLAUDE.md, Hooks, Subagents가 각각 다른게 세팅되어 있어요.

 

# 컨트롤이 명확해요

작업 전에 "이 파일들을 수정하겠습니다. 진행할까요?"라고 물어봐요. 자동 모드로 귀찮음을 덜 수도 있지만 그래도 운영 코드에선 매번 확인받는 게 안전하니까요.

 

---

5. 단점 - 솔직하게...

# 무료 티어가 없어요

진입 장벽이 가장 높은 거 같아요. 처음 손에 익히려면 Pro($20/월)은 무조건 사용해야 해요. 하지만 조금만 진지하게 쓰려면 Pro는 토큰이 부족해서 결국 Max 플랜으로 올라가게 돼요.

 

# 클로즈드 소스예요

내부 동작을 직접 뜯어볼 수 없어요. 사내 보안 정책상 클로즈드 소스 툴을 못 쓰는 곳도 있을 텐데, 이런 경우엔 오픈소스인 Codex CLI나 Gemini CLI가 대안이 될 수 있을 것 같아요.

 

# 속도가 빠르지는 않아요

깊게 생각하고 움직이는 만큼 단수한 한 줄 수정 같은 작업선 간혹 답답할 때가 있어요. "한 줄만 고쳐달라"는 요청에도 주변 컨텍스트를 다 읽고 시작하기 때문에 빠른 실험엔 Gemini CLI가 나을 때도 있어요.

 

# 토큰 소모가 적지 않아요

같은 작업에서 Codex CLI 대비 토큰을 2~4배 더 쓴다고 해요. 그만큼 깊이 보는 거지만, API 직접 호출로 운영하게 된다면 비용이 장난 아니게 사용돼요. 그래서 Max 같은 정액제가 차라리 나은 거 같아요.

 

# "챗봇처럼"만 쓰면 진짜 가치를 못 봐요

이건 담점이라기보다는 학습 곡선의 문제죠. 설치만 하고 그냥 챗봇처럼 쓰면 다른 도구와 큰 차이를 못 느낄 거예요. CLAUDE.md, Hooks, Subagents까지 셋업 해야 비로소 "아 이래서 사람들이 칭찬하는구나" 하고 생각될 거예요.

 

---

6. 누구한테 추천?

잘 맞는 경우

• 운영 중인 프로덕션 코드를 다루는 개발자
• 다중 파일이 얽힌 복잡한 리팩토링이 잦은 경우
• 한국어 문서화, 다국어 콘텐츠 작업이 많은 팀
• 워크플로우를 세팅해서 장기적으로 굴리고 싶은 팀
• 본인이 시니어급이라 AI 출력을 검증할 수 있는 경우

잘 안 맞는 경우

• 무료로만 써야 하는 경우 -> Gemini CLI 추천
• 클로즈드 소스 정책이 막힌 환경 -> Codex CLI 추천
• 단순 자동완성, 한 줄 짜기 정도만 필요한 경우 -> IDE 통합형이 더 나을 수도..
• AI 출력을 검증할 능력이 없는 주니어 -> 학습 도구로는 좋지만 의존하면 위험!!

 

---

7. 마치며.

Claude Code를 6개월 써 본 가장 큰 깨달음은 이거에요. "이건 도구가 아니라 플랫폼이다."

VS Code 확장 한 두개 깔듯이 쓰면 평함한 AI 챗봇이에요. 그런데 CLAUDE.md를 정성껏 쓰고, Hooks로 가드레일을 치고, Subagent로 역활을 분담하고, Skills로 노하우를 패키징하기 시작한다면 그때부터 진짜로 "내 팀의 한 명"이 되요.

---

이 글은 2026년 5월 기준이에요. Claude Code는 매달 업데이트가 되니 실제 셋업 전엔 공식문서를 한번 더 확인하시길 바래요.