Claude Code 사용법, 설치부터 권한·MCP·테스트까지

◆ Claude Code는 일반 AI 채팅과 무엇이 다를까

일반 AI 채팅에서 코드를 물으면 답변으로 코드 조각을 받아 사용자가 직접 파일에 옮기는 경우가 많습니다. Claude Code는 프로젝트 안의 파일을 직접 읽고 관계를 파악한 뒤 필요한 파일을 수정하고 명령을 실행하는 방식이 중심입니다.

예를 들어 “로그인 실패 원인을 찾아 테스트를 추가하고 고쳐줘”라고 요청하면 관련 파일을 탐색하고 수정 계획을 세운 뒤 코드와 테스트를 함께 다룰 수 있습니다. 개발자는 결과와 변경 내용을 검토하면서 방향을 조정합니다.

이 도구는 자동완성 도구라기보다 작업 단위를 맡기는 에이전트에 가깝습니다. 작은 함수 수정부터 여러 파일을 건드리는 리팩터링, 테스트 실행, Git 작업까지 이어갈 수 있다는 점이 핵심입니다.

◆ 설치는 운영체제에 맞는 공식 방법을 쓴다

현재 공식 안내는 macOS와 Linux에서 설치 스크립트, Windows PowerShell에서 전용 설치 명령, Homebrew와 WinGet 같은 패키지 관리 방식도 제공합니다. 설치 방식은 바뀔 수 있으므로 오래된 블로그의 명령보다 공식 문서를 우선하는 것이 좋습니다.

macOS와 Linux에서는 `curl -fsSL https://claude.ai/install.sh | bash` 방식이 안내되고, Windows PowerShell에서는 `irm https://claude.ai/install.ps1 | iex` 방식을 사용할 수 있습니다.

설치가 끝나면 작업할 프로젝트 폴더로 이동한 뒤 `claude`를 실행합니다. 처음 실행에서는 Claude 계정이나 Anthropic Console 계정 등 사용할 인증 방식을 선택합니다.

설치한 명령이 실행되지 않으면 먼저 설치 경로와 셸 설정을 확인합니다. 버전과 설치 상태를 점검하는 공식 진단 명령도 제공되므로 오류가 생기면 무작정 재설치하기보다 진단 결과부터 보는 편이 좋습니다.

◆ 처음에는 코드베이스 설명부터 시킨다

새 프로젝트에서 바로 코드를 수정하게 하기보다 먼저 구조를 설명하게 하는 것이 안전합니다. “이 프로젝트의 주요 폴더와 실행 흐름을 설명해줘”처럼 요청하면 어떤 파일을 읽는지와 프로젝트 이해 수준을 확인할 수 있습니다.

그다음 작은 읽기 전용 작업을 시도합니다. 특정 함수가 어디에서 호출되는지 찾거나 오류 로그와 관련된 파일을 추적하게 하면 에이전트가 코드베이스를 어떻게 탐색하는지 파악하기 쉽습니다.

사용 초반에는 큰 기능 구현보다 작은 버그 수정과 테스트 추가처럼 결과를 검증하기 쉬운 작업이 좋습니다. 변경 파일 수가 적을수록 잘못된 방향을 빠르게 발견할 수 있습니다.

◆ 계획을 먼저 보고 수정하게 하면 안전하다

복잡한 작업에서는 바로 파일을 고치게 하기보다 계획을 먼저 요청합니다. 어떤 파일을 변경할지, 왜 수정해야 하는지, 어떤 테스트로 확인할지 설명하게 하면 위험한 변경을 줄일 수 있습니다.

권한과 실행 모드를 조정하면 읽기 중심으로 탐색한 뒤 실제 수정 단계로 넘어가는 흐름을 만들 수 있습니다. 특히 익숙하지 않은 코드베이스에서는 계획 확인이 중요합니다.

계획이 지나치게 크다면 작업을 쪼갭니다. “데이터베이스 구조 변경과 UI 수정, 테스트 작성”을 한 번에 맡기기보다 각 단계가 끝날 때마다 검토하면 오류 원인을 추적하기 쉽습니다.

◆ 권한 요청은 이유를 확인하고 승인한다

