Claude Code 개발 가이드 - 효과적으로 AI와 협업하는 법
Claude Code는 강력한 도구다. 하지만 도구는 잘 써야 제 값을 한다. 그냥 "이거 만들어줘"라고 던지면 어떻게든 결과물이 나오긴 하지만, 품질은 보장할 수 없다.
이 가이드는 Claude Code와 효과적으로 협업하기 위한 전략들을 정리한 것이다. 실제 개발 과정에서 겪은 시행착오를 바탕으로, 무엇이 효과적이고 무엇이 비효율적인지를 담았다.
핵심 원칙
Claude Code를 잘 활용하려면 세 가지를 기억하면 된다:
- 역할을 분리하라 - Claude Code는 코드를 작성하고, 개발자는 환경을 관리한다
- 명시적으로 요청하라 - 암묵적인 기대는 금물. 원하는 걸 정확히 말해야 한다
- 단계를 나눠라 - 개발, 검토, 리뷰를 한 번에 하려 하지 말고 분리한다
프로젝트 설정
CLAUDE.md 작성하기
Claude Code는 프로젝트 루트에 있는 CLAUDE.md 파일을 읽어서 프로젝트 특성을 이해한다. 이 파일에 프로젝트의 규칙과 가이드를 명시해두면 Claude Code가 일관된 방식으로 작업할 수 있다.
필수 항목
## Commands
개발 서버 실행, 빌드, 테스트 명령어를 명시한다.
## Architecture
프로젝트의 전체 구조와 주요 디렉토리 설명을 담는다.
## Development Server
개발 서버가 이미 실행 중이라면 명시해둔다. Claude Code가 불필요하게 서버를 재시작하는 걸 막을 수 있다.
## Server Logs
로그 파일 위치를 명시하면 Claude Code가 디버깅할 때 알아서 로그를 확인한다.
코딩 컨벤션
프로젝트의 코드 스타일, 변수명 규칙, 파일 구조 등을 정의한다. 예를 들어:
## Code Conventions
- 변수명은 camelCase
- 컴포넌트 파일명은 PascalCase
- API 모듈 파일명은 반드시 `*Api.ts`로 끝남
- 데이터베이스 테이블명은 단수형
용어 정의
프로젝트에서 사용하는 핵심 용어들을 명확하게 정의한다. 특히 비슷한 의미의 용어가 여러 개 있을 때 혼란을 방지할 수 있다.
## Terminology
- Canvas: 실제 드로잉이 일어나는 HTML Canvas 요소
- Viewport: Canvas를 감싸는 스크롤 가능한 영역
- WorkspaceContainer: Viewport와 도구 모음을 포함하는 전체 작업 영역
주의: workspace, work area 등의 용어는 사용하지 않음
👉 자세히 보기: Claude Code와 개발할 때 용어 통일이 중요한 이유
도메인 특화 규칙
DDD, 특정 프레임워크, 아키텍처 패턴을 사용한다면 명시해둔다.
## DDD Guidelines
- HTTP controller는 단순히 Application Service를 호출만 함
- 복잡한 비즈니스 로직은 Application Service 레이어에 구현
MCP 설정하기
Model Context Protocol(MCP)을 통해 Claude Code에 추가 기능을 제공할 수 있다. 특히 Playwright MCP는 브라우저 자동화에 유용하다.
Playwright로 UI 검증
Playwright MCP를 활성화하면 Claude Code가 브라우저를 직접 제어해서 UI를 검증할 수 있다.
핵심은 구체적인 수치 기반 조건을 제공하는 것이다. "잘 정렬되어야 해" 대신 "상단 경계가 일치하고, 간격은 24px"처럼 말하면 정확한 결과를 얻는다.
const sidebar = await page.locator('.sidebar').boundingBox();
const mainContent = await page.locator('.main-content').boundingBox();
console.log('Sidebar:', sidebar);
console.log('Main Content:', mainContent);
console.log('Top alignment diff:', Math.abs(sidebar.y - mainContent.y));
console.log('Gap between elements:', mainContent.x - (sidebar.x + sidebar.width));
Claude Code는 로그를 확인하고 조건에 맞지 않는 부분을 스스로 수정한다.
개발 환경 설정
Claude Code와 함께 개발할 때 가장 먼저 해야 할 일은 개발 환경을 제대로 세팅하는 것이다.
서버는 직접 실행하라
Claude Code에게 서버를 실행하도록 시키지 말고, nodemon이나 스크립트를 통해서 직접 실행해두는 게 좋다. 그래야 브라우저를 열어두고 실시간으로 변경사항을 확인하면서 개발할 수 있다.
로그는 파일로 남겨라
서버 로그를 파일로 리다이렉트해두면 Claude Code가 필요할 때 로그를 읽어서 디버깅할 수 있다. CLAUDE.md에 로그 파일 위치를 명시해두면 더 좋다.
변수명을 명확하게 지어라
Claude Code는 변수명을 보고 의도를 파악한다. 비슷한 이름의 변수가 여러 개 있으면 혼동해서 잘못된 변수를 참조할 수 있다. userCount와 userTotal 대신 activeUserCount와 totalRegisteredUsers처럼 명확하게 짓자.
👉 자세히 보기: Claude Code로 개발할 때 알아두면 좋은 팁들
복잡한 코드 디버깅
간단한 기능은 잘 만들어주는데, 복잡한 페이지에서 버그가 계속 발생할 때가 있다. 이럴 때는 바로 수정에 뛰어들지 말고 한 발 물러서야 한다.
문서화 먼저
복잡한 버그를 만났을 때는 먼저 Claude Code에게 현재 구현된 기능, 컴포넌트 구조, 데이터 흐름을 문서로 정리해달라고 하자. 문서화 과정에서 Claude Code도 전체 구조를 다시 파악하게 되고, 개발자도 현재 상태를 명확하게 이해할 수 있다.
설계원칙 기반 검토
문서가 만들어지면 설계원칙에 맞춰 검토를 요청한다. 간결함, 모듈 분리, 가독성 같은 기본 원칙에 비추어 현재 코드를 점검하면 구조적인 문제점들이 드러난다.
👉 자세히 보기: Claude Code로 복잡한 페이지 디버깅하기
용어 및 명명 관리
프로젝트가 진행되면서 비슷한 의미의 용어들이 난립하면 Claude Code도, 개발자도 헷갈린다. workspace, work area, viewport, pane 같은 용어들이 섞여 쓰이면 버그의 원인이 된다.
용어 혼란의 문제
"workspace 컴포넌트 수정해줘"라고 하면 Claude Code는 WorkspaceContainer를 수정한다. 아니라고 하면 WorkArea를 고친다. 서로 대화가 안 통하면서 삽질이 시작된다.
용어 사전 만들기
프로젝트에서 헷갈리는 용어들을 발견하면 즉시 Claude Code에게 정리를 요청하자.
지금 우리 프로젝트에서 workspace, work area, viewport, pane 같은 용어들이 섞여서 쓰이고 있어.
각 용어가 정확히 뭘 의미하는지 정리하고, 앞으로는 통일된 용어만 사용하자.
용어 사전을 만들어줘.
Claude Code는 현재 코드베이스를 분석해서 각 용어의 정확한 의미를 정리하고, 중복되거나 애매한 용어들을 통합해준다. 이 용어 사전은 주요 파일의 주석이나 CLAUDE.md에 남겨두면 된다.
초반부터 용어 정의하기
프로젝트를 시작할 때 핵심 용어들을 먼저 정의하면 나중에 몇 시간씩 삽질하는 걸 막을 수 있다.
이 프로젝트에서 사용할 핵심 용어들을 먼저 정의하고 시작하자.
UI 구조에서 각 영역을 어떻게 부를지, 데이터 구조에서 각 개념을 어떻게 명명할지 정리해줘.
10분 투자해서 용어를 정리하면 몇 시간의 삽질을 막는다.
👉 자세히 보기: Claude Code와 개발할 때 용어 통일이 중요한 이유
에이전트 활용 전략
서브 에이전트로 병렬 작업
Claude Code의 서브 에이전트 기능을 활용하면 개발과 리뷰를 동시에 진행할 수 있다.
개발 에이전트는 다음 작업을 진행하고, 리뷰 에이전트는 방금 작성된 코드를 검토한다. 개발 속도를 유지하면서도 품질을 챙길 수 있는 방법이다.
메모리 관리
복잡한 프로젝트에서는 Claude Code의 메모리를 효과적으로 관리하는 게 중요하다. 중요한 결정사항이나 설계 원칙은 CLAUDE.md에 명시하고, 임시 작업 사항은 별도 에이전트에서 처리하는 식으로 분리하면 컨텍스트가 깔끔하게 유지된다.
코드리뷰
개발이 끝났다고 작업이 끝난 게 아니다. 코드리뷰까지 해야 진짜 끝이다.
왜 코드리뷰가 필요한가
Claude Code가 개발을 진행할 때는 "문제 해결 모드"로 동작한다. 에러가 나면 고치고, 기능이 필요하면 구현한다. 이 과정에서 지엽적인 문제에 집중하기 때문에, 전체적인 설계 결함이나 구조적 문제를 놓치기 쉽다.
명시적으로 리뷰 요청
개발이 끝나면 명시적으로 코드리뷰를 요청하자. "방금 작성한 코드를 전체적으로 리뷰해줘. 설계상 문제점이나 개선할 부분이 있는지 확인해줘." 이렇게 요청하면 Claude Code가 모드를 전환해서 전체적인 관점으로 코드를 검토한다.
서브 에이전트 활용
가능하다면 서브 에이전트를 띄워서 코드리뷰를 병렬로 수행하는 것도 좋다. 개발 에이전트는 다음 작업을 진행하고, 리뷰 에이전트는 방금 작성된 코드를 검토한다. 개발 속도를 유지하면서도 품질을 챙길 수 있다.
👉 자세히 보기: Claude Code로 개발했다면, 코드리뷰는 필수다
테스트 전략
테스트 문서 먼저
브라우저로 테스트를 많이 하는 기능을 개발할 때는 테스트 시나리오를 먼저 작성하게 하자. 정상 케이스, 에러 케이스, 엣지 케이스를 체크리스트 형태로 정리하면, 개발 후에 체계적으로 검증할 수 있다.
Playwright로 UI 검증
Claude Code는 Playwright MCP를 통해 브라우저를 직접 제어할 수 있다. "잘 정렬되어야 해" 같은 모호한 표현 대신 "상단 경계가 일치해야 하고, 간격은 24px"처럼 수치 기반으로 조건을 부여하면 정확한 결과를 얻을 수 있다.
👉 자세히 보기: Claude Code로 개발할 때 알아두면 좋은 팁들
프로젝트 구조 설계 원칙
Claude Code와 작업할 때는 프로젝트 구조가 더 중요하다. 사람은 맥락을 보고 추론하지만, AI는 명시적인 구조에 의존하기 때문이다.
간결함 우선
같은 기능이라면 사람이 이해하기 쉬운 간결한 아키텍처로 구현한다. 과도한 추상화나 불필요한 패턴은 Claude Code를 혼란스럽게 만든다.
모듈 분리
중복된 코드를 제거하고, 각 모듈이 분리된 역할을 수행하도록 설계한다. 한 파일이 여러 책임을 지면 Claude Code가 수정할 때 의도하지 않은 부분까지 건드릴 수 있다.
가독성
코드를 읽어내려가면서 구현 흐름과 프로세스를 직관적으로 이해할 수 있어야 한다. 변수명, 함수명, 파일 구조 모두 명확하게 만든다.
복잡한 페이지를 개발할 때 이 원칙들에 맞춰 검토를 요청하면, 구조적인 문제점들이 드러난다.
워크플로우 정리
효과적인 Claude Code 협업 워크플로우는 다음과 같다:
- 프로젝트 설정 - CLAUDE.md 작성, 용어 정의, MCP 설정
- 개발 환경 준비 - 서버 실행, 로그 설정, 브라우저 준비
- 개발 - 기능 구현, 테스트 시나리오 작성, Playwright 검증
- 문서화 - 복잡한 기능은 문서로 정리해서 구조 파악
- 설계 검토 - 설계 원칙에 맞춰 코드 검토 요청
- 코드리뷰 - 명시적으로 리뷰 모드 전환해서 전체 검토
- 배포 - 최종 확인 후 배포
각 단계를 명확히 분리하고, 한 번에 하나씩 진행하는 게 핵심이다.
정리
Claude Code와 잘 협업하려면 도구의 특성을 이해해야 한다. 개발 중에는 지엽적인 문제 해결에 집중하고, 리뷰 단계에서 전체적인 관점을 확보한다. 복잡한 상황에서는 문서화를 통해 구조를 명확히 한다.
프로젝트 초기 설정에 시간을 투자하고, 용어를 명확하게 정의하고, 단계를 분리해서 작업하면 Claude Code는 강력한 협업 파트너가 된다.
이 가이드에서 소개한 방법들은 모두 실제 개발 과정에서 검증된 것들이다. 하나씩 적용해보면서 자신만의 워크플로우를 만들어가면 된다.
관련 글
- Claude Code로 개발할 때 알아두면 좋은 팁들 - 개발 환경 설정, Playwright 활용
- Claude Code로 복잡한 페이지 디버깅하기 - 문서화 전략
- Claude Code로 개발했다면, 코드리뷰는 필수다 - 코드리뷰의 중요성
- Claude Code와 개발할 때 용어 통일이 중요한 이유 - 용어 관리 전략