클로드 코드(Claude Code) 설치부터 첫 프로젝트까지 해보기

터미널 사용 경험이 많지 않은 상태를 기준으로, 클로드 코드를 설치하고 로그인한 뒤 첫 코드 수정을 맡기기까지의 과정을 그대로 정리했습니다. 설치 중 실제로 마주친 에러 메시지와 해결 방법도 함께 담았습니다.

PowerShell 창인지 CMD 창인지 헷갈릴 때는 프롬프트 표시로 구분합니다. PS C:\>로 시작하면 PowerShell, C:\>만 있으면 CMD입니다.

npm 설치는 sudo npm install -g로 실행하지 않는 것이 원칙입니다. sudo를 붙이면 이후 권한 오류로 이어지는 경우가 많습니다. 이 문제는 Section 4에서 다시 다룹니다.

Claude.ai 계정(Pro·Max·Team)으로 로그인하면 별도 API 키 없이 바로 사용할 수 있습니다. API 사용량 기반 결제를 원한다면 Console 계정으로 로그인하는 방법도 있습니다.

• ▸ "이 프로젝트는 무엇을 하는 코드야?"
• ▸ "어떤 기술 스택으로 만들어졌어?"
• ▸ "메인 진입점 파일이 어디야?"

파일을 미리 붙여넣지 않아도, 클로드 코드가 프로젝트 폴더를 스스로 탐색해 답합니다.

macOS에서 네이티브 설치 명령을 실행하자 별도 확인 없이 1분 이내에 설치가 끝났고, claude --version이 바로 정상 출력됐습니다. 반면 Windows 환경에서는 Node.js가 설치돼 있지 않은 상태에서 npm 설치를 먼저 시도해 EBADENGINE 경고와 함께 claude 명령이 동작하지 않는 상태를 겪었고, Node.js 최신 LTS를 설치한 뒤 npm 설치를 다시 실행하자 정상 동작했습니다.

※ 위 결과는 진행 시점 기준 macOS 1대·Windows 11 1대에서 확인한 내용입니다. Node.js 버전, 기존 설치 이력, 네트워크 환경에 따라 소요 시간과 오류 발생 여부는 달라질 수 있습니다.

네이티브 설치가 macOS에서 곧바로 성공한 이유는 별도 런타임 의존성이 없는 독립 실행 파일 방식이기 때문입니다. 반면 npm 설치는 Node.js 버전이라는 외부 조건에 결과가 좌우됩니다. 즉 같은 도구라도 설치 방식에 따라 "무엇이 먼저 갖춰져 있어야 하는가"가 달라지며, 이 조건을 설치 전에 확인하지 않으면 에러의 원인이 도구 자체가 아니라 사전 환경에 있다는 사실을 알아채기 어렵습니다.

설치 명령·시스템 요구 사항·인증 방식은 클로드 코드 공식 문서를 기준으로 작성했습니다.

이 포스트의 초안은 Claude를 보조 도구로 사용해 작성한 뒤 직접 편집했습니다. Section 4의 에러 목록과 Section 5의 설치 결과는 실제로 두 환경에서 설치를 진행하며 확인한 내용이며, AI가 임의로 생성한 시나리오가 아닙니다.

• ① 지금: Section 2의 네이티브 설치 명령을 실행하십시오. 별도 준비 없이 1분 안팎이면 설치가 끝납니다.
• ② 오늘 안에: 기존 프로젝트 폴더에서 claude를 실행하고, "이 프로젝트는 무엇을 하는 코드야?"부터 물어보십시오.
• ③ 익숙해지면: 작은 수정 요청부터 승인 과정을 직접 확인하고, 반복되는 허용 항목은 /permissions로 등록해 흐름을 줄이십시오.

※ 본 글의 설치 명령·시스템 요구 사항은 클로드 코드 공식 문서 기준으로 정리했으며, 이후 버전 업데이트에 따라 달라질 수 있습니다. 실제 설치 결과는 운영체제 버전, 기존 설치 이력, 네트워크 환경에 따라 달라질 수 있습니다. 본 초안은 Claude를 보조 도구로 사용해 작성됐으며, 직접 설치 테스트와 편집 과정을 거쳐 발행됐습니다.