클로드 코드 처음 배운다면 훅부터, CC101이 말하는 이유

클로드단 오픈채팅방에서 최근 반복된 화두는 '클로드 코드를 처음 쓰는 사람에게 뭘 먼저 보여줘야 하나'였다. 여러 참여자가 팀원이나 지인에게 한국어 입문 자료 CC101을 건넸다는 경험을 나눴다. 동시에 훅(hooks) 설정을 모른 채 에이전트를 실행했다가 파일이나 저장소가 망가진 사례도 언급됐다. 실제로 이 위험은 과장이 아니다. GitHub의 클로드 코드 이슈 트래커에는 rm -rf 명령이 의도치 않게 실행돼 파일이 통째로 사라졌다는 신고가 여러 건 올라와 있다. 안전장치 없이 에이전트에게 셸 권한을 넘기는 일이 얼마나 위태로운지 보여주는 대목이다.

CC101은 무엇을, 어떤 순서로 가르치나

CC101은 cc101.axwith.com에 공개된 23개 섹션짜리 한국어·영어 병기 가이드다. GitHub 저장소 fivetaku/cc101로 오픈소스 배포된다. 대상은 터미널을 한 번도 열어본 적 없는 마케터·기획자·연구원부터 바이브코딩을 시도하는 개발자까지 폭넓다. 구성은 설치와 기본 개념, CLAUDE.md로 프로젝트 맥락을 기억시키는 법, 자연어로 git과 GitHub를 다루는 법 같은 기초 14개 섹션에서 시작한다. 이후 MCP로 Notion·Slack·GitHub 같은 외부 도구를 연결하고 훅으로 위험한 명령을 차단하고 서브에이전트를 구성하는 고급 섹션으로 이어진다.

이 가이드 자체가 만든 방식부터 흥미롭다. 제작자는 코드를 한 줄도 직접 짜지 않았다. 여러 AI 도구를 활용해 기획부터 콘텐츠 작성, 사이트 개발, 배포까지 끝냈다고 설명한다. 오픈AI의 Codex에도 비슷한 성격의 입문 자료가 있었다. 그걸 보다가 클로드 코드 버전이 있으면 좋겠다 싶어 시작했다는 게 만든 계기였다. 공식 문서 앞에서 막히는 초보자를 자주 봤다. 건네줄 한국어 페이지가 필요했다는 것이다.

훅 없이 쓰다 실제로 무슨 일이 났나

방에서 나온 경고, 즉 기초 설정을 모르고 쓰면 파일이나 저장소가 훼손될 수 있다는 말은 GitHub 이슈로 확인된다. 2025년 10월 개발자 마이크 월락은 우분투·WSL2 환경에서 클로드 코드가 루트에서부터 rm -rf를 실행해 사용자 소유 파일이 전부 사라졌다고 신고했다. 다른 이슈에서는 파일을 하위 폴더로 옮긴 뒤 부모 디렉터리를 삭제해 약 1500개 파일이 경고 없이 삭제된 사례도 보고됐다. 도커 블로그가 정리한 사고 기록에는 2025년 12월 한 사용자가 오래된 저장소를 정리해 달라고 요청했다가 rm -rf ~/가 실행돼 수년치 프로젝트와 개인 파일이 통째로 날아간 경우도 있다.

한 사례에서는 셸의 틸드(~) 확장으로 삭제 대상이 홈 디렉터리를 가리키면서 사고가 났다. 겉보기엔 특정 폴더만 지우는 명령 같아도 실행 시점에는 홈 디렉터리 전체나 그 이상을 가리키게 되는 식이다. 프롬프트에 '이 폴더는 건드리지 마'라고 적어 두는 것만으로는 안전을 보장할 수 없다. 모델은 지시를 확률적으로 따를 뿐, 예외 없이 지키는 결정론적 장치는 아니기 때문이다.

훅이 실제로 막아주는 범위

클로드 코드의 훅은 특정 이벤트가 발생할 때 미리 정해 둔 스크립트를 예외 없이 실행하는 장치다. 도구 호출 직전에 걸리는 PreToolUse 훅에 rm -rf 같은 패턴을 감지하는 스크립트를 매처로 연결해 둔다. 그러면 스크립트가 종료 코드 2를 반환하는 순간 해당 명령은 실행되지 않고, 그 이유가 클로드에게 오류 메시지로 전달된다. 이 방식은 --dangerously-skip-permissions로 대화형 확인 창을 건너뛴 상태에서도 그대로 작동한다는 점이 중요하다. 스킵 플래그가 없애는 건 사람이 매번 눌러야 하는 확인 프롬프트일 뿐이다. 훅이 내리는 차단 결정까지 건너뛰지는 않는다.

다만 훅도 완전한 안전망은 아니다. 명령형 훅은 사용자 권한 그대로 명령을 실행한다. 스크립트 자체를 잘못 짜면 그 구멍으로 위험이 그대로 새어 나간다. 클로드 코드 공식 문서도 훅 사용을 '자기 책임'이라 못 박아 둔다. 방에서 훅을 초보자 교육의 기초로 꼽은 것도 이런 맥락과 무관하지 않다. CC101이 훅을 안전장치 섹션으로 별도 배치한 이유도 여기 있다.

터미널은 코딩 도구가 아니라 업무 에이전트라는 말의 실제 무게

방에서 나온 또 다른 조언은 터미널이 코딩 전용 창구가 아니라는 것이었다. 데스크톱 앱과 CLI는 같은 엔진을 쓰고 CLAUDE.md, 설정, MCP 서버, 훅, 스킬, 권한 규칙을 그대로 공유하지만 쓰임새는 갈린다. 데스크톱 앱은 변경 사항을 빨간 줄과 초록 줄로 보여주는 시각적 diff와 여러 세션을 한 화면에 띄우는 사이드바가 강점이다. CLI는 여러 창을 동시에 띄워 반복 가능한 워크플로우와 자동화를 짤 수 있어 기능 범위가 더 넓다는 게 대체로 통용되는 평가다.

비개발자의 실무 활용은 이미 사례로 쌓이고 있다. 코딩 경험이 없는 마케팅 인력이 자연어 명령만으로 웹훅을 설정하고 카드뉴스 제작을 자동화했다. 작업 시간을 크게 줄였다는 활용 사례가 공유된 바 있다. 방에서도 터미널로 코딩뿐 아니라 자연어 대화와 업무 지시가 가능하다는 언급이 나왔다. 코딩 도구를 넘어 범용 비서로 쓰인다는 실제 흐름과 겹치는 이야기다.

초보자에게 남는 선택은 명확하다. 입문 자료로 개념을 익히되, 첫 실행 전에 훅으로 위험한 명령을 걸러내는 최소한의 장치부터 걸어두는 것이다. 그 순서를 건너뛴 사고 사례는 이미 차고 넘친다.