Code Gear - AI 개발 유튜브 강의

지난 글에서 책이 나오기까지의 이야기를 풀어놓았는데, 정작 중요한 질문에는 답을 안 했더라고요.

"그래서, 그 책에는 뭐가 들어 있나요?"

오늘은 그 답을 드리려고 합니다. 『밑바닥부터 따라하면서 배우는 클로드 코드 완전 정복』이 어떤 책이고 누구에게 필요한지, 목차를 따라가며 소개하겠습니다.

→ 책이 나오기까지의 이야기가 궁금하다면: https://codegear.tistory.com/162

한 줄로 말하면

AI에게 말로 설명해서 프로그램을 만드는 개발 방식, 요즘 말로 '바이브 코딩'을 클로드 코드(Claude Code)로 처음부터 끝까지 따라 해보는 입문서입니다.

개념 설명으로 끝나지 않습니다. 설치도 하기 전에 브라우저에서 무료로 첫 웹페이지를 만들어보는 것으로 시작해서, 마지막에는 직접 만든 웹 서비스를 클라우드에 배포하고 GitHub에 자동 코드 리뷰까지 붙입니다. 360쪽 내내 손을 움직이게 되실 거예요.

이런 분께 필요합니다

• 코딩은 처음이지만, AI로 뭔가 만들어보고 싶은 분
• 지금 쓰는 도구에서 AI 코딩 도구로 갈아타려는 현업 개발자
• 바이브 코딩, 에이전틱 코딩이라는 말은 들었는데 실체가 궁금한 분
• 클로드 코드를 깔아는 봤는데, 어디서부터 시작할지 막막했던 분

반대로 특정 언어의 문법을 깊이 배우고 싶은 분께는 맞지 않습니다. 이 책의 관심사는 "AI와 함께 만드는 법"이지 문법 강의가 아니거든요.

장별로 살펴보면

1장 「AI와 개발 패러다임의 변화」에서는 도구 사용법으로 바로 뛰어들지 않고 큰 그림부터 그립니다. 바이브 코딩과 에이전틱 코딩이 무엇이고 왜 등장했는지, 그리고 AI 코딩 도구를 대화형, 웹앱 빌더, IDE 통합형, 에이전트형 네 가지로 나눠 비교합니다. "내게 맞는 도구가 뭘까, 왜 클로드 코드일까"를 스스로 판단할 수 있게 하는 장입니다.

2장 「클로드 코드 기초」는 맛보기 실습으로 시작합니다. 설치 없이, 무료로, 브라우저에서 1분 만에 자기소개 웹페이지를 만들어봅니다. 입문서를 읽다 보면 실습이 너무 늦게 나와서 지치는 경우가 많은데, 그 순서를 뒤집었습니다. 첫 성공을 맛본 다음에 요금제와 회원 가입, 터미널 기초, 설치와 로그인, VS Code·IntelliJ 연동을 차례로 짚고, 브라우저에서 바로 쓰는 Claude Code on the Web까지 다룹니다.

3장 「바이브 코딩 기초」는 제가 이 책에서 가장 공들인 장입니다. 머릿속의 막연한 '느낌'을 구체적인 코드로 바꾸는 법, 결과가 어긋났을 때 오류를 수정하는 법, 효과적인 프롬프트 작성법, 그리고 AI에게 얼마나 깊이 고민하게 할지 조절하는 사고 강도 제어까지. 실습으로는 개발자 포트폴리오 사이트와 토큰 계산기를 직접 만듭니다.

4장 「클로드 코드 고급 활용법」에는 한 단계 위로 올라가는 기능을 모았습니다. 슬래시 명령어, 에이전트 스킬, 서브에이전트, 훅, MCP를 다루고, 공식 마켓플레이스가 열린 플러그인도 여기서 소개합니다. 이름만 들으면 어렵게 느껴지는 것들인데, 하나씩 직접 써보며 익히는 구성입니다.

5장 「AI 에이전트 기반의 풀스택 개발 워크플로」에서는 앞에서 배운 걸 모두 모아 앱 하나를 처음부터 끝까지 만듭니다. 프로젝트 설계, 소스 구현, 서버 실행과 디버깅, 구글 로그인 연동, 기능 테스트, 깃허브 소스 관리를 거쳐 마지막에는 무료 클라우드에 배포합니다. 이 장을 마치면 내가 만든 서비스를 남에게 링크로 보여줄 수 있게 됩니다.

