npm 패키지 배포: 바리스타가 첫 CLI 도구를 출시하기까지

한눈에 요약
카페에서 일하는 비전공자가 AI와 함께 CLI 도구 VHK를 만들고 npm에 공개했다. 핵심은 대단한 코딩 지식이 아니라 한 번에 목표 하나만 잡고, 테스트가 실패하면 완료를 거부하는 구조를 만든 것이다. vhk goal, vhk check, vhk preflight는 그 시행착오에서 나온 안전장치다.

퇴근하고 앞치마를 벗으면, 그날의 두 번째 출근이 시작된다. 카페에서 종일 샷을 내리던 손으로 밤엔 터미널을 연다.

"개발자도 아닌데 이게 될까?" 몇 달 전의 나는 명령어 한 줄 앞에서도 막막했다.

그런데 지금, 내가 만든 도구는 npm에 올라가 있다. npm i -g @byh3071/vhk@2.5.1 한 줄이면 누구나 설치할 수 있다.

나는 바리스타다. 전공도, 개발 회사 경력도 없다. AI와 같이 만드는 비전공자다.

이 글은 그 과정을 감정도, 막혔던 지점도, 실제로 친 명령어도 빼지 않고 적은 현실 기록이다. 똑같이 시작하려는 사람에게 주는 기록이기도 하다.

npm에 CLI를 배포한다는 건 뭔가?

npm 배포는 내가 만든 명령어 도구를, 전 세계 누구나 한 줄로 설치해 쓰게 만드는 일이다. 웹사이트를 띄우는 게 아니라 터미널에 치는 명령어 자체를 패키지로 포장해 공개 저장소에 올리는 것이다.

"npm 배포 = 내 명령어 도구를 누구나 한 줄로 설치하게 만드는 일."

앱스토어에 앱 올리는 것과 비슷한데, 사용자가 "터미널 쓰는 사람"이라는 점만 다르다.

VHK는 무엇을 막는 도구인가?

한 줄로 말하면, VHK는 AI랑 코딩할 때 대충 넘어가는 걸 막아주는 작업 규율 도구다. 내가 쓰려고 만들었고, 지금도 매일 쓴다.

하는 일을 세 개로 추리면 이렇다.

• vhk goal — 한 번에 목표 하나만 잡게 한다. 이것저것 손대다 아무것도 못 끝내는 걸 막으려고 만들었다. 1 PR = 1 goal.
• vhk check — 테스트나 게이트를 통과하지 못하면 "완료"를 거부한다. 소위 거짓 완료를 차단한다.
• vhk preflight — 배포 전에 안전점검을 한 번에 돌린다. 터트리기 전 마지막 관문이다.

"VHK는 내 의지가 아니라 규칙으로 나를 막아주는 도구다."

왜 굳이 직접 만들었나?

AI랑 코딩하면 빠르다. 그런데 빠른 만큼 같은 함정에 반복해서 빠졌다.

AI가 "다 됐어요!"라고 해도 직접 실행해보면 버튼이 반응하지 않거나, 명령은 끝났는데 결과 파일이 생기지 않거나, 기존 기능에 새 버그가 나는 일이 반복됐다. 코드를 작성했다는 말과 실제로 동작한다는 것은 달랐다.

그래서 완료 판단을 말이 아니라 확인 절차에 맡기기로 했다. 사람이 놓칠 수 있는 부분을 테스트와 규칙이 막게 하자.

그렇게 VHK가 태어났다. 최신 공개 기준으로 목표 문서는 0번부터 46번까지 47개 쌓였고, 버전은 v2.5.1까지 왔다. v2.5.1 릴리스 기준 테스트는 1162 pass까지 확인했다.

실제로 어떤 순서로 만들었나?

1단계: 명령어 하나부터 AI와 뼈대 세우기

처음부터 대단한 걸 만들려 하지 않았다. 명령어 딱 하나 동작시키기부터 시작했다.

