기획서 파일 하나로 Claude Code의 오작동 줄이기

코딩을 모르는 창업가가 Claude Code를 쓰면서 가장 자주 하는 실수는 대화하듯 코드를 짜는 겁니다. 처음엔 신기해서 이것저것 시키다 보면 어느 순간 인공지능이 앞뒤 안 맞는 코드를 뱉어내기 시작합니다. 프로젝트가 커질수록 AI는 내가 처음에 뭘 만들려 했는지 잊어버리기 때문입니다. 이걸 막으려면 터미널을 켜기 전에 한글로 된 설계도부터 만들어야 합니다.

product_spec.md 파일이 벌어다 주는 시간

개발 지식이 없어도 서비스의 뼈대는 직접 잡아야 합니다. 프로젝트 폴더 제일 상단에 product_spec.md라는 파일을 만드세요. 여기에 내가 만들고 싶은 서비스의 목적, 꼭 필요한 기능, 사용자가 화면에서 어떻게 움직이는지를 한글로 자세히 적어두면 됩니다.

준비가 끝났다면 터미널에서 Claude Code를 실행하고 플랜 모드(Plan Mode)로 들어갑니다. 그 다음 "이 문서 내용대로만 구현 계획을 짜줘"라고 시키면 됩니다. Anthropic의 관찰 결과에 따르면, 이렇게 사전에 정의된 사양을 기반으로 개발할 경우 나중에 꼬인 코드를 풀기 위해 허비하는 시간을 5시간 이상 아낄 수 있습니다.

API 키 유출로 1억 원 청구서 받지 않는 법

보안은 나중에 챙기는 게 아닙니다. 2024년 통계에 따르면 깃허브(GitHub)에 실수로 노출되는 민감 정보는 매년 2% 이상 늘고 있습니다. 특히 AI 에이전트는 사람이 짤 때보다 보안 정보를 노출할 확률이 2배나 높습니다. 실제로 구글 클라우드 API 키가 유출되어 단 이틀 만에 8만 2천 달러, 우리 돈으로 1억 원 넘는 요금이 청구된 사례도 있습니다. 1인 창업가에게는 사업을 접어야 할 만큼 치명적인 사고입니다.

코드를 짜기 전 딱 세 가지만 먼저 하세요.

• 터미널에 touch .env를 쳐서 파일을 만들고, 모든 비밀번호와 API 키는 여기에만 적으라고 Claude에게 명령하십시오.
• .gitignore 파일을 만들고 그 안에 .env라고 적으세요. 이 파일이 내 컴퓨터 밖으로 나가는 걸 막아줍니다.
• Claude 설정 파일(~/.claude/settings.json)에서 .env 파일 접근 권한을 거부로 설정하십시오.

이렇게 하면 자동화된 해킹 봇이 내 소중한 자격 증명을 털어가는 상황을 원천 차단할 수 있습니다.

화면이 안 나올 때는 브라우저 콘솔을 복사하세요

코드는 다 짰다는데 브라우저 화면이 백지라면 당황스럽습니다. 하지만 이럴 때 비싼 외주 개발자를 찾을 필요는 없습니다. 브라우저가 이미 정답을 말하고 있기 때문입니다.

웹 브라우저에서 F12를 누르면 콘솔(Console) 창이 뜹니다. 거기 보이는 빨간색 에러 메시지를 전부 복사해서 Claude Code 터미널에 그냥 붙여넣으세요. "이 에러가 나는데 원인을 찾아서 고쳐줘"라고 한마디만 덧붙이면 됩니다. 기술을 몰라도 에러 메시지만 잘 전달하면 AI가 내 눈과 귀가 되어 버그를 잡아냅니다.

90% 비용을 아끼는 롤백 습관

Claude Code는 내가 쓴 토큰 양만큼 돈을 가져갑니다. 하루에 12달러 내외로 쓰는 사용자가 대부분이지만, 같은 질문을 반복하거나 너무 큰 덩어리의 작업을 시키면 요금 폭탄을 맞을 수 있습니다.

비용을 아끼려면 작업을 잘게 쪼개야 합니다. 로그인 기능 하나, 메뉴바 디자인 하나씩 따로 요청하세요. 그리고 기능 하나가 성공할 때마다 "지금까지 한 거 커밋(Commit)해줘"라고 시키십시오. 게임의 세이브 포인트 같은 겁니다. 만약 AI가 코드를 엉망으로 고쳐놓았다면, 당황하지 말고 터미널에 git reset --hard HEAD를 입력하세요. 방금 전 성공했던 상태로 마법처럼 되돌아갑니다. 이 습관 하나가 불필요한 재수정 비용을 90%까지 줄여줍니다.