6장 「클로드 코드를 활용한 코드 품질 개선」은 새로 만들기보다 이미 있는 코드를 다루는 장입니다. 레거시 코드 분석, 디버깅, 리팩터링, 보안 취약점 점검, 테스트 케이스 생성, 문서화, 데이터베이스 관리. 마지막에는 실전 예시로 GitHub PR에 자동 코드 리뷰가 달리도록 만들어봅니다.

마지막 7장 「마치며」에서는 AI 시대에 개발의 주도권을 어떻게 지킬지, 개발자는 어떻게 성장해야 할지를 짚습니다. 부록에는 책을 덮은 뒤 이어서 볼 만한 추천 학습 자료를 정리했습니다.

이 책으로 만들게 되는 것들

말로 설명하는 것보다 결과물 목록이 빠르겠네요. 책을 따라가면 이런 것들이 손에 남습니다.

1. 자기소개 웹페이지 — 설치 없이 브라우저에서, 1분
2. 개발자 포트폴리오 사이트 — 프롬프트 작성과 오류 수정을 여기서 연습합니다
3. 토큰 계산기 — PRD로 요구사항을 전달하는 법을 익힙니다
4. 구글 로그인이 되는 풀스택 웹 서비스 — 설계부터 배포까지
5. GitHub PR 자동 코드 리뷰 — 회사 프로젝트에도 바로 써먹을 수 있는 자동화

AI 책은 금방 낡지 않나요?

책을 쓰는 내내 저를 괴롭힌 질문이고, 독자분들이 가장 걱정하실 부분이라고 생각합니다. 그래서 두 가지를 준비했습니다.

하나, 책 자체를 특정 버전의 화면과 기능에 묶이지 않게 썼습니다. 유행하는 기능 나열이 아니라, 시간이 지나도 유효한 원리와 워크플로 중심으로요.

둘, 출간 이후의 변화는 깃허브 저장소에 계속 정리하고 있습니다. 저장소에는 장별 예제 코드 전체와 클로드 코드 치트시트, 그리고 출간 뒤 새로 나온 모델과 기능을 담은 업데이트 문서가 들어 있습니다. 전부 무료입니다.

💻 https://github.com/wikibook/mastering-claude-code

궁금한 점이나 오탈자 제보는 저장소 이슈로 남겨주시면 제가 직접 확인합니다.

책 정보

『밑바닥부터 따라하면서 배우는 클로드 코드 완전 정복』
바이브 코딩 입문자부터 풀스택 개발자까지, 모두를 위한 클로드 코드 완전 활용법
엄태효 지음 | 위키북스 | 2026년 6월 24일 출간 | 360쪽 | 28,000원

구매하실 수 있는 곳

• 교보문고: https://product.kyobobook.co.kr/detail/S000220273082
• 예스24: https://www.yes24.com/product/goods/192047818
• 알라딘: https://www.aladin.co.kr/shop/wproduct.aspx?ItemId=395837303

사기 전에 훑어보고 싶다면 교보문고 미리보기로 앞부분을 읽어보실 수 있습니다.

• 미리보기: https://product.kyobobook.co.kr/book/preview/S000220273082

🎬 이 책이 나오기까지의 이야기는 영상으로도 담았습니다.

• https://youtu.be/87_rgehG5PY

읽어주셔서 감사합니다. 궁금한 게 있으면 댓글로 편하게 물어봐 주세요. 🙌

클로드 코드를 실무 프로젝트에 깊숙이 도입해 보면 이내 장벽에 부딪히게 된다. 초기에는 뛰어난 성능을 보여주던 에이전트가 대화 세션이 길어질수록 엉뚱한 코드를 짜거나, 바로 직전에 지시한 규칙을 잊어버리는 현상을 자주 겪기 때문이다.

이러한 한계는 모델 자체의 결함이라기보다, 에이전트의 핵심 작동 메커니즘을 오해하고 잘못 다루었을 때 발생하는 경우가 많다. 클로드 코드를 프로덕션 환경에서 견고한 도구로 통제하기 위해 반드시 이해해야 할 3가지 핵심 설계 원칙을 정리한다.

