Claude Code 사용기

김주엽·2025년 10월 2일
0
post-thumbnail

🧑‍💻 들어가며

요즘에는 Claude Code, Codex CLI, Gemini CLI, Cursor CLI 등 다양한 코딩 에이전트 툴들이 많이 개발되는 것 같다. 그 중에서 나는 Claude Code를 사용해서 개인 프로젝트에 활용해봤다.

이번 글에서는 Claude Code가 뭔지 간단히 소개하고, 내가 어떤 방식으로 사용했는지 그리고 직접 사용하면서 느낀 후기를 정리해보려고 한다.


🚀 Claude Code란?

Claude Code는 Anthropic에서 만든 코딩 에이전트 툴이다.
일반적인 코드 어시스턴트와 달리, 단순히 코드 스니펫을 제안하는 수준이 아니라 프로젝트 전체를 이해하고 파일을 수정하거나 커밋까지 생성할 수 있다는 점이 특징이다.

특징을 간단히 정리하면:

  • 프로젝트 맥락(Context) 이해 → 단순 코드 조각이 아니라 파일 단위로 수정
  • 행동(Action) 지원 → 명령어 실행, 파일 편집, 커밋 생성 가능
  • MCP 확장성 → GitHub, Slack, Figma 같은 외부 도구와 연동 가능

아직은 한계가 분명하지만, 기존에 내가 경험했던 Copilot이나 코딩 보조 툴이랑 확실히 결이 달랐다.


🛠 사용한 방식

나는 Claude Code를 역할별 서브 에이전트와 커스텀 명령어 작성해서 이를 중심으로 활용했다.

역할별 서브 에이전트

처음부터 모든 걸 하나의 Claude에게 맡기지 않고, 역할을 나눠서 서브 에이전트로 정의했다.

프로젝트에 사용된 전체 서브 에이전트는 다음과 같다:

에이전트 이름전문 분야주요 역할
product-manager프로젝트 기획요구사항 분석, 사용자 스토리, 로드맵 계획
github-managerGitHub 관리이슈/PR 관리, 브랜치 전략, 커밋 컨벤션
testing-engineer테스팅 전략Kotlin/Spring 테스트 코드, 커버리지 분석
backend-engineer백엔드 아키텍처아키텍처 설계, 도메인 모델링, 비즈니스 로직 구현
api-developerREST APIAPI 설계, OpenAPI 문서화, 응답 모델링
database-schema-engineer데이터베이스 설계PostgreSQL/JPA 스키마, Flyway, Redis 캐싱
prompt-engineerAI 프롬프트프롬프트 설계 및 성능 개선

예를 들어 testing-engineer는 다음과 같이 정의했다.

---
name: testing-engineer
description: Spring Boot + Kotlin 애플리케이션의 테스팅 전문가. 헥사고날 아키텍처 테스팅에 중점을 둔 테스트 자동화, 커버리지 분석, 품질 보증 전략에 특화. 테스트 관련 작업에 적극적으로 활용하세요.
model: sonnet
---

Spring Boot + Kotlin 애플리케이션을 위한 포괄적인 테스팅 전략을 전문으로 하는 테스팅 엔지니어입니다.

## 전문 분야
- Kotlin용 Kotest, MockK 테스팅 프레임워크
- Kover 코드 커버리지 분석 및 리포팅
- 통합 테스트를 위한 TestContainers
- 헥사고날 아키텍처 테스팅 전략
- Spring Boot 테스트 슬라이스(@WebMvcTest, @DataJpaTest)
- 성능 테스팅 및 부하 테스트 접근법

## 접근 방식
1. 도메인 우선 테스팅을 통한 테스트 주도 개발
2. 포괄적인 테스트 피라미드(단위, 통합, E2E)
3. Port/Adapter 격리를 통한 헥사고날 아키텍처 테스팅
4. TestContainers를 활용한 컨테이너 기반 통합 테스트
5. 200ms 미만 응답 요구사항에 대한 성능 벤치마킹
6. CI/CD 파이프라인에서의 자동화된 테스팅

## 산출물
- 적절한 Assertion을 포함한 Kotest + BehaviorSpec 테스트 스위트
- PostgreSQL/MySQL, Redis, Kafka 등 테스트를 위한 TestContainers 설정
- 80% 이상의 코드 커버리지 요구사항을 위한 Kover 설정
- 외부 종속성 및 Adapter에 대한 Mock 전략
- 자동화된 테스트 실행을 위한 CI 통합

클린 아키텍처 원칙을 지원하고 안정적인 애플리케이션 품질을 보장하는 포괄적인 테스트 전략에 중점을 둡니다.
사용자와의 대화는 한국어로 진행하되, 코드, 설정, 기술 문서는 표준 영어 관례를 따릅니다.

이렇게 역할을 명확하게 정의해 두니 Claude Code가 훨씬 일관성 있게 동작했다.

커스텀 명령어

GitHub 이슈를 기반으로 /task <이슈번호>라는 명령어를 만들어서 Plan 모드와 함께 사용했다.
명령어를 입력하면 Claude Code가 해당 이슈에 맞는 개발을 진행하도록 했다.

덕분에 “AI와 대화하다가 갑자기 코드 작성”이 아니라 명확한 흐름 속에서 코드를 만들어낼 수 있었다.

task 커스텀 명령어는 다음과 같이 작성했다.

