바이브코딩 서비스를 Docker 컨테이너로 실전서비스 론칭하기 · 1부 — 바이브코딩 셋업부터 컨테이너 실행까지

2장. Claude Code 사용법 익히기

1장에서 아무것도 없던 노트북에 개발 도구를 갖추고, vote-app 폴더를 VS Code로 열어 그 안의 터미널에서 claude까지 실행해 봤습니다. 이제 Claude Code를 "제대로 부리는" 법을 배웁니다. 같은 AI를 써도 잘 시키는 사람과 못 시키는 사람의 결과가 크게 갈리는데, 그 차이가 이 장에서 배우는 몇 가지 기본기에서 나옵니다. 개념을 하나씩 익히고, 작게 직접 해 보면서 감을 잡아 봅시다.

이번 장에서 배우는 것은 우리 투표 서비스를 본격적으로 만들기(4장) 전에 꼭 손에 익혀 둬야 하는 조작법입니다. 그래서 여기서는 아직 투표 서비스를 만들지 않고, hello.txt 같은 작은 예제로 연습만 합니다.

[지금 여기]

우리는 22단계를 거쳐 "라이브 투표 서비스"를 직접 만들고, 컨테이너에 담아, AWS 클라우드에 배포합니다. 아래가 그 전체 여정 지도입니다. 1장에서 개발 환경을 갖췄고, 지금은 2단계에 있습니다.

  1. 1장개발 환경 준비 (터미널 / Node.js / Git / GitHub / VS Code / Claude Code)
  2. 2장Claude Code 사용법 익히기
  3. 3장무엇을 만들지 기획 (라이브 투표 서비스)
  4. 4장로컬에서 서비스 만들기 (React + Express + PostgreSQL)
  5. 5장Docker 개념
  6. 6장Dockerfile 작성
  7. 7장컨테이너 빌드·실행
  8. 8장AWS 시작 (계정 / IAM / 리전 / 비용)
  9. 9장이미지 태깅
  10. 10장ECR에 이미지 올리기
  11. 11장VPC 네트워크 구성
  12. 12장RDS 데이터베이스 생성
  13. 13장SSM 터널로 RDS 초기화
  14. 14장ECS Fargate + ALB로 배포 (기본 완성)
  15. 15장CI/CD (GitHub Actions)
  16. 16장IaC (Terraform)
  17. 17장배포 자동화 연결
  18. 18장현업 운영 구조 이해
  19. 19장무중단 배포
  20. 20장신규 버전 배포 & 롤백
  21. 21장(심화) 프론트를 Vercel로 분리 배포
  22. 22장마무리 (회고 + 리소스 삭제)

이번 장에서 완성되는 것

한 문장으로: Claude Code에게 일을 시키고(프롬프트) → 변경을 승인하고(권한) → 결과를 확인하는 한 바퀴 흐름을, 작은 예제로 직접 돌려 볼 수 있게 됩니다.

이렇게 되면 성공입니다: vote-app 폴더에서 Claude Code로 hello.txt 파일을 만들어 승인해 보고, 계획 모드와 슬래시 명령을 한 번씩 써 보고, /init으로 CLAUDE.md 파일이 생기는 것까지 눈으로 확인합니다.

사전 조건

이 장은 1장의 결과물 위에서 시작합니다. 아래가 갖춰져 있어야 합니다.

혹시 컴퓨터를 껐다 켰거나 VS Code를 닫았다면, 다시 이렇게 준비하세요.

  1. VS Code를 실행하고, File(파일) → Open Folder…(폴더 열기)로 문서 폴더의 vote-app을 엽니다. (왼쪽 위에 VOTE-APP이 보이면 됩니다.)
  2. 위쪽 메뉴에서 Terminal(터미널) → New Terminal(새 터미널)을 눌러 VS Code 통합 터미널을 엽니다.
  3. 터미널에서 아래로 위치를 확인합니다.
pwd          # 지금 터미널이 있는 폴더의 경로를 보여 줍니다

경로 끝이 /vote-app이면(예: /Users/mac/Documents/vote-app) 제대로 온 것입니다. 아니라면 1장 1.6절로 돌아가 vote-app을 다시 여세요.

  1. 이 터미널에 claude를 입력하고 Enter를 눌러 Claude Code를 실행합니다. AI 입력창이 뜨면 준비 완료입니다.
참고

앞으로 이 책에서 "터미널"이라고 하면 언제나 이 VS Code 통합 터미널을 뜻합니다. 그리고 이 장의 모든 요청(프롬프트)은 그 터미널 안에서 실행 중인 Claude Code 입력창에 입력합니다.