1. 컨텍스트 윈도우를 철저하게 제어하라

클로드 코드를 다룰 때 개발자가 관리해야 할 가장 귀중한 자원은 바로 컨텍스트(Context) 다.

사용자가 입력한 대화 기록, 에이전트가 읽어 들인 소스 코드 파일, 실행한 명령어의 터미널 출력값, 첨부한 이미지 등은 모두 '컨텍스트 윈도우(Context Window)'라는 하나의 작업 공간에 차곡차곡 누적된다. 이 공간이 가득 차면 모델은 이전 맥락을 유실하기 시작하며, 지시를 잊거나 추론 실수가 눈에 띄게 증가한다. 뒤에서 언급할 /clear 명령어, 서브에이전트 활용, 짧은 CLAUDE.md 설정 등은 모두 이 컨텍스트 자원을 아끼기 위한 구체적인 처방들이다.

특히 이미지를 가볍게 다루어서는 안 된다. 모델은 이미지를 시각 자료 그대로 받아들이는 것이 아니라, 잘게 쪼개어 수많은 토큰(Token)으로 변환한 뒤 컨텍스트 윈도우에 밀어 넣는다. 고해상도 스크린샷 한 장이 수백에서 수천 단어 분량의 텍스트와 맞먹는 공간을 차지하므로, 이미지 오용은 컨텍스트를 고갈시키는 주범이 된다.

"1M 토큰 시대에 굳이 컨텍스트를 아껴야 하는가?"

2026년 3월 13일부로 Opus 4.6 및 Sonnet 4.6 모델에서 100만(1M) 토큰 컨텍스트 윈도우가 정식 제공되기 시작했다. 대규모 코드베이스를 통째로 밀어 넣어도 남을 만큼 여유로운 용량이다. 그러나 용량이 커졌다고 해서 자원 관리가 무의미해진 것은 아니다. 오히려 대용량 컨텍스트 환경이기 때문에 관리의 필요성은 더욱 커졌다. 그 기술적 근거는 다음과 같다.

① 수용 용량과 추론 성능은 비례하지 않는다

100만 토큰은 모델이 한 번에 '입력받을 수 있는 최대 한계치'일 뿐, 그 안에 담긴 모든 정보가 균일하게 활용되고 분석된다는 보장이 아니다. 정보의 절대량이 늘어날수록 모델이 처리해야 할 노이즈도 함께 증가한다. 넓은 책상을 쓴다고 해서 구석에 밀어둔 서류의 메모 내용까지 사람이 또렷하게 기억할 수 없는 것과 같은 이치다.

② 컨텍스트 로트(Context Rot) 현상

컨텍스트 로트란 대화 세션이 길어지고 정보가 누적될수록 모델의 정확도와 회상률(Recall)이 서서히 감퇴하는 현상이다.

우유가 상하는 과정을 생각하면 이해하기 쉽다. 냉장고에 넣어둔 우유가 유통기한 마지막 날에 한순간에 상하는 것이 아니다. 냉장고 문을 열고 닫는 순간부터 눈에 보이지 않게 조금씩 변질되어 가며, 어느 날 마셔보고 나서야 상태가 이상함을 인지할 뿐이다. 컨텍스트 역시 특정 한계에 도달해 한 번에 무너지는 것이 아니라, 정보가 채워지는 과정에서 처음부터 서서히 성능이 열화된다. "아직 1M 용량이 남았으니 안전하다"고 맹신할 수 없는 이유다.

③ 'Lost in the Middle' 현상의 실제와 한계

거대 언어 모델은 입력된 컨텍스트의 맨 앞과 맨 뒤에 위치한 정보에 집중하며, 중간에 파묻힌 정보는 쉽게 유실하는 경향이 있다.

이 현상은 스탠퍼드 연구진(Percy Liang 등)이 동료 심사 학술지 TACL에 게재한 논문 「Lost in the Middle: How Language Models Use Long Contexts」에서 학술적으로 명확히 규명되었다.

*"We observe that performance is often highest when relevant information occurs at the beginning or end of the input context, and significantly degrades when models must access relevant information in the middle of long contexts, even for explicitly long-context models."*

