비개발자가 포트폴리오 사이트를 직접 만들면서 배운 것들

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

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

Claude Code의 작동 원리

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

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

'서브 에이전트'는 메인 에이전트가 하위 태스크를 별도 에이전트에게 위임하는 구조다. 리서치는 A, 코드 작성은 B, 테스트는 C처럼 역할을 분리해서 병렬로 실행한다. 복잡한 작업일수록 이 구조가 속도 차이를 만든다. '커맨드'는 /로 시작하는 단축 명령어로, /review, /test, /deploy처럼 자주 쓰는 작업을 등록해두면 긴 지시 없이 한 단어로 호출한다.

'훅'은 특정 이벤트 발생 시 자동으로 실행되는 스크립트다. 파일 저장 후 린트 실행, 커밋 전 테스트 자동화, 작업 완료 후 Slack 알림 전송 같은 것들을 자동화할 수 있다. '스킬'은 에이전트가 특정 작업을 수행하는 방법을 담은 재사용 가능한 지식 모듈이다. "코드 리뷰하기", "문서 작성하기" 같은 작업 방식을 파일로 정의해두고 필요할 때 불러쓴다. 'MCP'는 Claude Code가 외부 앱을 직접 읽고 쓸 수 있게 해주는 연결 프로토콜로, Notion, Slack, GitHub, Figma와 연결하면 에이전트가 앱을 넘나들며 작업한다. 이 여섯 개 개념이 맞물리면 단순한 CLI 도구가 아니라 작업 흐름 전체를 설계할 수 있는 프레임워크가 된다.

바이브 코딩의 현실

워크플로우는 단순하다. 준비 → 플래닝 → 플랜 점검 → 구현 → 점검·개선. 이 루프를 반복한다. 구현은 AI가 한다. 사람이 해야 하는 건 플래닝이다. 플래닝에 시간을 많이 쓸수록 구현이 빠르다. 요구사항을 구체화하고, 단계를 분해하고, 엣지케이스를 정의하는 데 시간을 쓰면 AI가 엉뚱한 방향으로 달려가는 일이 줄어든다. "think"나 "ultrathink"를 프롬프트에 포함하면 Claude가 실행 전에 더 깊게 추론하고 계획을 세운다.

그런데 실제로 해보면 이 루프가 생각보다 자주 깨진다. 내가 겪은 실패들을 솔직하게 쓴다. 가장 먼저 저지른 실수는 플래닝 없이 바로 구현을 요청한 것이다. "로그인 기능 만들어줘"처럼 모호하게 던지면 AI가 엉뚱한 방향으로 달려간다. 무엇을, 왜, 어떻게를 먼저 정의하고 플랜을 확인한 뒤 구현을 지시해야 한다는 걸 몇 번 실패하고 나서야 체득했다.

같은 세션에서 너무 많은 수정을 반복하는 것도 문제였다. 대화가 길어지면 AI가 앞뒤 맥락에 혼란을 느낀다. 큰 방향이 바뀌면 새 세션을 시작하고 CLAUDE.md로 맥락을 주입하는 게 맞다. 이걸 모르고 한 세션에서 계속 수정하다가 코드가 점점 이상해지는 경험을 했다. "조금만 더 고쳐줘"를 반복하면 코드가 복잡해지고 나중에 리팩터링이 불가능해진다. 일정 수준의 변경은 처음부터 다시 짜는 게 결국 더 빠르다.

AI가 "완성됐다"고 해도 그냥 배포하는 실수도 했다. AI 출력은 초안이다. 실제로 실행되는지, 의도대로 작동하는지 직접 확인해야 한다. 이걸 건너뛰면 반드시 후회한다. AI가 만든 코드를 블랙박스로 두면 버그가 났을 때 고칠 수 없다. "이 코드 한 줄씩 설명해줘"로 항상 이해하며 진행해야 한다. 구현 후 CLAUDE.md를 업데이트하지 않으면 다음 세션에서 AI가 이전 상황을 모른 채 시작한다. 구현과 문서 업데이트는 세트다. 마지막으로, "전체 앱 만들어줘"처럼 너무 큰 태스크를 한 번에 던지면 안 된다. 기능 단위로 잘게 쪼개서 각 단계를 확인하며 진행하는 것이 결국 더 빠르다. 커밋도 작게 자주.

