AI 엔지니어와 알아보는 Claude Code 공략집 - 3편
1편에서는 Claude Code를 설치하고 터미널에서 실행하는 흐름을 정리했다. 2편에서는 프로젝트 폴더에서 작업하고, Git으로 변경사항을 확인하고, Claude Code에게 안전하게 일을 맡기는 기본 루프를 정리했다.
3편에서는 코딩을 거의 모르는 사람이 Claude Code로 실제 프로젝트를 만드는 방법을 정리한다. 여기서 말하는 바이브코딩은 코드를 직접 한 줄씩 작성하기보다, 만들고 싶은 결과를 자연어로 설명하고 AI 에이전트와 함께 기능을 쌓아가는 방식이다. 다만 결과물을 안정적으로 만들려면 “그냥 만들어 줘”보다 훨씬 구체적인 작업 방식이 필요하다.
Claude Code는 터미널에서 프로젝트를 읽고, 파일을 수정하고, 명령을 실행할 수 있는 에이전트형 개발 도구다. Claude Code 개요에서 설명하는 핵심도 코드베이스를 이해하고 개발 작업을 돕는 명령줄 도구라는 점이다. 초보자에게 중요한 지점은 코딩 지식보다 작업을 작은 단위로 나누고, 매 단계마다 확인하는 습관이다.
개발 작업은 코드를 많이 쓰는 일보다 작은 변경을 확인하는 흐름에 가깝다.
1. 바이브코딩은 “프롬프트 실력”보다 “작업 분해”가 중요하다
코딩을 모르는 상태에서 가장 많이 하는 실수는 처음부터 완성된 서비스를 한 번에 요청하는 것이다. 예를 들어 “인스타그램 같은 서비스를 만들어 줘”라고 요청하면 Claude Code는 많은 파일을 한 번에 만들 수 있다. 하지만 초보자는 그 결과가 맞는지 검증하기 어렵고, 오류가 생겼을 때 어디서부터 봐야 하는지도 알기 어렵다.
프로젝트는 화면, 데이터, 동작, 저장, 배포 같은 여러 층으로 나뉜다. 코딩을 모르는 사람일수록 이 층을 한꺼번에 다루지 않는 편이 안전하다. 처음에는 화면만 만들고, 그다음 버튼 동작을 붙이고, 그다음 데이터를 저장하는 식으로 진행해야 한다.
내가 권하는 기본 순서는 다음과 같다.
- 만들고 싶은 서비스를 한 문장으로 정의한다.
- 사용자가 실제로 누를 화면을 먼저 정한다.
- 가장 작은 기능 하나만 만든다.
- 실행해서 눈으로 확인한다.
- Git diff로 바뀐 파일을 확인한다.
- 문제가 없으면 다음 기능으로 넘어간다.
이 순서는 개발자가 보기에는 느려 보일 수 있다. 하지만 코딩을 모르는 사람에게는 가장 빠른 방법이다. 한 번에 많이 만들었다가 전체를 이해하지 못하는 상태가 되면 이후 수정 비용이 더 커진다.
2. 프로젝트를 시작하기 전에 한 장짜리 기획서를 만든다
Claude Code에게 바로 “앱 만들어 줘”라고 입력하기 전에 프로젝트 설명을 먼저 정리해야 한다. 이 문서는 거창할 필요가 없다. 오히려 짧고 명확해야 한다.
초보자용 프로젝트 기획서는 다음 항목이면 충분하다.
- 프로젝트 이름
- 누구를 위한 서비스인지
- 사용자가 처음 보는 화면
- 반드시 필요한 기능 3개
- 지금 만들지 않을 기능
- 디자인 분위기
- 사용할 데이터 예시
예를 들어 할 일 관리 앱을 만든다면 다음처럼 쓸 수 있다.
프로젝트 이름: simple-todo
목표: 코딩을 모르는 개인 사용자가 오늘 할 일을 관리하는 웹앱을 만든다.
첫 화면: 할 일 목록, 입력창, 추가 버튼이 보인다.
필수 기능:
1. 할 일을 추가한다.
2. 할 일을 완료 처리한다.
3. 할 일을 삭제한다.
이번 버전에서 제외할 기능:
- 로그인
- 다른 사람과 공유
- 모바일 앱 배포
디자인: 흰 배경, 큰 글씨, 버튼은 명확하게 보이게 한다.
데이터 예시:
- 블로그 글쓰기
- 장보기
- 운동하기
이 정도만 있어도 Claude Code가 무엇을 만들어야 하는지 훨씬 잘 이해한다. 특히 “이번 버전에서 제외할 기능”이 중요하다. 초보 프로젝트는 기능을 많이 넣을수록 실패 확률이 올라간다.
초보 프로젝트는 구현보다 먼저 범위와 순서를 정해야 안정적이다.
3. 첫 요청은 구현이 아니라 “계획 수립”이어야 한다
Claude Code를 켠 뒤 첫 프롬프트에서 바로 파일 수정을 맡기지 않는 편이 좋다. 처음에는 프로젝트 구조와 구현 계획만 요청한다. Claude Code 일반 워크플로우에서도 코드베이스 이해, 수정, 테스트, 커밋 같은 반복 작업이 중요한 흐름으로 다뤄진다.
첫 요청 예시는 다음과 같다.
이 프로젝트는 코딩을 모르는 사람이 사용할 간단한 할 일 관리 웹앱이다.
아직 코드를 수정하지 말고, 먼저 다음만 정리해 줘.
1. 어떤 파일을 확인해야 하는지
2. 어떤 순서로 만들면 안전한지
3. 첫 번째로 구현할 가장 작은 기능은 무엇인지
4. 내가 실행해서 확인해야 할 명령어는 무엇인지
나는 초보자라서 설명은 쉬운 말로 해 줘.
이 요청의 핵심은 “아직 코드를 수정하지 말고”라는 조건이다. 초보자는 Claude Code가 프로젝트를 어떻게 이해했는지 먼저 확인해야 한다. 계획이 너무 크거나 이해하기 어렵다면 구현 전에 줄여야 한다.
계획을 받은 뒤에는 다음처럼 범위를 좁힌다.
좋아. 지금은 로그인과 저장 기능은 제외하자.
먼저 화면에 할 일 목록, 입력창, 추가 버튼만 보이게 만들어 줘.
파일 수정 전에 어떤 파일을 바꿀지 먼저 말해 줘.
이렇게 요청하면 변경 범위가 작아진다. 범위가 작아질수록 초보자도 결과를 확인하기 쉬워진다.
4. 초보자는 “기능 1개 단위”로만 요청한다
바이브코딩에서 가장 중요한 규칙은 한 번에 기능 하나만 맡기는 것이다. 기능 하나는 사용자가 눈으로 확인할 수 있는 작은 변화여야 한다.
좋은 요청은 다음처럼 생겼다.
할 일 입력창과 추가 버튼을 만들어 줘.
사용자가 텍스트를 입력하고 추가 버튼을 누르면 화면 아래 목록에 표시되게 해 줘.
아직 저장 기능은 만들지 마.
수정 후 실행 방법도 알려 줘.
나쁜 요청은 다음처럼 범위가 넓다.
할 일 앱을 완성해 줘.
디자인도 예쁘게 하고 저장도 되고 로그인도 되게 해 줘.
초보자는 “완성”이라는 단어를 조심해야 한다. 완성이라는 표현은 사람에게는 편하지만 에이전트에게는 범위가 불명확하다. 대신 화면에서 확인 가능한 동작을 하나씩 적는 편이 안전하다.
기능을 하나 구현한 뒤에는 바로 다음 질문을 던지지 않는다. 먼저 실행하고, 눈으로 확인하고, 변경사항을 확인한다.
git status
git diff
git status는 바뀐 파일 목록을 보여준다. git diff는 실제로 어떤 코드가 바뀌었는지 보여준다. 코드를 모두 이해하지 못해도 파일이 지나치게 많이 바뀌었는지, 전혀 관련 없는 파일이 수정됐는지는 확인할 수 있다.
기능을 작은 단위로 나누면 Claude Code의 변경사항을 검증하기 쉬워진다.
5. 모르는 오류는 그대로 복사해서 붙여넣는다
초보자가 오류를 만났을 때 가장 피해야 할 행동은 오류 메시지를 요약해서 전달하는 것이다. “무슨 빨간 에러가 떠”라고 설명하면 Claude Code가 원인을 좁히기 어렵다. 터미널에 나온 오류 문장을 그대로 복사해서 붙여넣는 편이 낫다.
오류를 전달할 때는 다음 형식을 사용한다.
방금 실행했더니 아래 오류가 나왔다.
아직 파일을 수정하지 말고, 원인을 쉬운 말로 설명해 줘.
그리고 수정이 필요하다면 어떤 파일을 바꿀지 먼저 말해 줘.
오류 메시지:
여기에 터미널 오류 전체를 붙여넣는다.
오류 수정도 바로 맡기지 않는 편이 좋다. 먼저 원인을 설명하게 하고, 수정 파일을 확인한 뒤 진행한다. 특히 의존성 설치, 설정 파일 변경, 데이터 삭제와 관련된 요청은 더 조심해야 한다.
오류가 길어도 전체를 붙여넣는 편이 좋다. 에러의 첫 줄만 보고 해결하려 하면 실제 원인을 놓칠 수 있다. 터미널 로그에는 실패한 명령, 파일 경로, 줄 번호, 패키지 이름이 함께 들어가는 경우가 많다.
6. “예쁘게”보다 “구체적인 화면”을 요청한다
초보 프로젝트에서 디자인 요청은 자주 모호해진다. “예쁘게 만들어 줘”는 사람마다 의미가 다르다. Claude Code에게는 색, 간격, 글자 크기, 버튼 모양, 화면 배치처럼 확인 가능한 기준을 주는 편이 좋다.
예를 들어 다음 요청은 모호하다.
디자인을 예쁘게 바꿔 줘.
다음 요청은 더 구체적이다.
첫 화면 디자인을 정리해 줘.
조건은 다음과 같다.
- 전체 폭은 너무 넓지 않게 가운데 정렬한다.
- 제목은 크게 보이게 한다.
- 입력창과 추가 버튼은 한 줄에 배치한다.
- 할 일 목록은 카드처럼 구분되게 한다.
- 색상은 흰 배경과 파란색 버튼 중심으로 사용한다.
- 기능 동작은 바꾸지 말고 스타일만 수정한다.
마지막 줄의 “기능 동작은 바꾸지 말고 스타일만 수정한다”가 중요하다. 디자인만 바꾸려는 작업에서 기존 동작까지 같이 바뀌면 초보자는 원인 파악이 어렵다.
디자인 요청은 분위기보다 배치, 색, 크기처럼 확인 가능한 조건으로 적는 편이 좋다.
7. 저장 기능은 가장 늦게 붙인다
코딩을 모르는 사람이 처음부터 데이터베이스를 붙이면 난이도가 급격히 올라간다. 로그인, 권한, 테이블, API, 환경변수, 배포 설정이 함께 따라오기 때문이다. 처음에는 브라우저 화면에서만 동작하는 형태로 시작하는 편이 안전하다.
할 일 관리 앱을 예로 들면 순서는 다음이 좋다.
- 화면에 샘플 할 일을 보여준다.
- 입력한 할 일을 화면 목록에 추가한다.
- 완료 처리와 삭제를 붙인다.
- 새로고침하면 사라지는 상태로 충분히 테스트한다.
- 그다음 로컬 저장이나 데이터베이스 저장을 검토한다.
새로고침하면 데이터가 사라지는 앱은 미완성처럼 보일 수 있다. 하지만 학습용 첫 프로젝트에서는 오히려 장점이 있다. 저장 계층을 붙이기 전에 화면과 동작을 충분히 확인할 수 있기 때문이다.
저장 기능을 붙일 때도 한 번에 데이터베이스까지 가지 않아도 된다. 브라우저의 로컬 저장소를 먼저 쓰는 방식이 더 단순할 수 있다. 다만 실제 서비스 계정, 결제, 개인정보처럼 중요한 데이터를 다루는 프로젝트라면 보안과 백업을 별도로 설계해야 한다.
8. Claude Code에게 프로젝트 규칙을 남긴다
반복해서 말해야 하는 규칙은 CLAUDE.md에 남기는 편이 좋다. Claude Code 메모리 문서는 CLAUDE.md를 통해 프로젝트별 지침을 저장하는 방식을 다룬다. 초보자에게 이 파일은 “Claude Code에게 매번 알려줘야 하는 작업 규칙”을 적어두는 곳으로 이해하면 된다.
초보 프로젝트용 CLAUDE.md 예시는 다음과 같다.
# 프로젝트 작업 규칙
- 사용자는 코딩 초보자이므로 설명은 쉬운 말로 작성한다.
- 한 번에 큰 기능을 만들지 않는다.
- 파일을 수정하기 전에 어떤 파일을 바꿀지 먼저 설명한다.
- 로그인, 결제, 배포, 데이터베이스는 사용자가 명시적으로 요청하기 전까지 만들지 않는다.
- 기능 수정과 디자인 수정을 한 번에 섞지 않는다.
- 수정 후 실행 명령어와 확인 방법을 알려준다.
- 테스트나 빌드 명령이 있다면 변경 후 실행한다.
이 파일을 잘 써두면 이후 대화가 안정된다. 특히 “한 번에 큰 기능을 만들지 않는다”, “파일을 수정하기 전에 설명한다” 같은 규칙은 초보자에게 중요하다.
9. 권한 요청은 “무엇을 바꾸는지” 기준으로 판단한다
Claude Code는 파일 수정이나 명령 실행 과정에서 권한 확인을 요구할 수 있다. 초보자는 권한 요청을 보고 무조건 승인하기 쉽지만, 적어도 무엇을 하려는지는 확인해야 한다.
승인해도 비교적 안전한 작업은 다음과 같다.
- 현재 프로젝트 안의 소스 파일 수정
- 스타일 파일 수정
- 테스트 명령 실행
- 린트 명령 실행
- 빌드 명령 실행
더 신중해야 하는 작업은 다음과 같다.
- 프로젝트 밖의 파일 수정
- 대량 파일 삭제
- 환경변수 파일 수정
- 의존성 대량 설치
- 데이터베이스 초기화
- 배포 관련 설정 변경
- 권한 상승이 필요한 명령 실행
판단이 어려우면 승인하지 말고 먼저 질문한다.
이 권한 요청이 정확히 무엇을 하는지 쉬운 말로 설명해 줘.
내 프로젝트 파일 중 어떤 것이 바뀌는지도 알려 줘.
초보자가 승인해도 안전한 작업인지 판단 기준을 말해 줘.
승인 버튼을 누르는 일은 코드 작성만큼 중요하다. 초보자일수록 권한 요청을 작업 단위의 체크포인트로 다루는 편이 좋다.
권한 요청은 승인 버튼이 아니라 변경 범위를 확인하는 체크포인트로 다뤄야 한다.
10. 슬래시 명령은 “작업을 멈추고 정리하는 버튼”처럼 쓴다
Claude Code에는 대화와 작업을 제어하는 슬래시 명령이 있다. 슬래시 명령 문서는 내장 명령과 커스텀 명령의 개념을 설명한다. 초보자에게는 많은 명령을 외우는 것보다, 작업이 길어졌을 때 정리하는 용도로 이해하는 편이 좋다.
처음에는 다음 상황에서만 써도 충분하다.
- 지금까지 무엇을 했는지 요약하고 싶을 때
- 다음 작업을 새로 정리하고 싶을 때
- 같은 요청 템플릿을 반복해서 쓰고 싶을 때
- 대화가 길어져서 맥락이 흐려졌다고 느낄 때
대화가 길어지면 에이전트가 이전 요구사항과 현재 요구사항을 섞어 이해할 수 있다. 이때는 새 기능을 추가하기 전에 현재 상태를 요약하게 한다.
지금까지 변경한 내용을 초보자도 이해할 수 있게 요약해 줘.
그리고 현재 앱에서 동작하는 기능과 아직 없는 기능을 분리해서 정리해 줘.
아직 파일은 수정하지 마.
이 요약을 받은 뒤 다음 기능으로 넘어가면 작업 흐름이 안정된다.
11. 초보자에게 맞는 첫 프로젝트 주제
처음부터 복잡한 서비스를 만들면 Claude Code가 코드를 작성해도 사용자가 검증하기 어렵다. 첫 프로젝트는 상태가 단순하고, 화면에서 바로 결과가 보이고, 외부 API가 없어도 동작하는 것이 좋다.
추천하는 첫 프로젝트는 다음과 같다.
- 할 일 관리 앱
- 독서 기록장
- 지출 메모장
- 운동 체크리스트
- 냉장고 재료 메모장
- 블로그 글 아이디어 보관함
- 여행 준비물 체크리스트
처음 프로젝트로 피하는 편이 좋은 주제도 있다.
- 결제 서비스
- 로그인 기반 커뮤니티
- 주식 자동매매
- 병원, 법률, 세무처럼 정확성이 중요한 서비스
- 개인정보를 많이 저장하는 서비스
- 여러 사용자가 동시에 쓰는 실시간 서비스
나쁜 주제라는 뜻은 아니다. 다만 첫 프로젝트로는 검증해야 할 것이 너무 많다. 초보자는 화면에서 바로 확인되는 개인용 도구부터 시작하는 편이 좋다.
12. 프로젝트 진행 템플릿
아래 템플릿은 코딩을 모르는 사람이 Claude Code와 프로젝트를 만들 때 그대로 복사해서 쓸 수 있는 형태다.
12.1 새 기능을 만들 때
이번에는 아래 기능 하나만 만들고 싶다.
기능:
여기에 기능을 한 문장으로 적는다.
조건:
- 기존 기능은 바꾸지 않는다.
- 관련 없는 파일은 수정하지 않는다.
- 파일을 수정하기 전에 어떤 파일을 바꿀지 먼저 설명한다.
- 수정 후 내가 실행할 명령어와 확인 방법을 알려준다.
나는 코딩 초보자이므로 어려운 용어는 쉽게 설명해 줘.
12.2 디자인만 바꿀 때
이번 작업은 디자인 수정만 한다.
기능 동작은 바꾸지 마.
원하는 디자인:
- 여기에 색상, 배치, 글자 크기, 여백 등을 적는다.
수정 전에 어떤 파일을 바꿀지 먼저 말해 줘.
수정 후 화면에서 무엇을 확인하면 되는지도 알려 줘.
12.3 오류를 고칠 때
아래 오류가 발생했다.
아직 파일을 수정하지 말고 원인을 먼저 설명해 줘.
수정이 필요하다면 어떤 파일을 바꿀지 알려 줘.
내가 실행한 명령어:
여기에 명령어를 붙여넣는다.
오류 메시지:
여기에 오류 전체를 붙여넣는다.
12.4 작업을 마무리할 때
이번 작업을 마무리하기 전에 정리해 줘.
1. 어떤 기능이 추가됐는지
2. 어떤 파일이 바뀌었는지
3. 내가 실행해서 확인해야 할 명령어
4. 아직 남은 위험이나 주의사항
5. 다음에 만들면 좋은 기능 하나
파일은 수정하지 말고 요약만 해 줘.
계획, 요청, 구현, 실행, 검토, 저장을 반복하는 기본 루프다.
13. 내가 권하는 하루짜리 실습 시나리오
코딩을 모르는 사람이 처음 프로젝트를 만든다면 하루 안에 끝나는 범위로 잡는 편이 좋다. 아래 흐름은 할 일 관리 앱 기준이지만, 독서 기록장이나 지출 메모장에도 그대로 적용할 수 있다.
첫 번째 단계는 프로젝트 목표를 정하는 것이다. 앱 이름, 첫 화면, 필수 기능 3개, 제외할 기능을 적는다. 이 문서를 프로젝트 폴더에 PROJECT_PLAN.md 같은 이름으로 저장해도 좋다.
두 번째 단계는 Claude Code에게 계획만 요청하는 것이다. 파일을 수정하지 말고 구현 순서와 첫 작업만 정리하게 한다.
세 번째 단계는 화면 뼈대를 만든다. 제목, 입력창, 버튼, 목록 영역이 보이면 충분하다. 이때 저장 기능은 만들지 않는다.
네 번째 단계는 추가 기능 하나를 붙인다. 입력창에 글을 쓰고 버튼을 누르면 목록에 추가되는 정도면 충분하다.
다섯 번째 단계는 완료 처리나 삭제 중 하나만 붙인다. 두 개를 한 번에 요청하지 않는다.
여섯 번째 단계는 디자인만 다듬는다. 기능과 디자인을 분리해서 작업하면 오류 원인을 찾기 쉽다.
일곱 번째 단계는 git status와 git diff로 변경사항을 확인한다. 문제가 없으면 커밋한다.
git status
git diff
git add .
git commit -m "Create basic todo app"
이 정도만 끝내도 첫 바이브코딩 프로젝트로는 충분하다. 중요한 것은 거대한 서비스를 완성하는 것이 아니라, 작은 기능을 요청하고 확인하고 저장하는 흐름을 몸에 익히는 것이다.
14. 정리
Claude Code로 바이브코딩을 할 때 코딩 지식이 전혀 없어도 시작은 가능하다. 다만 프로젝트를 안정적으로 만들려면 요청을 작게 나누고, 구현 전에 계획을 확인하고, 실행 결과와 변경사항을 계속 검증해야 한다.
초보자에게 가장 중요한 규칙은 다음과 같다.
- 한 번에 기능 하나만 요청한다.
- 구현 전에 계획을 먼저 받는다.
- “예쁘게”보다 구체적인 화면 조건을 쓴다.
- 오류는 요약하지 말고 그대로 붙여넣는다.
- 저장, 로그인, 배포는 나중에 붙인다.
- 권한 요청은 무엇을 바꾸는지 확인한 뒤 승인한다.
CLAUDE.md에 프로젝트 규칙을 남긴다.- 매 단계마다 실행하고
git diff로 확인한다.
바이브코딩은 AI에게 전부 맡기는 방식이 아니라, 사람이 방향과 기준을 정하고 AI가 구현을 돕는 방식이다. 코딩을 모르는 사람일수록 더 작은 단위로 요청해야 하고, 더 자주 확인해야 한다. 그 흐름만 지키면 Claude Code는 첫 프로젝트를 만드는 데 충분히 강력한 도구가 된다.