2.1 대화의 기본 — 명확하게 지시하기

1장에서 배운 대로, AI에게 건네는 지시문을 프롬프트라고 합니다. 바이브코딩의 실력은 곧 이 프롬프트를 얼마나 명확하게 쓰느냐입니다. AI는 똑똑하지만 독심술사는 아닙니다. 두루뭉술하게 말하면 두루뭉술한 결과가, 구체적으로 말하면 원하는 결과가 나옵니다.

같은 요청을 두 가지 방식으로 비교해 봅시다.

프롬프트

아쉬운 예

투표 사이트 만들어 줘

이렇게만 하면 AI는 세부 사항을 스스로 추측해서 만듭니다. 내가 상상한 것과 다른 결과가 나오기 쉽습니다.

프롬프트

좋은 예

간단한 투표 웹 서비스를 만들 거야. 다음 조건을 지켜 줘.
- 질문 하나와 선택지 여러 개를 만들 수 있다
- 사용자가 선택지에 투표할 수 있다
- 각 선택지가 몇 표 받았는지 막대그래프로 보여 준다
우선 전체 구조를 어떻게 잡을지 계획부터 설명해 줘. 아직 코드는 만들지 마.

좋은 프롬프트에는 세 가지가 들어 있습니다.

  1. 무엇을 만드는지 (투표 웹 서비스)
  2. 구체적인 조건 (질문/선택지/투표/막대그래프)
  3. 지금 원하는 행동 ("계획부터 설명해, 아직 코드는 만들지 마")

특히 세 번째가 중요합니다. AI에게 "지금 무엇을 해 달라"를 분명히 하면 엉뚱한 방향으로 한참 나가는 일을 막을 수 있습니다.

참고

한국어로 편하게 쓰세요 Claude Code는 한국어를 잘 이해합니다. 문법을 신경 쓰거나 영어로 쓸 필요 없이, 동료에게 설명하듯 편하게 쓰면 됩니다.

2.2 Claude Code가 실제로 하는 일 — 그리고 권한 승인

Claude Code가 웹 챗봇과 다른 결정적인 지점이 여기입니다. Claude Code는 말로만 답하지 않고 실제로 내 컴퓨터의 파일을 만들고, 고치고, 명령어를 실행합니다. 그런데 내 컴퓨터를 함부로 바꾸면 위험하겠죠. 그래서 Claude Code는 뭔가를 바꾸기 전에 "이렇게 바꿔도 될까요?"라고 먼저 물어보고, 내가 허락(승인)해야 실행합니다.

용어

도구(툴, Tool) Claude Code가 실제 작업을 할 때 쓰는 기능들입니다. 파일을 만드는 도구, 파일을 고치는 도구, 터미널 명령을 실행하는 도구 등이 있습니다. AI가 "파일을 만들겠다"고 하면 내부적으로 파일 생성 도구를 쓰는 겁니다.

용어

권한 승인(Permission) Claude Code가 파일을 고치거나 명령을 실행하기 직전에 사용자에게 허락을 구하는 절차입니다. 화면에 "무엇을 할 것인지" 보여 주고, 여러분이 승인/거절을 고를 수 있습니다.

[활용 사례] Claude Code로 실무에서 하는 일 — 이런 것들에 승인이 붙습니다

Claude Code가 하는 일은 파일 하나 만드는 데 그치지 않습니다. 실제 개발에서 이런 다양한 일을 시킵니다. 그리고 아래 대부분은 내 컴퓨터를 바꾸는 일이라, 실행 직전에 권한 승인을 한 번씩 물어봅니다.

핵심은, 무엇을 시키든 "내 컴퓨터를 바꾸는 순간"에는 항상 여러분의 확인을 거친다는 점입니다. 그래서 마음 놓고 이것저것 시켜 볼 수 있습니다.

[맛보기] 파일 하나 만들며 승인 직접 해 보기

말로만 들으면 감이 안 오니 직접 해 봅시다. Claude Code 입력창에 이렇게 요청해 보세요. (우리 투표 서비스와 상관없는, 연습용 파일입니다.)

프롬프트
이 폴더에 hello.txt 라는 파일을 만들고,
그 안에 "첫 번째 파일입니다" 라고 적어 줘.

그러면 Claude Code는 곧바로 파일을 만들지 않고, 아래와 비슷한 확인 화면을 보여 줍니다.

그리고 승인을 기다립니다. 보통 이런 선택지가 번호와 함께 나옵니다. 숫자 키(1, 2, 3)를 누르거나, 위아래 화살표로 골라 Enter를 눌러 선택합니다.

지금은 Yes(보통 1번)를 골라 승인해 봅시다. 잠시 뒤 hello.txt 파일이 실제로 만들어집니다.

