터미널 안의 자율 코딩 비서, Claude Code 제대로 쓰는 법: 설치부터 실무 워크플로우까지

ChatGPT나 Claude 웹 채팅창에 코드를 복사-붙여넣기 하던 시절을 지나, 이제는 Cursor 같은 AI 기반 IDE가 익숙해졌습니다. 하지만 Anthropic이 공개한 Claude Code(클로드 코드)는 여기서 한 걸음 더 나아갑니다.

Claude Code는 단순한 코드 자동 완성이 아닙니다. 터미널에서 직접 실행되어 파일 탐색, 코드 읽기/수정, 터미널 명령어 실행, git 커밋 및 테스트 통과까지 스스로 판단하고 수행하는 '자율 에이전트(Autonomous Agent)'입니다.

이번 글에서는 Claude Code를 로컬 환경에 설치하고, 실무 프로젝트에서 생산성을 3배 이상 끌어올리는 핵심 활용 팁과 워크플로우를 정리합니다.

---

1. Claude Code 설치 및 기본 세팅

Claude Code는 Node.js 환경에서 npm을 통해 손쉽게 설치할 수 있습니다.

(1) 글로벌 설치

npm install -g @anthropic-ai/claude-code

(2) 프로젝트 폴더로 이동 및 실행

작업할 프로젝트 루트 디렉토리로 이동한 뒤 실행합니다:

cd ~/my-project
claude

• 최초 실행 시 Anthropic 콘솔을 통한 브라우저 OAuth 인증(또는 API 키 입력) 창이 뜹니다. 인증을 완료하면 터미널에 대화형 프롬프트가 열립니다.

---

2. Claude Code가 일하는 방식 이해하기

Claude Code의 핵심은 "지시 → 계획 수립 → 도구 호출(Tool Calling) → 실행 결과 확인 → 반복"의 루프입니다.

• 파일 읽기 및 검색: grep, glob, 파일 읽기 도구를 사용해 내가 말한 기능과 관련된 코드 위치를 스스로 찾아냅니다.
• 부분 패치(Diff): 파일 전체를 무식하게 덮어쓰지 않고, 필요한 함수나 라인만 정밀하게 수정(Patch)합니다.
• 터미널 실행 및 피드백: 코드를 수정한 뒤 npm test나 pytest를 직접 돌려보고, 에러가 발생하면 에러 로그를 읽고 스스로 코드를 다시 고칩니다.

---

3. 실무 생산성을 좌우하는 핵심 팁

팁 1: 프로젝트 규칙의 핵심, CLAUDE.md 작성하기

Claude Code는 프로젝트 루트에 위치한 CLAUDE.md 파일을 가장 먼저 읽고 프로젝트의 규칙을 파악합니다. 여기에 다음과 같은 내용을 적어두면 매번 지시할 필요가 없습니다.

# Project Guidelines

## Tech Stack
- Next.js 14 (App Router), TypeScript, Tailwind CSS
- Jest, React Testing Library

## Development Rules
- 코드를 수정한 뒤에는 반드시 `npm test`를 실행해 기존 테스트가 깨지지 않았는지 확인할 것.
- 새로운 컴포넌트를 만들 때는 반드시 대응하는 단위 테스트(`.test.tsx`)를 함께 작성할 것.
- 커밋 메시지는 Conventional Commits 규칙(`feat:`, `fix:`, `refactor:`)을 준수할 것.

팁 2: 모호한 요구 대신 '완료 조건(Acceptance Criteria)' 명시하기

• ❌ "로그인 기능 좀 개선해줘"
• ⭕ "카카오 OAuth 로그인 시 이메일이 없는 사용자에 대해 추가 이메일 입력 모달을 띄우는 로직을 추가해줘. 기존 로그인 테스트 케이스가 모두 통과해야 해."

팁 3: Git 워크플로우와 결합하기

작업 전 브랜치를 파두면 에이전트가 수정한 내용을 git diff로 깔끔하게 검토할 수 있습니다:

git checkout -b feature/login-flow
claude
# 작업 완료 후
# Claude 안에서: "방금 작업한 내용으로 커밋 메시지 작성해서 커밋해줘"

---

4. 주의할 점과 한계

1. 토큰 및 비용 관리: 대규모 코드베이스를 한 번에 인덱싱하거나 긴 로그를 출력하게 하면 컨텍스트 토큰이 빠르게 소모됩니다. 검색 범위를 디렉토리 단위로 좁혀주는 것이 좋습니다.
2. 최종 코드 검토(Human in the loop): 에이전트가 테스트를 통과시켰더라도 아키텍처적 일관성이나 보안적 취약점이 없는지 git diff로 개발자가 직접 눈으로 확인하는 과정은 여전히 필수입니다.

---

마치며

Claude Code는 단순한 보조 도구가 아니라 "지치지 않고 테스트를 돌려가며 코드를 완성하는 주니어 개발자" 한 명을 터미널 옆에 앉혀둔 느낌을 줍니다.

다음 글에서는 "CLAUDE.md를 정교하게 설계해 버그 발생률을 0으로 만드는 실전 프롬프트 템플릿"과 "Claude Code에 커스텀 MCP 도구를 연동해 사내 DB 및 슬랙과 연결하는 방법"을 다뤄보겠습니다.