Claude Code는 파일 변경이나 명령 실행처럼 시스템에 영향을 주는 작업에서 권한 확인을 거칩니다. 어떤 명령을 왜 실행하려는지 확인한 뒤 승인하는 습관이 중요합니다.

패키지 설치, 파일 삭제, 배포, 데이터베이스 명령처럼 결과가 큰 작업은 특히 주의해야 합니다. 익숙하지 않은 명령은 승인 전에 내용을 확인하고, 필요하면 먼저 설명해 달라고 요청합니다.

권한을 건너뛰는 옵션도 존재하지만 일상적인 개발에서 기본값처럼 사용하는 것은 권장되지 않습니다. 자동화 속도보다 변경 범위를 통제하고 되돌릴 수 있는 상태를 유지하는 것이 더 중요합니다.

실제 서비스 저장소에서 사용할 때는 작업 전 브랜치를 만들고 Git 상태를 깨끗하게 유지하면 변경 내용을 비교하고 복구하기 쉽습니다.

◆ 테스트까지 맡겨야 코딩 에이전트 장점이 살아난다

코드를 수정한 뒤 결과만 읽고 끝내면 사람이 직접 코드를 붙여넣는 방식과 큰 차이가 없습니다. 에이전트형 도구의 장점은 수정 후 테스트와 정적 검사까지 같은 흐름에서 실행할 수 있다는 점입니다.

에이전트에게 “변경 후 관련 단위 테스트와 타입 검사를 실행하고 실패하면 원인을 설명해줘”처럼 검증 조건을 함께 줄 수 있습니다.

테스트가 없는 프로젝트라면 버그를 고치기 전에 재현 테스트부터 작성하게 하는 것도 좋습니다. 수정 전에는 실패하고 수정 후에는 통과하는 테스트가 있으면 변경의 효과를 확인하기 쉽습니다.

테스트가 통과해도 실제 요구사항을 만족하는지는 사람이 최종 검토해야 합니다. 자동 테스트가 커버하지 못하는 UI, 데이터 손실, 권한 문제는 별도 확인이 필요합니다.

◆ CLAUDE.md에는 프로젝트 규칙을 짧게 모은다

반복해서 알려줘야 하는 프로젝트 규칙은 CLAUDE.md 같은 프로젝트 지침 파일에 정리하면 편합니다. 빌드 명령, 테스트 방식, 폴더 규칙, 금지된 변경, 코드 스타일처럼 작업마다 반복되는 정보를 넣을 수 있습니다.

너무 긴 설명을 모두 넣기보다 실제 작업에 영향을 주는 규칙만 유지하는 것이 좋습니다. 오래된 명령이나 더 이상 쓰지 않는 구조가 남아 있으면 에이전트가 잘못된 방향으로 작업할 수 있습니다.

에이전트가 자주 틀리는 부분을 발견하면 대화마다 길게 설명하기보다 프로젝트 지침을 업데이트해 재발을 줄이는 방식이 효율적입니다.

◆ MCP는 외부 도구와 연결할 때 사용한다

MCP는 코딩 에이전트가 외부 시스템과 상호작용할 수 있도록 기능을 확장하는 방법입니다. GitHub, 데이터베이스, 문서 서비스, 내부 도구처럼 필요한 시스템을 연결해 프로젝트 밖의 정보와 작업을 활용할 수 있습니다.

모든 연결을 처음부터 추가할 필요는 없습니다. 현재 개발 작업에서 실제로 필요한 도구만 연결하고, 각 MCP 서버가 어떤 권한과 데이터에 접근하는지 확인하는 것이 중요합니다.

CLI에는 MCP 설정을 위한 명령이 있으며, 연결 뒤에는 실제로 필요한 범위만 허용했는지 점검합니다. 외부 서비스 토큰과 비밀값은 저장소에 직접 넣지 말고 별도 보안 방식으로 관리해야 합니다.

◆ 터미널이 불편하면 웹과 IDE에서도 쓸 수 있다

Claude Code는 터미널 전용 도구로 시작했지만 현재는 여러 환경에서 사용할 수 있습니다. VS Code와 JetBrains 확장, 데스크톱 앱, 웹, GitHub와 Slack 같은 방식이 제공됩니다.