사용자 요청예: hello.txt 만들어 줘승인 화면 (권한 요청)무엇을 바꿀지 보여 주고 기다린다Yes — 승인이번 작업만 실행Yes, 앞으로 안 물음비슷한 작업 자동 실행No — 거절취소 · 이유 말하면 재시도내가 고르기 전에는 아무것도 바뀌지 않는다

[확인] 파일이 정말 생겼는지 봅시다. VS Code 왼쪽 파일 탐색기(폴더 이름 VOTE-APP 아래 목록)를 보면 방금 만든 hello.txt가 새로 나타나 있습니다. 클릭해서 열면 "첫 번째 파일입니다"라고 적혀 있습니다. 방금 여러분은 AI에게 시키고 → 승인하고 → 결과를 확인하는 한 바퀴를 처음 돌려 본 겁니다.

주의

승인 화면이 뜨면 내용을 한 번 읽어 보는 습관을 들이세요. 특히 파일을 삭제하거나 시스템을 바꾸는 명령은 무엇을 하려는지 확인한 뒤 승인하는 것이 안전합니다.

[용어] 권한 모드 — 승인을 얼마나 자주 물을지 정하기

매번 승인 버튼을 누르는 게 번거로울 때를 위해, Claude Code에는 몇 가지 "권한 모드"가 있습니다. 상황에 맞게 골라 쓰면 됩니다.

실행 중에 Shift + Tab를 누르면 이 모드들이 차례로 번갈아 바뀝니다. 지금 어떤 모드인지는 입력창 아래쪽에 표시됩니다. 지금은 초보자에게 권장하는 기본 모드로 두고 진행합시다. (Shift + Tab을 눌러 봤다면, 다시 눌러 표시가 기본 상태로 돌아오게 해 두세요.)

참고

이 밖에 모든 승인을 건너뛰는 위험한 모드(bypassPermissions)도 있지만, 내 컴퓨터를 확인 없이 바꿀 수 있어 초보자에게는 권하지 않습니다. 이 책에서는 기본 모드와, 가끔 계획 모드만 씁니다.

2.3 계획 모드 (Plan Mode)

큰 작업일수록, 곧바로 만들게 하기보다 "어떻게 만들지 계획부터" 물어보는 게 좋습니다. 계획을 보고 방향이 맞는지 먼저 확인하면, 엉뚱하게 많이 만들어 놓고 되돌리는 낭비를 줄일 수 있습니다. 이걸 도와주는 게 계획 모드입니다.

용어

계획 모드(Plan Mode) Claude Code가 파일을 전혀 바꾸지 않고, 코드베이스를 읽어 보기만 한 뒤 "이렇게 만들겠다"는 계획만 세워서 보여 주는 모드입니다. 계획을 검토하고 여러분이 승인해야 실제 작업이 시작됩니다. 파일을 건드리지 않으니 마음 놓고 방향을 잡아 볼 수 있습니다.

[활용 사례] 계획 모드는 이럴 때 씁니다

[맛보기] 계획 모드로 작은 요청 해 보기

계획 모드로 들어가는 방법은 두 가지입니다. 어느 쪽이든 됩니다.

여기서는 방법 B로 해 봅시다. 우리 투표 서비스와는 분리된, 아주 작은 연습 요청입니다.

프롬프트
아주 간단한 메모장 웹페이지를 만든다면 어떤 파일들이 필요하고
어떤 순서로 만들면 될지, 코드는 아직 만들지 말고 계획만 세워 줘.

Claude Code가 파일을 하나도 만들지 않고, "이런 파일을 이런 순서로 만들겠다"는 계획을 글로 보여 줍니다.

[확인] VS Code 왼쪽 파일 탐색기를 보세요. 방금 요청으로 새로 생긴 파일이 없어야 합니다. (아까 만든 hello.txt만 그대로 있습니다.) 계획만 세우고 파일은 건드리지 않는 것 — 이게 계획 모드의 핵심입니다.

Shift + Tab으로 계획 모드에 들어가 있었다면, 다시 Shift + Tab을 눌러 아래쪽 표시가 기본 모드로 돌아오게 해 두세요. 다음 절부터는 기본 모드로 진행합니다.

2.4 핵심 흐름 — 계획하고 → 만들고 → 실행해 보기

바이브코딩은 보통 다음 세 단계를 반복하며 진행됩니다. 이 리듬을 익혀 두면 어떤 기능이든 같은 방식으로 만들어 나갈 수 있습니다.