[번역] "우리는 관련 정보가 입력 문맥의 시작이나 끝에 배치될 때 성능이 가장 높았으며, 긴 문맥의 중간에 있는 관련 정보에 액세스해야 할 때 성능이 크게 떨어진다는 것을 관찰했습니다. 이는 장문맥 처리를 위해 특별히 개발된 모델에서도 동일하게 나타났습니다."

단, 이 연구 결과를 오늘날의 클로드 코드에 그대로 기계적으로 대입하는 것은 경계해야 한다.

• 시점의 차이: 해당 연구는 2023년에 수행되어 당시 세대의 모델(Claude-1.3, GPT-3.5-Turbo 등)을 대상으로 했다.
• 규모의 차이: 실험에 사용된 컨텍스트 크기는 2K~16K 토큰 수준으로, 오늘날의 1M 크기와는 수십 배 이상의 차이가 존재한다.
• 태스크의 차이: 논문은 다문서 QA와 키-값 검색을 다루었으므로, 유기적인 소스 코드 분석 및 함수 호출 추적 작업과는 결이 다르다.
• 성능의 지속적 향상: 앤트로픽의 최신 Opus 모델은 세대를 거듭하며 장문맥 추론 점수가 크게 향상되고 있다.

그럼에도 불구하고 이 논문이 시사하는 바는 명확하다. 정보의 절대적인 배치 위치가 모델 추론에 영향을 미친다는 현상 자체는 실재하며, 컨텍스트 윈도우가 극적으로 확장된 지금은 오히려 잃어버릴 수 있는 '중간 지대'가 훨씬 더 광활해졌음을 뜻한다.

④ 멀티홉(Multi-hop) 추론 성능의 저하

코딩은 여러 파일과 함수, 설정을 유기적으로 추적해야 하는 대표적인 멀티홉 작업이다. 최종 답안을 도출하기 위해 정보의 고리를 여러 단계에 걸쳐 타고 넘어가야 하기 때문이다.

지하철 환승에 비유할 수 있다. 한 번에 가는 직행 노선은 길을 잃을 염려가 없지만, 여러 번 환승해야 하는 노선은 중간에 사슬 하나만 끊어져도 목적지와 전혀 다른 곳에 도달하게 된다.

앤트로픽이 공개한 Opus 4.8 시스템 카드에 따르면, 거대한 그래프 구조를 순회하게 만드는 멀티홉 추론 테스트인 GraphWalks BFS(F1) 실험에서 아주 명확한 상관관계가 나타난다.

• 256K 서브셋 (윈도우를 일부만 채웠을 때): 85.9%
• 1M 서브셋 (윈도우를 가득 채웠을 때): 68.1%

동일한 최신 모델을 사용했음에도 컨텍스트 윈도우를 꽉 채워 쓰자 멀티홉 추론 성능이 17.8%p나 급감했다. 코딩 과정에서 가장 필수적인 다단계 참조 능력이, 역설적으로 컨텍스트가 차오를 때 가장 먼저 취약해짐을 증명한다.

💡 실천적 컨텍스트 관리 전략

• 주제가 바뀌면 즉시 /clear를 실행하라
  버그 수정을 끝내고 신규 기능 구현이나 리팩토링으로 넘어갈 때는 이전 세션의 잔재를 완전히 비워내야 한다. 한 세션에 여러 작업을 뒤섞어 수행하는 '잡탕 세션'이 컨텍스트 오염의 주원인이다.
• 탐색성 작업은 서브에이전트에게 위임하라
  "로그인 흐름이 어디서 시작되는지 찾아달라"와 같은 코드 탐색 작업은 메인 창이 아닌 @explore 서브에이전트를 호출하여 처리해야 한다.

📌 @explore 서브에이전트 작동 방식

❯ @explore "로그인 흐름이 시작되는 진입점 파일을 찾아줘"

서브에이전트는 완전히 격리된 별도의 컨텍스트 윈도우에서 작동한다. 수십 개의 소스 파일을 열어보며 발생한 수만 토큰의 찌꺼기는 서브에이전트 세션의 종료와 함께 소멸하며, 메인 대화창에는 정돈된 요약 정보만 전달되므로 메인 컨텍스트를 깨끗하게 유지할 수 있다.