웹에서는 GitHub 저장소를 선택하고 작업을 맡긴 뒤 브라우저를 닫아도 원격 환경에서 계속 실행되도록 할 수 있습니다. 완료되면 변경 사항을 검토할 수 있는 풀 리퀘스트를 생성하는 흐름도 지원합니다.

로컬 개발 환경과 직접 연결된 수정이 필요하면 터미널이나 IDE가 편하고, 오래 걸리는 작업이나 여러 저장소를 병렬로 맡기고 싶다면 웹 실행이 유용할 수 있습니다.

어떤 환경에서 사용하든 최종 변경은 diff와 테스트 결과를 확인한 뒤 병합하는 원칙은 같습니다.

◆ Pro·Max와 API 사용은 비용 구조가 다르다

개인 사용자는 Claude Pro와 Max 플랜에 포함된 Claude Code 사용량을 이용할 수 있습니다. 공식 제품 페이지는 Pro를 작은 코드베이스의 짧은 코딩 작업에, Max를 더 큰 코드베이스와 잦은 사용에 적합한 선택지로 설명합니다.

Anthropic Console 계정으로 사용하면 API 토큰 사용량에 따라 과금될 수 있습니다. 구독 플랜에 포함된 사용량과 API 과금은 같은 개념이 아니므로 자신의 로그인 방식과 결제 방식을 확인해야 합니다.

대형 코드베이스와 긴 에이전트 작업은 사용량이 빠르게 늘 수 있습니다. 한 번에 너무 넓은 범위를 맡기기보다 작업을 작게 나누고 불필요한 파일 탐색을 줄이는 것이 비용과 검토 시간을 함께 줄이는 데 도움이 됩니다.

◆ 자주 묻는 질문

Q. Claude Code는 코딩을 몰라도 사용할 수 있나요?

　A. 자연어로 작업을 지시할 수 있지만 실제 코드 변경을 검토하고 테스트 결과를 판단하려면 기본적인 개발 지식이 필요합니다. 완성된 코드를 무검토로 배포하는 방식은 권장되지 않습니다.

Q. Windows에서도 설치할 수 있나요?

　A. 가능합니다. 현재 Windows용 PowerShell 설치와 WinGet 방식이 안내되며, WSL 환경에서도 사용할 수 있습니다. 설치 방식은 바뀔 수 있으므로 공식 설치 문서를 기준으로 확인하는 것이 좋습니다.

Q. Cursor와 Claude Code 중 무엇이 더 좋은가요?

　A. 작업 방식이 다릅니다. Cursor는 에디터 안에서 자동완성과 시각적 편집을 자주 사용하는 개발자에게 편하고, Claude Code는 터미널과 프로젝트 전체를 활용해 작업 단위를 에이전트에게 맡기는 흐름에 잘 맞습니다.

Q. 권한 요청을 모두 자동 승인해도 되나요?

　A. 권장되지 않습니다. 파일 삭제, 패키지 설치, 배포, 운영 데이터 접근처럼 영향이 큰 작업은 실행 명령과 범위를 확인한 뒤 승인하는 것이 안전합니다.

◆ 공식 문서에서 확인할 설치와 사용 기준

Anthropic 공식 제품 페이지는 Claude Code가 터미널, IDE, 웹, 데스크톱 등에서 사용할 수 있고 코드베이스를 탐색해 기능 구현, 버그 수정, 테스트와 풀 리퀘스트 작업까지 수행할 수 있다고 설명합니다. 현재 Pro와 Max 같은 개인 플랜에도 Claude Code 사용량이 포함됩니다.

공식 사용자 FAQ는 macOS·Linux 설치 스크립트, Windows PowerShell, Homebrew, WinGet 같은 설치 방법을 안내하고 있으며, 설치 뒤 프로젝트 폴더에서 `claude`를 실행해 시작하는 흐름을 설명합니다.

공식 자료: Anthropic Claude Code 공식 제품 안내

공식 자료: Claude Code 공식 사용자 FAQ

© pick.wi-th.com