Claude Code 3개월 실전기: 실패 패턴과 그 이유

터미널 앞에서 멍하니 있던 날

터미널 창을 처음 열었을 때, 커서가 깜빡이는 검은 화면 앞에서 한참을 멍하니 있었다. 개발자가 아니다. 코드를 짜본 적도 없다. 그런데 지금 이 포트폴리오 사이트는 내가 만들었다. Claude Code와 함께. 이 글은 그 과정에서 배운 것들을 정리한 것이다. 도구 홍보가 아니다. 실제로 겪은 것들, 잘못 이해했던 것들, 그리고 지금도 여전히 불편한 것들을 솔직하게 쓴다.

Claude Code의 작동 원리

Claude Code는 CLI 도구다. 터미널에서 실행하고, 자연어로 지시하면 파일을 읽고, 코드를 쓰고, 터미널 명령을 실행한다. 단순한 자동완성이 아니라 태스크를 받아 스스로 계획하고 실행하는 에이전트다. 이 구조를 이해하려면 몇 가지 개념을 알아야 한다.

'CLAUDE.md'는 프로젝트 루트에 두는 행동 지침서다. Claude Code가 세션을 시작할 때 자동으로 읽는다. 코딩 스타일, 금지 사항, 프로젝트 구조를 여기에 정의해두면 매번 설명할 필요가 없다. 처음에 이걸 제대로 안 썼더니 세션마다 같은 맥락을 반복해서 주입해야 했다. 시간 낭비였다.