AI에게 "CLI 뼈대 잡아줘"라고 시키고, 나온 코드를 내가 읽으며 "이 줄은 뭐 하는 거야?"를 계속 물었다.

코드를 못 읽어도 괜찮다. "이 줄 뭐야?"를 계속 물으면 AI가 설명해주고, 나는 그 설명을 바탕으로 판단하면 된다. 한 번에 다 이해하려 하면 포기하게 된다.

2단계: 거짓 완료에 제대로 데였다

실제로 테스트를 돌리지 않고 "됐다"고 넘어갔다가, 동작하지 않는 지점을 찾느라 반나절을 디버깅에 쓴 적이 있다.

그래서 게이트를 아예 도구에 박았다. vhk check가 테스트 통과를 확인하지 못하면 완료를 거부하게 했다. 에러를 조용히 숨기지 않는 규칙도 같이 넣었다.

교훈은 간단했다. 실수를 줄이는 건 다짐이 아니라, 실수를 불가능하게 만드는 구조다.

3단계: npm에 올리기라는 마지막 산

배포는 또 다른 산이었다. 패키지 이름 @byh3071/vhk, 버전 규칙, 그리고 2단계 인증(OTP).

배포는 사람이 직접 인증해야 하는 단계라 자동화하지 않았다. 대신 vhk preflight로 출고 전 점검을 돌린 뒤 올렸다.

배포 후 npm i -g @byh3071/vhk@2.5.1과 vhk --version을 다시 실행해 공개 패키지가 정상 설치되는지 확인했다.

아래 npm 화면에서 확인할 부분은 두 가지다.

1. Current Tags의 버전이 2.5.1이고 태그가 latest인지
2. 오른쪽 Install 영역에 npm i @byh3071/vhk 명령이 제공되는지

한눈에 보면 어떤 흐름인가?

1. AI와 CLI 뼈대 설계 — 뭘 모르는지도 몰랐지만 "이 줄 뭐야?"를 계속 물으며 첫 명령어를 동작시켰다.
2. 테스트·게이트 규칙 도구화 — 확인 없이 넘어가는 습관을 vhk check의 완료 거부로 막았다.
3. npm 배포 — 버전과 OTP 인증을 vhk preflight 점검과 수동 인증으로 통과해 공개 설치가 가능해졌다.

비전공자는 어떻게 따라 하면 좋을까?

내가 먹은 시행착오를 압축하면 이렇다.

1. 한 번에 명령어 또는 기능 하나만 만든다. 큰 걸 통째로 만들려 하면 무조건 멈춘다.
2. 코드를 못 읽어도 "이 줄 뭐야?"를 계속 물어라. 이해는 그렇게 차오른다.
3. "됐다"를 믿지 말고 테스트로 확인해라. 그게 귀찮으면 확인을 강제하는 장치를 둔다.
4. 막힌 순간을 기록해라. 그 기록이 다음 글이 되고, 다음 도구의 재료가 된다.

핵심 테이크어웨이는 무엇인가?

1. AI는 속도, 판단은 사람. 단, 판단을 까먹는 나는 의지가 아니라 도구로 막아야 한다.
2. 비전공자의 무기는 지식이 아니라 "한 번에 하나 + 기록"이다. 전공보다 꾸준한 검증 루프가 더 중요했다.
3. 도구는 거창할 필요 없다. 내 실수 하나를 막는 것부터 시작해도 된다. VHK도 그렇게 명령어 하나에서 출발했다.

다음 이야기는 무엇인가?

다음 글에서는 "AI랑 코딩할 때 거짓 완료를 막는 게이트"를 내가 실제로 쓴 규칙과 함께 더 구체적으로 풀어볼 생각이다.

관련해서 먼저 읽어볼 만한 글:

• AI 시대, 나만의 브랜드를 만드는 법 — 요한 스튜디오 런칭기
• 바이브코딩으로 2시간 만에 웹사이트 배포한 후기