다만 이 실패들이 전부 예측 가능했다는 게 아이러니다. 미리 알았어도 한 번씩은 겪었을 것 같다.

에디터와 에이전트, 무엇이 다른가

VS Code 같은 에디터는 사람이 주도한다. AI가 보조한다. 작업 단위는 줄이나 함수 수준이고, 매 스텝마다 사람이 개입한다. 터미널 실행 권한은 없다. Cursor Agent Mode 같은 에디터 내 에이전트는 중간 어딘가에 있다. 피처나 태스크 단위로 작업하고, 사람은 승인만 한다. 터미널 실행은 제한적이다. 주도권이 사람에서 AI로 넘어가는 과도기적 형태다.

Claude Code 같은 순수 에이전트는 다르다. 태스크나 레포 단위로 작업하고, 사람은 시작과 끝에만 개입한다. 터미널 실행 권한이 풀로 있다. 주도권이 AI에게 있다. 이 차이가 실제 경험에서 어떻게 느껴지냐면, 에디터는 내가 운전하고 AI가 네비게이션을 보는 것이고, Claude Code는 AI가 운전하고 내가 목적지를 말하는 것이다. 어느 쪽이 낫다는 게 아니다. 태스크의 성격에 따라 다르다.

비용은 얼마나 드는가

Claude Code는 두 가지 요금제가 있다. Pro는 월 $20, Max는 월 $100이다. Pro는 claude.ai 구독이 포함되고 사용량 제한이 있다. Max는 헤비 유저용으로 5배 높은 사용량 한도를 제공한다. API를 직접 쓰면 종량제다. API 토큰 요금은 Sonnet 4.5 기준으로 Input $3/1M 토큰, Output $15/1M 토큰이다. 1M 토큰은 A4 약 2,500장 분량이다. 일반적인 바이브 코딩 세션, 하루 2~3시간 기준으로는 월 $20 Pro 구독으로 대부분 커버된다. API를 직접 쓰면 하루 집중 작업 기준 $2~5 수준이다.

비용을 줄이는 방법은 결국 플래닝이다. 무한 수정 루프가 토큰 낭비의 주범이다. 큰 파일을 통째로 붙이지 말고 필요한 부분만 넣는 것도 중요하다. 같은 시스템 프롬프트나 문서를 반복 사용하면 Prompt Caching으로 Input 비용을 90%까지 절감할 수 있다. CLAUDE.md처럼 고정된 내용에 효과적이다. 단순 반복 작업은 Claude Haiku로, 복잡한 추론과 설계는 Sonnet이나 Opus로 용도에 맞게 모델을 선택하면 비용이 대폭 줄어든다.

텍스트 너머, 멀티모달 활용

Claude는 텍스트만 받는 게 아니다. 이미지, 스크린샷, 디자인 시안, PDF를 그대로 붙여넣으면 읽고 분석하고 구현한다. Figma 화면 스크린샷을 붙여넣고 "이 디자인을 React 컴포넌트로 만들어줘. Tailwind CSS 사용"이라고 하면 레이아웃, 컬러, 폰트까지 그대로 코드로 변환된다. 개발자 없이 시안을 바로 프로토타입으로 만들 수 있다.

터미널 에러 메시지나 브라우저 콘솔 스크린샷을 그대로 붙이면 무슨 에러인지, 왜 났는지, 어떻게 고치는지를 바로 설명해준다. 에러 텍스트를 일일이 복사할 필요가 없다. 계약서나 기획서 PDF를 넣고 "주요 내용 요약해줘"라고 하면 구조화된 지식으로 변환된다. 엑셀 화면이나 대시보드 스크린샷을 붙이고 "이 데이터에서 뭘 읽을 수 있어?"라고 하면 패턴과 이상값을 즉시 분석한다. 이 기능이 PM이나 기획자에게 특히 강력한 이유는, 텍스트로 설명하기 어려운 것들을 그냥 보여주면 되기 때문이다. 말로 설명하는 것보다 스크린샷 하나가 훨씬 정확하다.

결국 Claude Code는 도구다. 잘 쓰면 비개발자도 프로덕트를 만들 수 있다. 못 쓰면 AI와 계속 싸우게 된다. 차이는 플래닝에 있고, 플래닝은 결국 생각하는 시간이다. AI가 빠르게 실행할수록, 사람이 더 깊이 생각해야 한다.