---
argument-hint: [issue-number] [additional-instructions]
description: Execute development workflow from issue
---

# Development Task Workflow

Follow this development workflow for all feature implementations. All work and responses must be in Korean.

## Development Workflow

1. **Issue Analysis**
    - Review GitHub issue #$1 requirements and acceptance criteria
    - Understand the technical scope and dependencies

2. **Branch Management**
    - Create branches from `main` using @github-manager agent
    - Use descriptive branch names that reflect the feature being implemented

3. **Development Process**
    - Start development by updating GitHub project status to "In Progress"
    - Proceed with development using @agents that are appropriate for the given situation
    - Use Context7 tools. If Context7 is not available, provide guidance to the developer before starting development

4. **Developer Review (Pre-Commit)**
    - **MANDATORY**: Present completed work to the developer for review before any commits
    - Provide comprehensive summary of changes made:
        - Files modified and new files created
        - Key implementation decisions and rationale
        - Test coverage and validation performed
        - Architecture compliance verification
    - Wait for developer approval before proceeding to commit stage
    - Address any feedback or concerns raised during review

5. **Commit Standards** (After Developer Approval)
    - Use github-manager agent
    - Only proceed after receiving developer approval from step 4

6. **Code Push**
    - Push branches to remote repository
    - Ensure all tests pass before pushing: `./gradlew test`

7. **Pull Request Creation**
    - Create PR with descriptive title matching commit convention
    - Use team PR template(`.github/pull_request_template.md`): Follow the standardized PR template for consistent documentation
    - Update GitHub project status to "In Review"

$2

MCP 활용

추가로 context7, sequential-thinking 같은 다양한 MCP 서버를 함께 사용했다.

  • github: 코드 레벨의 이슈, PR, 브랜치 관리
  • context7: 개발 관련 문서 학습
  • sequential-thinking: 복잡한 문제를 단계별로 나눠서 처리
  • obsidian: 프로젝트 관련 문서 조회 및 관리

이런 도구들을 곁들이니 문맥이 길어져도 어느 정도 안정적으로 이어갈 수 있었다.


😎 사용 후기

코딩 방식이 달라졌다

기존에는 프로그래머가 처음부터 코드를 짜고 테스트하고 수정하는 흐름이었다면,
Claude Code를 쓰면서는 AI가 코드를 쓰고 내가 리뷰·보완하는 흐름으로 바뀌었다.

이제 중요한 건 코드를 짤 줄 아는 능력보다는, AI가 짠 코드를 이해하고 올바른 방향으로 교정하는 능력이 될 것 같다는 생각이 들었다.
즉, 코딩 경험과 이론 지식의 중요성이 오히려 더 커졌다.

장점

  • 개발 속도가 월등히 빨라졌다
  • 반복적인 CRUD나 보일러플레이트 코드에서 해방
  • MCP와 서브 에이전트 덕분에 문서화와 일관성이 강화됨
  • 커밋과 PR 작성과 같은 작업을 프롬프트나 커스텀 명령어를 통해 간단하게 작성 가능

단점

  • 대규모 컨텍스트 관리의 한계
    → 길게 작업하면 지침을 잊거나, 개발 지침을 무시하는 경우가 종종 발생
  • 문서 업데이트 부담
    → CLAUDE.md와 서브 에이전트 문서를 수시로 관리해야 안정적
  • Pro 플랜 한계
    → 생각보다 사용량 제한에 자주 걸려서 불편
  • 간혹 발생하는 품질 저하(?)
    → 이유는 모르겠으나 가끔 Claude Code의 성능이 저하되거나 이상하게 개발하는 성향이 체감상 있었다.

    👉 최근 있었던 Claude 품질 저하 이슈


📌 배운 점

  • Claude Code가 작성한 코드들은 항상 의심하고 관찰해야 한다.
  • CLAUDE.md, 서브 에이전트 문서에 역할·책임·기술 스택·지침을 명확하게 써야 한다.
  • 그렇지 않으면 Claude는 자유롭게 해석해버려서 결과물이 뒤죽박죽 된다.
    • 이 경우 개발자가 직접 처음부터 코딩하는 방식보다 시간이 더 오래 걸릴 수도 있다.
  • 사람이 코딩을 직접 덜 하게 되더라도 설계·문서화·리뷰 역량은 더욱 중요해진다.
  • Claude Code가 생성한 코드들이 별로라면 과감하게 삭제하고 다시 개발하는 것이 매우 중요하다.
  • AI가 만든 코드에 숨어있는 논리적인 오류나 미묘한 버그를 빨리 찾아내고 코드의 흐름을 추적하려면, 디버깅 스킬이 점점 중요해질 것이라는 생각이 들었다.

🎉 마무리

Claude Code를 쓰면서 개발자의 역할이 점점 바뀌고 있다는 걸 강하게 느꼈다.
이제는 모든 걸 직접 짜기보다는, AI가 만들어낸 코드를 리뷰하고 방향을 제시하는 쪽으로 무게중심이 이동하고 있다.

아직 부족한 부분도 많지만, 개발에 Claude Code를 사용해보니 확실히 개발 생산성은 높아졌고 문서화도 강화된 것 같다.

추후 기술이 발전되고 대규모 컨텍스트에 대한 처리가 이뤄진다면 그때는 또 개발 방식이 어떻게 변할지 궁금하다!

profile
나야 루이지

0개의 댓글