• /compact 명령어는 목적성을 갖고 사용하라
  대화 흐름을 유지하되 컨텍스트를 비우는 /compact 명령어는 기본적으로 대화를 요약하는 '손실 압축' 방식이다. 중요 규칙이나 세부 제약 조건이 누락될 위험이 있으므로, /compact "인증 관련 결정사항은 반드시 유지해줘"와 같이 보존해야 할 핵심 맥락을 직접 지정하여 실행하는 것이 안전하다.

2. 지시 사항은 대화가 아닌 파일에 명문화하라

클로드 코드를 사용하며 세션마다 "진행 상황은 한국어로 설명해라", "테스트 코드는 특정 라이브러리를 써라"와 같은 지시를 반복하는 경우가 많다. 이는 에이전트의 작동 원리를 오해한 비효율적인 접근이다.

"대화창을 통한 지시는 세션이 종료되는 즉시 소멸한다."

새로운 세션이 시작되면 에이전트는 이전 대화의 약속을 기억하지 못하며, 모델 고유의 기본 경향성(예: 영문 출력, 기본 구조 선호)으로 회귀한다.

해결책: CLAUDE.md 파일 활용

매번 반복해야 하는 프로젝트 고유의 규칙, 코딩 컨벤션, 언어 설정 등은 전역 설정 파일(~/.claude/CLAUDE.md) 또는 프로젝트 루트의 CLAUDE.md 파일에 기록해야 한다.

# 프로젝트 규칙
- 모든 대화와 작업 요약은 한국어로 진행합니다.
- 예외적으로 변수명, 주석, 커밋 메시지 등 코드와 관련된 자산은 영문 컨벤션을 따릅니다.
- 외부 라이브러리 도입 전 반드시 사용자에게 승인을 요청합니다.

CLAUDE.md는 클로드 코드가 세션을 시작할 때 가장 먼저 자동으로 읽어 들이는 파일이다. 여기에 기록된 규칙은 컨텍스트의 가장 앞부분에 상시 배치되므로, 대화 도중 소실되거나 'Lost in the Middle' 현상에 의해 망각될 우려가 없다.

• 판단 기준: 동일한 요구사항을 두 번 이상 말하고 있다면, 그것은 대화의 영역이 아니라 CLAUDE.md 파일로 승격시켜야 할 대상이다.

3. 결과물이 아닌 검증 프로세스를 통제하라

앤트로픽의 공식 가이드라인은 다음과 같은 핵심 권장 사항을 제시한다.

*"If you only adopt one practice, make it verification."*
(단 하나의 습관만 들여야 한다면, 그것은 반드시 검증이어야 한다.)

클로드 코드는 자율적으로 판단하고 실행하는 에이전트다. 그러나 명확한 채점 기준(검증 수단)이 주어지지 않으면, 코드가 실제로 동작하는지 확인하지 않은 채 외관상 그럴싸한 수준에서 작업을 종료하고 성공을 선언한다.

검증 수단을 제공하지 않으면 개발자 본인이 매번 테스트 환경을 구축하고 직접 구동하여 에러를 피드백해 주는 '인간 검증 루프'에 갇히게 된다.

"Pass / Fail" 피드백 루프 구축

가장 견고한 개발 워크플로우는 에이전트 스스로 코드를 작성하고, 테스트를 수행하며, 실패 시 코드를 자가 수정하는 닫힌 루프(Closed Loop)를 만들어 주는 것이다.

• 실패하는 테스트 코드를 선행 작성하라
  특정 버그를 수정하기 전, 해당 버그가 재현되어 반드시 실패하는 단위 테스트를 먼저 작성하도록 지시해야 한다. 이후 "이 테스트 케이스가 통과할 때까지 코드를 수정하라"고 명령하는 방식이 가장 확실하다.
• 정적 분석 및 빌드 명령어를 연계하라
  단순히 코드를 작성하는 것에 그치지 않고, npm run lint나 빌드 명령어를 에이전트가 직접 수행하여 에러가 없음을 최종 결과물로 증명하도록 요구해야 한다.

에이전트에게 일을 시킬 때는 "어떻게 구현할지"를 일일이 지시하는 것보다, "구현이 완료되었음을 어떻게 검증할지"를 먼저 설계하여 쥐여주는 것이 고성능 에이전트를 다루는 가장 성숙한 개발 방식이다.