목차
Claude Code가 무엇인지(어디서나 같은 엔진)
설치 방법(공식)
시작하기(첫 실행·로그인·기본 패턴)
주요 사용 환경(surfaces)별 특징
실전 워크플로(프롬프트 예시)
컨텍스트/규칙 관리(CLAUDE.md)
슬래시 명령/기능
권한/보안
확장: MCP 개요와 Desktop Extensions(.mcpb)
문제 해결 체크리스트
참고 링크
Claude Code가 무엇인지
Claude Code는 코드 작성·버그 수정·반복 작업 자동화를 "자연어로 지시"하면서, 실제로는 코드베이스를 읽고 여러 파일을 동시에 바꾸고, 필요하면 명령을 실행하고, Git 워크플로까지 이어가게 만든 에이전트형 코딩 도구다.12
중요한 포인트는 "표면(surface)"이 여러 개여도 내부 엔진은 같은 Claude Code 엔진을 공유한다는 점이다. 터미널에서 시작한 습관(예: 프로젝트의 CLAUDE.md, 설정, MCP 서버 연결)이 VS Code, JetBrains, Desktop, Web에서도 이어진다. 그래서 도구를 "어디서 쓰느냐"는 취향 문제에 가깝고, "무엇을 시키느냐/어떤 규칙을 먹이느냐"가 결과를 좌우한다.1
설치 방법(공식 문서 기준)
아래는 공식 문서에 나온 설치 루트다.12 팀 문서나 온보딩 문서엔 보통 "권장 1개 + 대체 1개"만 남기고 나머지는 링크로 빼는 편이 유지보수에 좋다.
macOS/Linux/WSL(권장):
curl -fsSL https://claude.ai/install.sh | bashWindows PowerShell(권장):
irm https://claude.ai/install.ps1 | iexWindows CMD:
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmdHomebrew:
brew install --cask claude-codeWinGet:
winget install Anthropic.ClaudeCodenpm 설치는 deprecated(비권장/폐기 예정)이다.2
npm install -g @anthropic-ai/claude-code시작하기(첫 실행·로그인·기본 사용 패턴)
프로젝트 폴더로 이동한 뒤 claude를 실행한다.1
cd your-project
claude첫 실행에서는 로그인 프롬프트가 뜬다. 로그인만 끝나면 바로 작업을 시작할 수 있고, 이후에는 보통 "요구사항 정리 → 계획 확인 → 변경 제안(diff) 검토 → 테스트 실행 → 커밋/PR" 순서로 반복하게 된다.12
Claude Code는 대화형 도구라서, 내가 원하는 출력 형태를 초반에 못 박는 게 중요하다. 예를 들어 "먼저 변경 계획을 적고, 그다음 diff로 제안하고, 마지막에 실행한 테스트와 결과를 요약해줘" 같은 식으로 작업 루프를 고정해두면 검토 속도가 빨라진다.
주요 사용 환경(surfaces)별 특징 요약
Terminal CLI는 가장 "원형"에 가깝다. 파일 편집, 명령 실행, 프로젝트 관리까지 터미널에서 끝내는 감각이라 빠르고 단단하다.12 다만 권한 승인 프롬프트가 자주 떠서 흐름이 끊길 수 있으니(뒤에서 보안 원칙과 함께 다룸), 작업 스타일에 맞는 권한 전략이 필요하다.3
VS Code 확장은 에디터 안에서 Claude Code를 다루는 인터페이스를 제공한다. 인라인 diff, @ 멘션(파일/컨텍스트 지칭), 계획(Plan) 리뷰, 대화 히스토리 같은 "검토 친화 기능"이 핵심이다.1
Desktop app은 IDE나 터미널 밖에서 세션을 병렬로 띄우고, 시각적 diff로 변경을 검토하는 데 강점이 있다. 공식 문서에서 "유료 구독 필요"를 명시하고 있으니, 도입 전 라이선스 정책을 먼저 확인하는 게 안전하다.1
Web은 로컬 셋업 없이 브라우저에서 실행한다. 로컬에 레포가 없어도 작업을 걸 수 있고, 오래 걸리는 작업을 걸어두고 나중에 다시 확인하거나, 여러 작업을 병렬로 돌릴 때 유리하다는 포지션이다.1
JetBrains 플러그인은 IntelliJ 계열 IDE에서 인터랙티브 diff 뷰와 컨텍스트 공유를 제공한다. 설치는 JetBrains Marketplace에서 플러그인 설치 후 IDE 재시작 흐름이다.1
실전 워크플로(예시 명령/프롬프트 포함)
아래는 "코드베이스 탐색/요구사항 정리 → 계획(Plan) → 변경 제안(diff) → 테스트/검증 → 커밋/PR"을 기본 골격으로 둔 워크플로다. 실제로는 기능 추가든 버그 수정이든 이 루프를 얼마나 짧게 돌리느냐가 생산성을 결정한다.12
먼저 탐색 단계에서는 "어디를 읽을지"를 지시해주는 게 핵심이다. 특히 큰 저장소에서 그냥 "해줘"라고 하면, 중요한 제약을 놓치거나 불필요한 파일을 읽느라 속도가 느려질 수 있다.
예시 프롬프트(탐색→요구사항 정리):
이 레포에서 로그인 요청이 처리되는 전체 흐름을 설명해줘.
우선 src/auth, src/api, middleware 관련 파일만 훑고,
핵심 엔트리포인트/데이터 흐름/예외 케이스를 짧게 요약해줘.계획(Plan) 단계에서는 "바꾸지 말아야 할 것"과 "검증 방법"을 계획에 포함시키는 게 좋다.
예시 프롬프트(Plan 고정):
목표: 비밀번호 재설정 토큰 만료 시간을 15분으로 변경.
1) 변경 계획을 단계별로 써줘(영향 파일 목록 포함).
2) 보안상 주의점이 있으면 먼저 경고해줘.
3) 마지막에 어떤 테스트/체크로 검증할지 적어줘.
계획 승인 전에는 파일을 수정하지 마.변경 제안(diff) 단계에서는 "diff로만 제안"을 요구하면 검토가 쉬워진다.
예시 프롬프트(diff 중심):
이제 계획대로 수정해줘. 직접 적용하기 전에
각 파일별로 어떤 diff가 생기는지 제안 형태로 보여줘.테스트/검증 단계에서는 "실행할 명령"을 CLAUDE.md에 고정해두면 매번 설명할 필요가 줄어든다(아래 CLAUDE.md 참고). 그래도 세션에서는 다음처럼 요청하는 게 깔끔하다.
로컬에서 가능한 테스트를 실행해줘(빠른 것부터).
실행한 명령과 결과 요약, 실패 시 원인 추정과 다음 액션까지 적어줘.커밋/PR 단계는 팀 규칙에 맞춰 템플릿화하는 게 좋다. Claude Code가 git 워크플로를 다룰 수 있다는 점 자체가 장점이지만,2 실제 운영에서는 "커밋 메시지 규칙, PR 본문 형식, 체크리스트"가 팀마다 다르니 CLAUDE.md로 묶는 편이 안정적이다.
대표 시나리오별 프롬프트 예시를 정리하면 아래 정도가 자주 쓴다.
버그 수정(1~2개):
이 에러 로그를 기준으로 재현 경로를 추정하고,
가장 가능성 높은 원인 2~3개를 코드 위치와 함께 제시해줘.
그 다음, 가장 작은 변경으로 고치는 수정안을 diff로 제안해줘.회귀를 막기 위해 테스트도 추가해줘.
테스트는 실패하는 케이스 → 수정 후 통과하는 케이스가 되게 구성해줘.리팩터링(1~2개):
이 모듈의 책임이 과도하게 섞여있어 보여.
외부 API는 유지하면서 내부 구조만 정리하는 리팩터링 계획을 먼저 써줘.
성능/동작 변경 위험 포인트를 표시해줘.계획 승인. 단계별로 diff를 제안하고,
각 단계마다 컴파일/테스트 명령을 무엇으로 확인할지 같이 적어줘.신규 기능 추가(1~2개):
요구사항: (여기에 요구사항)
기존 구조를 기준으로 설계 옵션 2가지를 제안해줘.
각 옵션의 변경 범위(파일), 위험, 테스트 전략을 비교해줘.옵션 A로 가자. 먼저 최소 동작(MVP)만 구현하고,
기능 플래그로 숨긴 뒤 점진적으로 확장할 수 있게 해줘.
diff로 제안하고, 문서/테스트도 함께 갱신해줘.문서화(1~2개):
이 레포의 개발자 온보딩 문서를 업데이트해줘.
실제로 필요한 순서(설치→실행→테스트)로 재구성하고,
오래되었거나 불명확한 단계는 코드/스크립트를 근거로 고쳐줘.README에 '자주 겪는 문제' 섹션을 추가해줘.
실제 발생 가능한 에러 3개와 해결책을 재현/해결 명령까지 포함해 써줘.컨텍스트/규칙 관리(CLAUDE.md)
CLAUDE.md는 "이 프로젝트에서 Claude가 지켜야 할 규칙과, 바로 실행 가능한 작업 지침"을 담는 살아있는 문서로 보는 게 실용적이다. 여러 surface가 같은 엔진을 쓰기 때문에, 여기 잘 적어두면 터미널이든 IDE든 웹이든 일관된 결과를 얻기 쉽다.1
보통은 프로젝트 개요(무엇을 만드는지), 코드 구조(중요 디렉터리/엔트리), 빌드·테스트 명령, 금지사항(예: 특정 파일은 수동 승인 없이는 수정 금지), 보안 주의점(시크릿 다루기)을 넣는다. "한 번 적고 끝"이 아니라, 시행착오로 얻은 맥락을 계속 축적하는 편이 장기적으로 가장 이득이라는 경험담도 많다.4
큰 저장소에서 컨텍스트를 잘 먹이는 요령은 단순하다. 첫째, 읽을 폴더/파일 범위를 먼저 제한한다. 둘째, 중요한 제약(절대 바꾸면 안 되는 것, 반드시 통과해야 하는 테스트, 운영 환경 가정)을 대화 초반에 가장 먼저 준다. 셋째, 결과물 형식(Plan→diff→test→commit)을 고정한다. 이렇게 하면 "모델이 똑똑하냐"보다 "내가 작업을 잘 쪼갰냐"가 성패를 가른다.
슬래시 명령/기능
공식적으로는 /bug로 버그 리포트를 올릴 수 있다고 안내한다. 문제를 재현하면서 바로 리포트로 이어지게 만들 수 있어서, "불편하지만 설명하기 귀찮은 이슈"를 흘려보내지 않게 해준다.2
다만 슬래시 명령은 버전별로 구성이 바뀔 수 있다. 안전한 습관은 "현재 클라이언트에서 /help로 확인하고 쓰기"다. 문서나 블로그에서 본 명령을 그대로 믿고 자동화에 박아두기보다, 먼저 내 버전에서 동작하는지 확인하는 쪽이 운영 사고를 줄인다.3
비공식 팁으로는 커뮤니티에서 /install-github-app 같은 GitHub 앱 설치 슬래시 명령이 언급되곤 한다.3 하지만 이는 공식 문서에 고정된 계약처럼 보장된다고 보기 어렵고, 조직 정책(권한 범위, 코드/PR 접근)을 건드릴 수 있으니 "테스트 조직/샌드박스 레포에서 먼저 검증" 후 도입하는 편이 안전하다.
권한/보안
Claude Code는 파일 편집이나 명령 실행 같은 "실제 영향이 있는 행동" 전에 권한을 묻는 흐름이 나올 수 있다. 사용성 측면에선 번거롭지만, 실수로 파괴적인 명령이 실행되는 리스크를 줄이는 안전장치이기도 하다.3
claude --dangerously-skip-permissions 같은 옵션은 이름 그대로 위험할 수 있으니, 원칙적으로 비권장이다. "빨리 끝내려고" 켰다가, 레포를 잘못 지정했거나(예: 홈 디렉터리), 스크립트가 운영 자격증명을 물고 있거나, 의도치 않은 삭제/푸시가 일어나면 되돌리기 어렵다. 켜야 한다면 개발자가 책임지고, 최소한 별도 샌드박스/브랜치, 제한된 토큰/자격증명, 실행 명령 allowlist 같은 안전장치를 같이 두는 게 맞다.3
민감정보 수칙은 결국 기본으로 돌아간다. 시크릿/키는 출력 로그, 터미널 히스토리, 스크린샷에 남기지 않는다. 필요하면 더미 키로 재현한다. 토큰 권한은 최소로 준다(읽기 전용, 환경 분리). 그리고 PR/이슈에 붙일 때도 "시크릿이 스며들지 않았는지"를 마지막에 사람이 한 번 더 확인하는 절차를 고정한다.2
확장: MCP(Model Context Protocol) 개요와 활용 방향
MCP는 Claude가 "외부 도구/지식"에 접근하는 통로를 표준화해, 로컬 도구·사내 문서·DB·자동화 스크립트 같은 것들을 '서버'로 붙여 쓰게 만드는 개념으로 이해하면 편하다. 즉, 모델이 잘 모르는 사내 지식이나, 매번 사람이 복붙하던 정보(런북, 테이블 스키마, 내부 API 문서)를 도구 호출로 가져오게 만들어 컨텍스트 품질을 높인다.5
특히 Desktop에서는 MCP 서버 설치 장벽을 낮추기 위해 Desktop Extensions라는 패키징 방식을 도입했고, 2025-09-11에 확장자 표준을 .mcpb로 정리했다. 핵심은 "의존성까지 번들링된 단일 패키지"라서, 사용자는 더블클릭 후 설치로 끝내는 방향이라는 점이다.5 조직 입장에선 배포/업데이트/시크릿 저장(OS 키체인)까지 포함한 운영 단위가 생긴 셈이라, 사내 도구를 Claude에 연결할 때 표준 옵션으로 검토할 가치가 있다.5
문제 해결 체크리스트
설치 실패: 공식 설치 스크립트/패키지 매니저(Homebrew, WinGet) 중 하나로 재시도하고, 기존 설치가 꼬였으면 제거 후 재설치까지 한 번에 한다.12
claude가 실행 안 됨(PATH): 설치는 됐는데 명령이 안 잡히면 PATH 문제일 가능성이 높다. 새 터미널을 열어 다시 시도하고, 셸 설정(.zshrc 등)과 설치 위치를 확인한다.로그인 실패: 브라우저 로그인 플로우가 막히는지(회사 SSO/보안정책), 네트워크가 차단되는지부터 확인한다.
프록시/네트워크: 회사 프록시 환경에선 인증/SSL 검사로 통신이 끊길 수 있다. 먼저 브라우저에서 해당 도메인 접근이 안정적인지 확인하고, 필요하면 네트워크 팀과 예외 정책을 협의한다.
권한 프롬프트 때문에 작업이 멈춤: 프롬프트가 뜨는 지점을 기준으로 "어떤 파일/명령이 허용돼야 하는지"를 내가 먼저 선언해주면 반복 승인 횟수를 줄일 수 있다. 위험 옵션(권한 스킵)은 원칙적으로 쓰지 않는다.3
diff 적용 충돌: 로컬 변경사항이 섞였거나 브랜치가 오래됐을 가능성이 크다. 먼저 rebase/pull로 기반을 맞춘 뒤 다시 diff를 제안받는 편이 낫다.
대화가 너무 길어짐: 맥락이 오염되면 결과 품질이 떨어진다. 작업 단위를 쪼개고, 필요하면
/clear를 하거나 새 세션에서 다시 시작한다(세션을 "작업 티켓 단위"로 운영하는 감각).3이상 동작/재현 가능한 버그:
/bug로 바로 리포트한다.2
참고 링크
1Claude Code overview - Claude Code Docs
2GitHub - anthropics/claude-code
3How I use Claude Code (+ my best tips) - Builder.io 블로그(개인 경험 기반)
4How I'm using Claude Code to write R code - simonpcouch.com(개인 경험 기반)
5Claude Desktop Extensions: One-click MCP server installation for Claude Desktop
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.