클로드코드 초보가 설치 삽질 끝에 첫 관문을 넘은 이야기

소개

클로드코드도 처음, 바이브코딩도 한 번도 안 해본 제가 설치부터 작은 벽을 하나씩 넘으며 결국 클로드코드와 bkit 설치를 완료한 미니 사례입니다.

처음에는 "클로드 데스크탑앱만 있으면 되는 거 아닌가?"라고 생각했습니다. 그런데 막상 설치를 따라가다 보니, 제가 하려던 건 데스크탑앱이 아니라 CLI 환경에서 돌아가는 Claude Code가 핵심이었습니다.

이 차이를 이해하고 나니, 왜 설치가 자꾸 막혔는지 조금씩 보이기 시작했습니다.

제가 이해한 차이

클로드 데스크탑앱 = 전화로 비서에게 조언 구하기
Claude Code CLI = 비서가 직접 내 사무실에 들어와서 파일을 꺼내고, 작업까지 해주는 상태
데스크탑의 코드 탭은 편의성 위주
CLI는 파일 접근, 명령 실행, 확장 기능 활용까지 가능한 풀기능 작업 환경

비유로 정리하면

GUI (Graphical User Interface, 그래픽 사용자 인터페이스)
- 마우스로 아이콘을 클릭하는 방식
- 예: 카카오톡, 클로드 데스크탑앱
CLI (Command Line Interface, 명령줄 인터페이스)
- 키보드로 명령어를 입력해서 컴퓨터에 지시하는 방식
- 예: 터미널에서 brew install node 입력하기

특히 bkit처럼 hook·커스텀 명령어를 쓰려면 CLI 환경이 사실상 필수라는 점을 뒤늦게 이해했습니다.

진행 방법

첫 번째 시행착오: 클로드 데스크탑앱이면 되는 줄 알았다

처음에는 클로드 데스크탑만 설치하면 바로 시작할 수 있을 줄 알았습니다. 하지만 실제로는 Claude Code CLI를 따로 설치하고, 터미널 환경에서 접근해야 하는 작업이었습니다.

이 지점을 이해한 뒤부터 설치 흐름이 정리됐습니다.

2. bkit 설치에서 막혔다

bkit 설치는 더 헷갈렸습니다.

쉽게 설치하라고 만들어주신 사이트 스크립트를 넣었는데, 자꾸 40GB가 필요하다는 메시지가 떴습니다.
https://bkit.ai 에서 시도해도 잘 되지 않았습니다.
그런데 다음날 회사 컴퓨터에서 다시 해보니, 정말 1~2분도 안 걸려서 설치가 완료됐습니다.

이 경험 때문에 처음에는 "내가 뭘 잘못한 건가?" 보다 "환경 차이 때문일 수도 있겠다" 라는 생각을 하게 됐습니다.

3. 맑은 정신으로 다시, 아주 차근차근

회사 일이 바빴던 다음날, 다시 처음부터 천천히 진행했습니다.

우선 https://bkit.ai 사이트에 있는 코드로 MCP 없이 먼저 시도했습니다.
이유는 혹시 MCP 때문에 용량 초과나 추가 오류가 나는 건가? 싶었기 때문입니다.
그 결과, bkit marketplace 플러그인 설치는 성공했습니다.

여기까지는 순조로웠습니다.

4. 그런데 bkit 스크립트가 작동하지 않았다

문제는 그다음이었습니다.

bkit 스크립트가 작동하지 않았습니다.
특히 두 번째 스크립트가 계속 안 됐습니다.
(아래 이미지의 2번)

개발 언어를 전혀 모르는 입장에서, 터미널에 뭔가 길게 나오기 시작하면 솔직히 읽기 싫어집니다. 그래도 이번에는 포기하지 않고,

오류 화면을 캡처하고
그 이미지를 클로드 챗봇에게 보여주고
설명을 받아가며
다음 명령어를 하나씩 실행하는 방식으로 이어갔습니다.

비개발자 입장에서는 이 과정이 꽤 인상적이었습니다. 정말 막힐 때마다 캡처해서 AI에게 물어보면 다음 행동을 안내받을 수 있는 시대라는 걸 실감했습니다.

5. 원인은 Homebrew와 Node.js였다

대화를 이어가며 확인한 원인은 다음과 같았습니다.

brew(Homebrew) 가 설치되어 있지 않았고
Node.js 도 설치되어 있지 않아서
bkit의 hook 실행 환경이 준비되지 않은 상태였습니다.

제가 이해한 비유는 이렇습니다.

Homebrew = 개발 도구를 설치하는 앱스토어 같은 것
Node.js = bkit hook이 실제로 움직이게 해주는 실행 엔진

즉,

공구를 사러 갈 수 있는 상점(Homebrew)도 없고, 산 공구를 실제로 돌릴 전원(Node.js)도 없는 상태였던 셈입니다.

6. 실제 설치 흐름

설치는 모두 터미널에서 한 줄 명령어로 가능해서 생각보다 간단했습니다.

설치 흐름 요약

Homebrew 설치 (공구 전문점 입점)

→ brew install node (공구 전문점에서 Node.js 구매)

→ Node.js 설치됨 (bkit hook 실행 가능)

→ hook 오류 사라짐

# Homebrew 설치
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Node.js 설치
brew install node

7. claude.md도 같이 수정했다

설치만 한 것이 아니라, 이후 더 편하게 쓰기 위해 claude.md 파일도 제 상황에 맞게 수정했습니다.

기본 설정

언어

- 모든 응답은 반드시 한국어로 작성할 것
- 코드 주석도 한국어로 작성할 것
- 오류 메시지 설명도 한국어로 할 것

응답 스타일

- 개조식 불릿 리스트로 답변
- 이모지 사용 금지
- 핵심만 간결하게

역할

- 나는 비개발자 CPO임
- 기술적 설명 시 비유를 들어 쉽게 설명할 것
- 전문 용어 사용 시 괄호 안에 한글 설명 추가

이 설정은 이후 제가 클로드코드를 사용할 때 설명 방식 자체를 제 눈높이에 맞추는 장치가 됐습니다.

결과와 배운 점

결과

Claude Code 설치 완료
bkit marketplace 플러그인 설치 확인
Homebrew, Node.js 설치 완료
hook 오류 원인 파악
claude.md 개인화 설정 반영

시행착오

hook, marketplace, terminal 환경 등에 대한 무개념 -> 순서 오류
bkit+MCP 한꺼번에 설치하는 스크립트가 집 맥북환경에서 40gb 요구로 인해 설치되지 않았으나, 2일 후 MCP없이 재시도 시 설치됨

배운 점

데스크탑앱과 CLI는 다르다
툴이 안 돌아갈 때는 실행 환경 의존성부터 확인해야 한다
Homebrew와 Node.js처럼 선행 설치가 필요한 경우가 많다
막히면 AI와 대화하면서 풀면 별것 아니다

앞으로의 계획

이제 작은 작업을 Claude Code와 bkit에게 맡겨보기 (곧 올릴 예정)
bkit의 hook이나 커스텀 명령어도 한 번 더 차분하게 써보기

이번 미니 사례는 대단한 자동화 성공담은 아니지만, 적어도 저처럼 터미널이 낯설고, 설치부터 겁나는 사람에게는 "생각보다 해볼 만하다"는 메시지를 줄 수 있는 경험이었습니다.

🔥<24기 AI 스터디> 9/21 모집 마감 🔥