1단계. 계획하기 (Plan) — 방금 배운 계획 모드로, 무엇을 어떻게 만들지 방향을 먼저 잡습니다. 큰 작업일수록 이 단계가 시간을 아껴 줍니다.

2단계. 만들기 (Build) — 계획이 마음에 들면 "그대로 만들어 줘"라고 합니다. 이때 Claude Code가 파일들을 만들고 고치며, 2.2절에서 배운 권한 승인 과정을 거칩니다.

3단계. 실행해 보기 (Run) — 만든 것이 실제로 동작하는지 돌려 봐야 합니다. 다행히 실행도 Claude Code에게 맡길 수 있습니다. "만든 걸 실행해서 잘 되는지 확인해 줘"라고 하면, 필요한 명령을 실행하고(이때도 승인을 거칩니다) 결과를 알려 줍니다.

이 세 단계 — 계획 → 만들기 → 실행 — 를 한 바퀴 돌리고, 결과를 보고 다음 요청을 하고, 또 한 바퀴 돌리는 식으로 서비스가 완성돼 갑니다. 4장에서 우리 투표 서비스를 만들 때 이 리듬을 그대로 씁니다.

계획하기어떻게 만들지 먼저만들기승인하며 파일 생성실행해 보기동작하는지 확인결과를 보고 다음 요청 — 다시 한 바퀴

2.5 결과 확인하는 법

AI가 "다 만들었습니다"라고 해도, 그대로 믿기보다 직접 확인하는 습관이 중요합니다. 확인하는 방법은 두 가지입니다.

방법 1. 파일을 눈으로 열어 보기

VS Code 왼쪽 파일 탐색기(폴더 이름 VOTE-APP 아래 목록)에 AI가 만든 파일들이 그대로 보입니다. 궁금한 파일을 클릭하면 오른쪽에 내용이 열립니다. "아, 이런 파일들이 생겼구나" 정도만 파악하면 충분합니다. 코드를 완벽히 이해할 필요는 없습니다. (앞서 hello.txt를 열어 본 것과 똑같은 방법입니다.)

참고

Claude Code는 지금 열려 있는 이 vote-app 폴더 안에서만 파일을 만들고 고칩니다. 그래서 결과는 항상 VS Code 왼쪽 파일 탐색기에서 바로 확인할 수 있습니다.

방법 2. 실제로 실행해서 눈으로 확인하기

가장 확실한 확인은 서비스를 실행해 브라우저에서 직접 보는 것입니다. 웹 서비스를 만들었다면 보통 이렇게 요청합니다.

프롬프트
지금까지 만든 걸 로컬에서 실행해 줘.
그리고 브라우저에서 어떤 주소로 접속하면 되는지 알려 줘.

Claude Code가 서비스를 실행하고(명령 실행이라 승인을 한 번 거칩니다) 접속 주소(예: http://localhost:3000)를 알려 줍니다. 그 주소를 브라우저에 입력해 화면이 뜨는지 확인합니다.

용어

로컬(Local)과 localhost "로컬"은 인터넷 서버가 아니라 지금 내 컴퓨터 안을 뜻합니다. localhost는 "내 컴퓨터 자신"을 가리키는 주소입니다. 즉 http://localhost:3000은 "내 컴퓨터에서 돌고 있는 서비스에 접속한다"는 뜻입니다. 아직 인터넷에 공개된 게 아니라 나만 볼 수 있습니다.

2.6 막혔을 때 — 오류를 그대로 붙여넣기

개발을 하다 보면 반드시 오류(에러)를 만납니다. 이건 실패가 아니라 지극히 정상적인 과정입니다. 중요한 건 오류를 만났을 때 어떻게 하느냐인데, 바이브코딩에서는 아주 간단합니다.

용어

오류(에러, Error) 프로그램이 예상과 다르게 동작하거나 실행되지 않을 때 컴퓨터가 내보내는 메시지입니다. 보통 빨간 글씨로 여러 줄 나오는데, 여기에 원인을 찾을 단서가 들어 있습니다.

해결법: 오류 메시지를 통째로 복사해서 붙여넣기

터미널이나 브라우저에 나온 오류 메시지를 복사해서, Claude Code 입력창에 그대로 붙여넣고 고쳐 달라고 하면 됩니다.

프롬프트
실행했더니 아래 오류가 났어. 원인을 설명하고 고쳐 줘.

(여기에 복사한 오류 메시지를 그대로 붙여넣기)

Claude Code가 오류의 원인을 짚어 주고, 고칠 방법을 제안한 뒤 승인을 받아 수정합니다. 오류 메시지를 "요약하거나 다듬지 말고" 있는 그대로 붙여넣는 게 요령입니다. 그래야 AI가 정확한 단서를 얻습니다.

참고

화면이 이상하게 나오는 것처럼, 오류 메시지가 없는 문제라면 "이런 걸 기대했는데 실제로는 이렇게 나온다"고 상황을 구체적으로 설명해 주면 됩니다. 가능하면 화면을 캡처해 보여 줘도 좋습니다.

2.7 슬래시 명령 (/)

지금까지는 "말"로 지시했습니다. 그 외에, Claude Code에는 자주 쓰는 기능을 빠르게 부르는 슬래시 명령이 따로 있습니다.

용어

슬래시 명령(Slash Command) 입력창에서 슬래시(/)로 시작하는 특수 명령입니다. 일반 대화가 아니라 Claude Code에 내장된 기능을 곧바로 실행합니다. 입력창에 /만 쳐도 쓸 수 있는 명령 목록이 자동으로 떠서, 화살표로 골라 쓸 수 있습니다.

[활용 사례] 자주 쓰는 슬래시 명령들

[맛보기] /help 한 번 열어 보기

Claude Code 입력창에 아래를 입력하고 Enter를 누르세요.

프롬프트
/help

사용할 수 있는 명령과 단축키 목록이 화면에 뜹니다. 지금 다 외울 필요는 없습니다. "이런 게 있구나" 하고 훑어보면 됩니다. 목록을 닫으려면 안내에 따라 EnterEsc를 누릅니다.

참고

입력창에 슬래시(/) 하나만 쳐 봐도, 쓸 수 있는 명령들이 자동으로 아래에 뜹니다. 위아래 화살표로 원하는 명령을 골라 Enter를 누르면 그 명령이 입력됩니다.

2.8 프로젝트 지침 파일 (CLAUDE.md)

마지막으로, AI에게 우리 프로젝트의 규칙을 미리 알려 두는 방법을 익힙니다. 앞서 본 /init 슬래시 명령을 여기서 실제로 써 봅니다.

용어

CLAUDE.md 프로젝트 폴더에 두는 "AI를 위한 안내문" 파일입니다. 여기에 적어 둔 내용을 Claude Code가 대화할 때마다 자동으로 참고합니다. 예를 들어 "이 프로젝트는 React와 Express를 쓴다", "설명은 한국어로 해 달라" 같은 규칙을 적어 두면, 매번 반복해서 말하지 않아도 됩니다.

[활용 사례] CLAUDE.md에는 이런 걸 적어 둡니다

이렇게 해 두면, 새 대화를 시작할 때마다 같은 설명을 반복하지 않아도 Claude Code가 우리 프로젝트의 규칙을 알고 움직입니다.

[맛보기] /init으로 CLAUDE.md 만들어 보기

직접 손으로 파일을 만들 수도 있지만, Claude Code에게 자동으로 만들어 달라고 하는 게 편합니다. 입력창에 아래를 입력하고 Enter를 누르세요.

프롬프트
/init

/init은 지금 프로젝트를 살펴본 뒤 기본 CLAUDE.md 파일을 만들어 주는 내장 명령입니다. 파일을 만드는 작업이라 2.2절에서 배운 것처럼 승인을 한 번 물어봅니다. Yes를 눌러 승인하세요. 지금은 폴더가 거의 비어 있으니(hello.txt 하나뿐) 아주 간단한 내용으로 만들어집니다.

[확인] VS Code 왼쪽 파일 탐색기에 CLAUDE.md 파일이 새로 생겼는지 보세요. 클릭해서 열면 이 프로젝트에 대한 간단한 설명이 적혀 있습니다. 나중에 4장에서 투표 서비스가 자라면, 이 파일에 규칙을 덧붙여 나가면 됩니다.

연습 파일 정리 (선택)

이 장에서 연습으로 만든 hello.txt는 우리 투표 서비스와 상관없는 파일입니다. 지우고 싶다면 Claude Code에게 이렇게 부탁하면 됩니다. (파일 삭제도 승인을 물어봅니다. CLAUDE.md는 남겨 두세요.)

프롬프트
연습으로 만든 hello.txt 파일을 삭제해 줘. CLAUDE.md 는 그대로 둬.

[확인]

이번 장이 제대로 끝났는지 눈으로 확인합니다.

여기까지 보였다면 Claude Code를 부리는 기본기가 갖춰진 것입니다.

막히면

이 장에서 초보자가 자주 막히는 지점과 대처법입니다.

[체크리스트]

아래가 모두 됐는지 확인해 보세요. 하나라도 안 됐다면 해당 절로 돌아가 다시 진행합니다.

모두 체크됐다면 Claude Code를 부리는 기본기가 갖춰진 겁니다.