클로드 코드 완전정복

에이전틱 AI 워크플로우의 설계, 구축, 수익화

1장 에이전틱 워크플로우가 바꾸는 산업 지형

■가 80억 달러에서 500억 달러로, 에이전틱 AI 시장의 폭발적 성장

2024년 가을, 실리콘밸리의 한 벤처캐피탈 파트너가 사내 회의에서 슬라이드 한 장을 띄웠습니다. 그래프 하나가 화면을 가득 채웠고, 선은 거의 수직에 가까운 각도로 올라가고 있었습니다. "이건 버블 아닌가요?"라는 질문이 나왔습니다. 파트너는 고개를 저었습니다. "버블은 기대만 있고 실체가 없을 때 쓰는 말입니다. 지금 기업들은 실제로 예산을 집행하고 있습니다."

그 그래프가 보여주는 시장이 에이전틱 AI(Agentic AI)입니다. 에이전틱 AI란 사람의 개입 없이 스스로 판단하고, 계획을 세우고, 도구를 사용해 작업을 실행하는 인공지능 시스템을 말합니다. 챗봇처럼 질문에 답변만 하는 수동적 AI와는 결이 다릅니다. 목표를 주면 거기에 도달하기 위한 경로를 스스로 설계하고, 중간에 문제가 생기면 우회로를 찾아냅니다.

이 시장의 규모는 2025년 기준 약 78억 달러(한화 약 10조 7,000억 원)로 추산됩니다. MarketsandMarkets의 2025년 보고서에 따르면, 이 수치는 2030년까지 약 526억 달러(한화 약 72조 원)에 이를 전망입니다. 연평균 성장률이 46%를 넘습니다. Statista가 인용한 캡제미니(Capgemini)의 분석도 비슷한 결론을 내놓았습니다. 2024년 51억 달러였던 시장이 2030년 470억 달러를 돌파할 것이라는 예측입니다. 조사 기관마다 시장을 정의하는 범위가 달라 수치에는 차이가 있으나, 2030년까지 최소 6배 이상 성장한다는 방향성은 모든 보고서에서 일치합니다.

수치의 크기보다 주목해야 할 것은 성장 곡선의 기울기입니다. 옴디아(Omdia)가 2025년 9월에 발표한 분석에 따르면, 에이전틱 AI의 초기 5년 연평균 성장률은 175%에 달합니다. 같은 시기 생성형 AI(Generative AI)의 초기 5년 성장률 90%와 비교하면 거의 두 배입니다. 생성형 AI가 깔아놓은 인프라 위에서 에이전틱 AI가 더 빠르게 달리고 있다는 뜻입니다.

■나 기업 25%가 이미 도입했고 2027년에는 절반이 운영한다

이 숫자들이 투자자의 기대치에 머물지 않는 이유가 있습니다. 기업들이 실제로 지갑을 열고 있기 때문입니다.

딜로이트(Deloitte)의 조사에 따르면, 생성형 AI를 사용하는 기업 중 25%가 2025년에 에이전틱 AI 파일럿 프로젝트를 시작했습니다. 이 비율은 2027년까지 50%로 두 배가 될 것으로 전망됩니다. 가트너(Gartner)는 한 발 더 나아갑니다. 2026년 말까지 기업용 애플리케이션의 40%가 작업별 AI 에이전트를 내장할 것이라고 예측했습니다. 2025년 초에 그 비율이 5% 미만이었다는 점을 감안하면, 불과 1~2년 사이에 여덟 배 이상의 확산이 일어나는 셈입니다.

PwC의 2025년 설문조사는 더 직접적인 숫자를 보여줍니다. 미국 기업 경영진의 79%가 자사에서 이미 AI 에이전트를 "어떤 형태로든" 사용하고 있다고 답했습니다. 88%는 에이전틱 AI 때문에 향후 12개월 내에 AI 관련 예산을 늘릴 계획이라고 밝혔습니다.

다만, 이 장밋빛 숫자 뒤에는 그림자도 있습니다. 가트너는 2027년 말까지 에이전틱 AI 프로젝트의 40% 이상이 취소될 수 있다고 경고했습니다. 비용 증가, 불명확한 사업 가치, 부족한 리스크 통제가 주된 원인입니다. 캡제미니의 조사에서도 에이전틱 AI를 완전히 확장 운영(Scaled Deployment) 단계까지 끌고 간 기업은 전체의 2%에 불과했습니다. 도입률 79%와 완전 운영률 2% 사이의 간극. 이 간극이 바로 기회입니다. 기업들은 에이전틱 AI를 원하지만, 제대로 구축하고 운영할 수 있는 사람이 부족합니다. 이 책이 그 역량을 길러드리려는 이유이기도 합니다.

■다 전통 자동화의 천장과 에이전틱 시스템의 돌파

(1) n8n, Zapier 같은 규칙 기반 자동화의 한계

왜 기업들이 이렇게 급하게 에이전틱 시스템으로 움직이는 걸까요. 기존 자동화 도구의 한계에 부딪혔기 때문입니다.

메이크(Make), n8n, 재피어(Zapier) 같은 도구를 써보신 분이라면 그 과정을 잘 아실 겁니다. 캔버스 위에 노드를 하나 올려놓습니다. 설정합니다. 다음 노드를 연결합니다. 변수가 제대로 전달되는지 확인합니다. 테스트합니다. 또 다른 노드를 추가합니다. 오류가 나면 메시지를 읽고, 원인을 찾고, 고칩니다. 다시 테스트합니다. 이 과정을 반복합니다.

이 방식은 예측 가능한 작업에서 빛을 발합니다. AI 자동화 분야에서 "결정론적(Deterministic)"이라고 부르는 성격의 작업, 다시 말해 같은 입력이 들어오면 항상 같은 출력이 나오는 작업입니다. 고객이 문의 양식을 제출하면 담당자에게 이메일이 가고, 스프레드시트에 행이 추가되고, 슬랙(Slack)에 알림이 뜹니다. 매번 같은 순서로, 같은 결과가 나옵니다. 지루하지만 아름다운 예측 가능성입니다.

문제는 예외 상황이 발생할 때입니다. 고객이 양식의 이메일 칸에 전화번호를 적어 넣었다면? 첨부 파일 형식이 예상과 다르다면? API가 갑자기 응답 형식을 바꿨다면? 규칙 기반 자동화는 이런 예외, 즉 엣지 케이스(Edge Case)를 만나면 멈춥니다. 그러면 누군가가 직접 들어가서 고쳐야 합니다. 그것이 유지보수이고, 시간이며, 결국 비용입니다.

(2) 에이전트가 빌드 과정에서 엣지 케이스를 스스로 처리하는 구조

에이전틱 워크플로우(Agentic Workflow)는 이 과정을 뒤집습니다. 시스템에게 "어떻게 하라"고 단계마다 지시하는 대신, "무엇을 원하는지"를 설명합니다. 에이전트가 나머지를 알아냅니다.

실력 있는 개발자를 고용한 상황을 떠올려 보십시오. 코드를 한 줄씩 설명해주지 않습니다. 문제를 설명하고, 원하는 결과를 이야기하고, "더 필요한 것이 있나요?"라고 묻습니다. 에이전틱 시스템이 작동하는 방식이 그렇습니다. 시스템이 추론합니다. 상황에 맞게 적응합니다. 필요하면 질문을 던집니다. 무언가 깨지면 스스로 진단하고 수리합니다.

미국의 한 AI 자동화 컨설턴트는 이 차이를 이렇게 표현했습니다. "전통 자동화는 종이 지도와 나침반을 들고 목적지를 찾아가는 것입니다. 거리 이름을 읽고, 경로를 직접 계획하고, 잘못된 길로 들어서면 스스로 알아채고 돌아와야 합니다. 에이전틱 워크플로우는 스마트폰을 꺼내서 목적지를 검색하는 것입니다. 파란 선이 나타나고, 따라가면 됩니다. 경로를 이탈하면 자동으로 재계산해서 다시 안내합니다."

두 방법 모두 목적지에 도착할 수 있습니다. 그러나 경험은 완전히 다릅니다.

여기서 한 가지 분명히 해야 할 것이 있습니다. 에이전틱 시스템이 전통 자동화를 대체하는 것은 아닙니다. 반복적이고 예측 가능한 작업에서는 여전히 규칙 기반 자동화가 적합합니다. 에이전틱 시스템의 진가는 판단이 필요한 영역, 변수가 많은 과정, 리서치처럼 입력과 출력의 형태가 매번 달라지는 작업에서 드러납니다. 고객 지원, 경쟁사 분석, 콘텐츠 파이프라인 같은 업무가 여기에 해당합니다. 움직이는 조각이 많고, 한 가지 정답이 없는 과정입니다.

(3) 열차 궤도 비유: 배포 전 다양한 시나리오로 배틀 테스트하기

에이전틱 시스템의 진짜 강점이 발휘되는 지점은 구축(Build) 단계에 있습니다.

전통 자동화를 구축하는 것은 열차 궤도를 손으로 까는 것과 같습니다. 레일 하나하나, 분기점 하나하나, 연결부 하나하나를 직접 설치합니다. 에이전틱 워크플로우는 건설 팀에게 "여기서 저기까지 열차 궤도를 놓아주세요"라고 지시하는 것과 같습니다. 건설 팀이 알아서 시공합니다. 시공 중에 지반이 약한 구간을 발견하면 보강 공사를 합니다. 커브가 너무 급하다 싶으면 각도를 조정합니다. 사람이 미처 생각하지 못한 엣지 케이스를 건설 과정에서 처리해버리는 것입니다.

그리고 배포(Deploy) 전에 배틀 테스트를 합니다. 열차 궤도 비유를 이어가면, 궤도가 완성되었다고 바로 운행에 들어가지 않습니다. 무게가 다른 열차 열 대를 굴려봅니다. 길이가 다른 열차, 바퀴 규격이 다른 열차, 화물차와 여객차를 번갈아 시험합니다. 모든 종류의 열차가 안전하게 달릴 수 있다는 확신이 생긴 뒤에야 실제 운행을 시작합니다.

에이전틱 워크플로우에서 이 배틀 테스트는 다양한 입력 시나리오를 던져보는 것입니다. 정상적인 데이터, 불완전한 데이터, 예상치 못한 형식의 데이터를 차례로 넣어봅니다. 에이전트가 각 상황을 어떻게 처리하는지 관찰하고, 문제가 발견되면 워크플로우와 도구를 수정합니다. 이 과정을 충분히 거치면, 배포된 워크플로우가 실전에서 깨질 확률이 크게 줄어듭니다.

■라 "에이전트를 배포하는 것"과 "코드를 배포하는 것"의 차이

(1) 에이전트는 로컬에 남고, 워크플로우와 도구만 클라우드로 올라간다

에이전틱 시스템을 둘러싼 오해 중 가장 흔한 것이 "에이전트가 24시간 돌아간다"는 생각입니다. 실제로는 그렇지 않습니다. 적어도 이 책에서 다루는 클로드 코드(Claude Code) 기반의 워크플로우에서는 그렇습니다.

이 책의 뒷부분에서 자세히 다루겠지만, 핵심 원리를 먼저 짚어두겠습니다. 이 책에서 사용하는 WAT 프레임워크는 세 개의 층으로 이루어져 있습니다. W는 워크플로우(Workflows), A는 에이전트(Agent), T는 도구(Tools)입니다. 워크플로우를 클라우드에 배포할 때 올라가는 것은 W와 T뿐입니다. A, 즉 에이전트 자체는 올라가지 않습니다.

클라우드에 배포된 워크플로우는 정해진 시간표(크론 스케줄)에 따라, 혹은 외부 신호(웹훅)에 반응해서 실행됩니다. 이때 실행되는 것은 에이전트의 판단력이 아니라, 에이전트가 미리 만들어 둔 코드와 프로세스입니다. 매주 월요일 아침 6시에 뉴스레터를 자동 발송하는 워크플로우를 예로 들면, 월요일 아침에 작동하는 것은 에이전트가 구축해 놓은 파이썬(Python) 스크립트와 마크다운(Markdown) 지침서이지, 에이전트 그 자체가 아닙니다.

(2) 자기치유(Self-healing)가 작동하는 범위와 작동하지 않는 범위

이 구분이 중요한 이유는 자기치유(Self-healing) 능력의 범위 때문입니다.

여러분이 클로드 코드 앞에 앉아서 워크플로우를 구축하고 있을 때, 에이전트는 여러분 바로 옆에서 함께 일하고 있습니다. 무언가 깨지면 에이전트가 즉시 감지합니다. 오류 메시지를 읽고, 원인을 분석하고, 코드를 수정하고, 다시 실행합니다. 이 자기치유 능력은 구축 단계에서 실제로 작동하며, 대단히 강력합니다.

그러나 워크플로우가 클라우드에 배포되어 자동으로 돌아가는 순간, 에이전트는 그 자리에 없습니다. 배포된 코드는 전통적인 자동화와 비슷하게 작동합니다. 예측 가능하고, 결정론적이며, 정해진 로직을 따릅니다. 예외 상황이 발생하면 에이전트가 아니라 사람이 개입해야 합니다.

그런데 이것은 약점이 아닙니다. 오히려 장점입니다. 배포된 자동화가 예측 가능하다는 것은 신뢰할 수 있다는 뜻이기 때문입니다. 비결정론적(Nondeterministic) 시스템, 즉 같은 입력에도 매번 다른 출력이 나올 수 있는 시스템을 고객의 핵심 업무 프로세스에 올려놓는 것은 위험합니다. AI가 판단력을 발휘하는 곳은 구축 단계이고, 배포 이후에는 그 판단의 결과물인 코드가 안정적으로 반복 실행되는 것. 이것이 에이전틱 워크플로우의 올바른 작동 방식입니다.

에이전틱 시스템을 도입하려는 분들이 이 구분을 명확히 이해해야 하는 이유는, 클라이언트에게 기대치를 정확히 전달하기 위해서입니다. "AI가 알아서 영원히 고쳐줍니다"라고 약속하면 안 됩니다. "AI가 구축 과정에서 사람보다 더 많은 예외 상황을 미리 처리합니다. 그래서 배포 후에 깨질 가능성이 훨씬 줄어듭니다"라고 설명하는 것이 정확합니다.

기업들이 기존 자동화의 천장에 부딪히고 에이전틱 시스템으로 시선을 돌리는 흐름, 그리고 그 시스템이 실제로 어떤 원리로 작동하는지까지 살펴보았습니다. 그렇다면 에이전틱 워크플로우를 설계하는 데 사용할 수 있는 구체적인 틀은 무엇일까요. 바로 다음 장에서 다룰 WAT 프레임워크가 그 답입니다. 워크플로우, 에이전트, 도구라는 세 개의 계층이 하나의 태스크를 어떻게 분담하고 협업하는지, 그 설계도를 펼쳐보겠습니다.

2장 WAT 프레임워크: 에이전틱 시스템의 설계도

■가 W(Workflows): 에이전트가 읽는 자연어 지침서

학교 사물함을 떠올려 보십시오. 매 과목의 숙제, 시험지, 필기 노트를 아무 생각 없이 던져 넣으면 어떻게 될까요. 국어 시험지 위에 수학 풀이가 깔리고, 그 밑에 지난달 체육 안내장이 눌려 있습니다. 성적이 나쁜 것은 실력 때문이 아니라 필요한 자료를 제때 찾지 못하기 때문입니다. 과목별 바인더를 넣고, 선반을 나누고, 노트북에 이름을 붙이면 같은 사물함이 전혀 다른 공간이 됩니다.

에이전틱 시스템에도 똑같은 원리가 적용됩니다. 클로드 코드 에이전트에게 "경쟁사를 분석해줘"라고 말하면, 에이전트는 웹을 검색하고, 데이터를 정리하고, PDF를 만들고, 이메일로 보내야 합니다. 이 과정을 매번 즉흥적으로 처리하게 두면, 결과물의 품질이 들쭉날쭉해집니다. 어떤 날은 경쟁사 세 곳을 빠뜨리고, 어떤 날은 차트 없이 텍스트만 보내옵니다. 구조가 없기 때문입니다.

WAT 프레임워크는 이 문제를 해결하기 위해 에이전틱 시스템을 세 개의 계층으로 나눕니다. W는 워크플로우(Workflows), A는 에이전트(Agent), T는 도구(Tools)입니다. 이 세 글자가 이 책 전체를 관통하는 뼈대입니다.

첫 번째 계층인 워크플로우는 마크다운(Markdown) 형식으로 작성된 지침서입니다. 마크다운이라는 이름이 낯설 수 있지만, 실체는 아주 평범합니다. 우리가 일상에서 쓰는 한국어 문장에 몇 가지 기호를 더한 것뿐입니다. 샵(#) 기호는 제목을 나타내고, 별표(*)는 강조를 표시하고, 대시(-)는 목록 항목을 구분합니다. 이 기호들 덕분에 에이전트는 어디가 큰 단계이고 어디가 세부 지침인지 한눈에 파악합니다.

워크플로우 하나는 하나의 업무 프로세스에 대응합니다. "경쟁사 분석 워크플로우"가 있다면, 그 안에는 목표(경쟁사 데이터를 수집하고 브랜디드 PDF 보고서를 생성한다), 필요한 입력(자사 정보, 분석 항목, 브랜드 에셋), 사용할 도구(웹 스크래핑 도구, 데이터 분석 도구, PDF 생성 도구), 기대 출력(브랜드 로고와 색상이 적용된 PDF 파일), 그리고 예외 처리 방법(경쟁사 웹사이트가 스크래핑을 차단할 경우 대체 데이터 소스를 사용)이 자연어로 기술되어 있습니다.

(1) 마크다운으로 작성하는 단계별 프로세스

워크플로우 파일을 열어보면 코드가 아니라 사람이 읽을 수 있는 문장이 적혀 있습니다. 예를 들어 뉴스레터 자동화 워크플로우에는 이런 내용이 담깁니다.

"1단계: 퍼플렉시티(Perplexity) API를 사용하여 주제에 관한 최신 리서치를 수행한다. 2단계: 리서치 결과를 바탕으로 뉴스레터 본문을 HTML 형식으로 작성한다. 3단계: 나노 바나나(Nano Banana) 이미지 생성 도구를 사용하여 인포그래픽 3건을 제작한다. 4단계: 인간 검토 단계. 제목 후보 3개를 제시하고 승인을 기다린다. 5단계: 승인된 제목으로 Gmail을 통해 수신자 목록에 발송한다."

이 지침서를 음식 조리법에 비유하면 이해가 쉽습니다. 워크플로우는 레시피입니다. 초콜릿 케이크를 만들려면 오븐을 예열하고, 달걀을 깨뜨리고, 밀가루를 계량하고, 반죽을 섞는 순서가 필요합니다. 레시피 없이 재료만 잔뜩 올려놓으면 케이크가 나오지 않습니다. 워크플로우 없이 도구만 잔뜩 갖춰놓아도 마찬가지입니다.

(2) 에이전트 피드백을 반영해 워크플로우 파일이 스스로 진화하는 구조

워크플로우의 진짜 힘은 고정되어 있지 않다는 점에 있습니다. 에이전트가 워크플로우를 실행하다가 문제를 만나면, 문제를 해결한 뒤 워크플로우 파일 자체를 수정합니다.

실제 사례를 들겠습니다. 뉴스레터 자동화를 처음 실행했을 때, 이미지 생성 도구의 API 엔드포인트가 변경되어 인포그래픽 제작이 실패했습니다. 에이전트는 오류를 감지하고, 웹 검색으로 새 엔드포인트를 찾아낸 뒤, 도구 코드를 수정했습니다. 여기서 끝이 아닙니다. 에이전트는 워크플로우 파일의 해당 단계에 "엔드포인트 변경 시 웹 검색으로 최신 문서를 확인한다"는 예외 처리 항목을 추가했습니다. 다음번 실행에서는 같은 문제가 발생하더라도 에이전트가 이미 대응 방법을 알고 있습니다.

이것이 자기개선 순환(Self-improvement Loop)입니다. 실행할수록 워크플로우는 더 정교해지고, 같은 실수를 반복할 확률은 줄어듭니다. 전통적인 자동화에서는 사람이 직접 오류를 발견하고, 직접 수정하고, 직접 문서를 업데이트해야 했습니다. 에이전틱 시스템에서는 이 세 단계가 에이전트 안에서 자동으로 일어납니다.

■나 A(Agent): 판단하고 위임하는 프로젝트 매니저

(1) 워크플로우를 읽고, 도구를 선택하고, 오류를 처리한다

두 번째 계층인 에이전트는 클로드 코드 그 자체입니다. VS Code(비주얼 스튜디오 코드) 오른쪽 채팅창에서 여러분과 대화하는 바로 그 존재입니다.

에이전트의 역할을 한마디로 정의하면 "프로젝트 매니저"입니다. 프로젝트 매니저는 직접 벽돌을 쌓지 않습니다. 설계도(워크플로우)를 읽고, 필요한 전문가(도구)를 부르고, 작업 순서를 결정하고, 문제가 생기면 대안을 찾습니다.

"경쟁사 분석을 해줘"라는 요청이 들어오면, 에이전트는 먼저 워크플로우 폴더를 뒤져서 "경쟁사 분석" 워크플로우가 있는지 확인합니다. 있으면 그 지침서를 읽습니다. 지침서에 "1단계: 웹 스크래핑 도구로 경쟁사 데이터를 수집한다"라고 적혀 있으면, 도구 폴더에서 웹 스크래핑 도구를 찾아 실행합니다. 실행 결과가 오류를 반환하면, 오류 메시지를 분석하고, 도구 코드를 수정하고, 다시 실행합니다.

이 과정에서 에이전트가 하는 일의 목록을 정리하면 이렇습니다. 워크플로우를 읽는다. 사용 가능한 도구를 파악한다. 도구를 올바른 순서로 호출한다. 오류가 발생하면 진단하고 수정한다. 필요할 때 사용자에게 질문한다. 작업이 끝나면 워크플로우와 도구를 업데이트한다.

(2) 사람이 아니라 도구에 작업을 위임하는 방식

에이전트가 사람에게 작업을 위임하는 것이 아니라 도구에 위임한다는 점이 중요합니다. 사람은 방향을 설정하고, 결과를 검토하고, 피드백을 줍니다. 실제 실행은 도구가 합니다.

이 구분이 왜 중요한지, 한 가지 비유를 더 들어보겠습니다. 배달 앱에서 음식을 주문하는 상황을 생각해 보십시오. 여러분은 앱에 "김치찌개 1인분"이라고 입력합니다. 앱은 주문을 식당에 전달하고, 식당은 조리하고, 배달 기사는 운반합니다. 여러분이 직접 냄비를 들고 가스레인지 앞에 선 것이 아닙니다. 여러분의 역할은 "무엇을 원하는지" 말하는 것이고, 나머지는 시스템이 처리합니다.

에이전틱 시스템에서 여러분은 주문자이고, 에이전트는 배달 앱이며, 도구는 식당과 배달 기사입니다. 주문자가 "김치찌개 말고 된장찌개로 바꿔줘"라고 하면 앱이 식당에 변경 사항을 전달하듯, 여러분이 "경쟁사 분석에 가격 비교 항목을 추가해줘"라고 하면 에이전트가 워크플로우를 수정하고 필요한 도구를 추가합니다.

■다 T(Tools): 하나의 작업만 수행하는 파이썬 스크립트

(1) 웹 스크래핑, PDF 생성, 데이터 분석 등 모듈형 도구

세 번째 계층인 도구는 실제로 행동하는 부분입니다. 워크플로우가 레시피라면, 도구는 재료입니다. 달걀, 밀가루, 설탕, 버터. 각 재료는 한 가지 역할만 합니다. 달걀은 반죽의 결합제이고, 설탕은 단맛을 내고, 버터는 풍미를 더합니다.

도구도 마찬가지입니다. 하나의 도구는 하나의 작업만 수행합니다. 웹사이트에서 데이터를 긁어오는 도구, 긁어온 데이터를 분석하는 도구, 분석 결과를 PDF로 변환하는 도구, PDF를 이메일로 발송하는 도구. 각각이 독립적인 파이썬(Python) 스크립트로 존재합니다.

파이썬이라는 단어를 보고 겁먹을 필요가 전혀 없습니다. 도구 파일의 내부에는 코드가 있지만, 그 코드를 여러분이 읽거나 수정할 일은 거의 없습니다. 에이전트가 도구를 만들고, 에이전트가 도구를 사용하고, 에이전트가 도구를 고칩니다. 여러분은 도구가 제대로 작동하는지 결과물을 확인하면 됩니다.

도구가 모듈형이라는 점은 실무에서 큰 장점을 줍니다. 한번 만든 웹 스크래핑 도구는 경쟁사 분석 워크플로우에서도, 채용 공고 수집 워크플로우에서도, 치과 영업 리드 수집 워크플로우에서도 재사용할 수 있습니다. 레고 블록처럼 필요한 곳에 끼워 넣으면 됩니다.

(2) 클로드 코드가 도구를 자동 생성하고 실패 시 자동 수정한다

도구의 생성과 수정이 자동으로 이루어진다는 점은 아무리 강조해도 지나치지 않습니다.

경쟁사 분석을 위해 "웹에서 데이터를 수집해야 한다"는 사실을 에이전트가 인지하면, 에이전트는 도구 폴더에 적합한 도구가 있는지 먼저 확인합니다. 없으면 직접 만듭니다. 파이썬 스크립트를 작성하고, 테스트하고, 실패하면 오류를 분석해서 코드를 수정합니다.

미국의 한 AI 자동화 컨설턴트가 경쟁사 분석 워크플로우를 구축할 때 실제로 관찰한 과정입니다. 에이전트는 파이어크롤(Firecrawl)이라는 웹 스크래핑 서비스를 사용해 경쟁사 웹사이트의 데이터를 수집하는 도구를 만들었습니다. 첫 실행에서 유니코드(Unicode) 인코딩 오류가 발생했습니다. 에이전트는 오류 로그를 읽고, 이모지 문자가 원인임을 파악했고, 스크립트에서 해당 문자를 처리하는 코드를 추가한 뒤, 도구 파일을 업데이트했습니다. 이 모든 과정에서 사용자가 한 일은 "고쳐줘"라고 말한 것뿐입니다.

■라 W-A-T 세 계층이 하나의 태스크에서 협업하는 흐름

세 계층이 하나의 작업에서 어떻게 맞물리는지, 처음부터 끝까지 따라가 보겠습니다.

여러분이 에이전트에게 "우리 회사의 경쟁사를 분석하고 PDF 보고서를 만들어줘"라고 요청합니다. 에이전트는 워크플로우 폴더를 탐색해서 "경쟁사 분석" 워크플로우를 찾아 읽습니다. 워크플로우에는 다섯 단계가 적혀 있습니다.

1단계에서 에이전트는 "비즈니스 정보 수집 도구"를 호출합니다. 이 도구는 여러분이 이전에 입력해 둔 자사 정보(업종, 타깃 고객, 가격대, 핵심 차별점)를 읽어옵니다. 2단계에서 에이전트는 "경쟁사 발굴 도구"를 호출합니다. 이 도구는 자사 정보를 바탕으로 웹을 검색해서 경쟁사 목록을 만듭니다. 3단계에서 "경쟁사 리서치 도구"가 각 경쟁사의 제품, 가격, 마케팅 메시지를 수집합니다. 4단계에서 "경쟁사 분석 도구"가 수집된 데이터를 종합하여 SWOT 분석과 기회 영역을 도출합니다. 5단계에서 "PDF 생성 도구"가 분석 결과를 여러분의 브랜드 로고, 색상, 서체가 적용된 보고서로 변환합니다.

이 전체 과정에서 에이전트는 워크플로우라는 지도를 따라 이동하면서, 각 지점에서 적절한 도구를 호출합니다. 도구가 결과를 반환하면 에이전트는 다음 단계로 넘어갑니다. 어떤 도구가 실패하면 에이전트는 오류를 진단하고, 도구를 수정하고, 다시 시도합니다. 그리고 이 경험을 워크플로우와 도구 파일에 기록해서, 다음번에는 더 매끄럽게 작동하도록 합니다.

WAT 프레임워크를 사용하는 이유를 수치로 설명할 수도 있습니다. AI가 모든 단계를 한꺼번에 처리하려고 하면, 각 단계의 정확도가 90%라고 가정해도 5단계를 거치면 전체 성공률은 59%로 떨어집니다(0.9의 5승). 그러나 각 단계를 독립적인 도구로 분리하고, 워크플로우가 순서를 통제하고, 에이전트가 각 단계의 결과를 검증하면, 실패한 단계만 다시 실행할 수 있습니다. 전체를 처음부터 반복할 필요가 없습니다.

이것이 WAT 프레임워크의 핵심입니다. 확률적(Probabilistic) AI가 추론과 판단을 맡고, 결정론적(Deterministic) 코드가 실행을 맡는 분업 구조. 이 분업이 에이전틱 시스템의 신뢰성을 만들어냅니다.

워크플로우는 "무엇을 어떤 순서로 할 것인가"를 정의하고, 에이전트는 "지금 상황에서 어떤 판단을 내릴 것인가"를 결정하며, 도구는 "그 판단을 실제로 실행"합니다. 세 계층 중 어느 하나라도 빠지면 시스템이 제대로 작동하지 않습니다. 워크플로우 없는 에이전트는 방향을 잃고, 에이전트 없는 워크플로우는 종이 위의 계획에 머물며, 도구 없는 시스템은 아무것도 실행하지 못합니다.

이 설계도를 손에 쥔 채로, 이제 실제로 작동하는 첫 번째 에이전틱 워크플로우를 구축해 보겠습니다. 빈 폴더 하나, 브랜드 로고 하나, 그리고 "에이전틱 AI에 관한 뉴스레터를 써줘"라는 한 줄의 프롬프트. 이것만으로 어디까지 갈 수 있는지, 다음 장에서 처음부터 끝까지 보여드리겠습니다.

3장 뉴스레터 자동화: 첫 번째 라이브 데모

■가 빈 폴더에서 시작하는 프로젝트 셋업

화면 앞에 앉아 있다고 상상해 보십시오. VS Code가 열려 있고, 왼쪽 파일 탐색기에는 아무것도 없습니다. "newsletters-demo"라는 이름의 폴더 하나가 덩그러니 비어 있습니다. 오른쪽에는 클로드 코드 채팅창이 커서를 깜빡이며 기다리고 있습니다. 이 빈 공간에서 한 시간 뒤, 브랜드 로고와 색상이 입혀진 뉴스레터가 수신함에 도착하게 됩니다. 그 과정을 처음부터 끝까지 따라가 보겠습니다.

모든 프로젝트의 시작은 같습니다. 빈 폴더를 열고, 클로드 코드에게 집을 마련해 주는 것입니다. 집이란 claude.md 파일을 말합니다. 이 파일에 대해서는 5장에서 깊이 다루겠지만, 지금은 한 가지만 기억하면 됩니다. claude.md는 에이전트가 매번 대화를 시작하기 전에 반드시 읽는 지침서입니다. 시스템 프롬프트(System Prompt)라고도 부릅니다.

2장에서 살펴본 WAT 프레임워크를 이 파일 안에 담습니다. 워크플로우는 이런 식으로 만들어라, 도구는 이 폴더에 저장해라, 오류가 나면 이렇게 대처해라. 이 지침서를 파일 탐색기의 왼쪽 패널로 드래그해서 놓으면, 폴더에 첫 번째 파일이 생깁니다.

그 다음, 클로드 코드에게 말합니다. "방금 claude.md 파일을 넣었어. 읽고 프로젝트를 초기화해줘. 궁금한 것이 있으면 물어봐." 에이전트는 파일을 읽고, WAT 프레임워크를 이해했다는 확인 메시지를 보내온 뒤, 왼쪽 패널에 폴더를 만들기 시작합니다. workflows, tools, temp 세 개의 폴더가 나란히 나타납니다. 워크플로우 파일이 들어갈 곳, 도구 스크립트가 들어갈 곳, 임시 파일이 잠깐 머물 곳. 프로젝트의 뼈대가 잡혔습니다.

■나 브랜드 가이드라인과 로고를 먹이는 법

뉴스레터가 아무리 잘 쓰여 있어도, 브랜드의 얼굴이 없으면 수신자에게 "이건 우리 회사 것"이라는 인식을 심어줄 수 없습니다. 로고, 색상 팔레트, 서체. 이 세 가지가 뉴스레터의 정체성을 만듭니다.

왼쪽 탐색기에 brand_assets라는 폴더를 하나 더 만듭니다. 여기에 두 개의 파일을 끌어다 놓습니다. 하나는 회사 로고 이미지 파일(PNG 형식)이고, 다른 하나는 브랜드 가이드라인 문서입니다. 브랜드 가이드라인에는 주요 색상 코드, 보조 색상, 사용 서체, 여백 규칙 같은 정보가 담겨 있습니다.

에이전트에게 이 파일들의 존재를 알려주는 방법은 자연어 한 문장이면 됩니다. "뉴스레터 전체를 내 브랜드에 맞춰서 만들어줘. 로고는 @AIS.png이고, 브랜드 가이드라인은 @AIS-brand-guidelines.png야." 클로드 코드에서 골뱅이(@) 기호를 입력하면 프로젝트 안의 파일을 직접 태그할 수 있습니다. 에이전트는 태그된 파일을 열어보고, 로고의 형태를 파악하고, 가이드라인에서 색상 코드와 서체 정보를 추출합니다.

이 과정이 중요한 이유는 반복성 때문입니다. 한번 브랜드 에셋을 프로젝트에 넣어두면, 이후 뉴스레터를 몇 번을 만들든 에이전트가 매번 같은 로고와 색상을 적용합니다. 사람이 매번 "로고 넣어야지, 색상 코드가 뭐였지" 하고 기억을 더듬을 필요가 없습니다.

■다 한 줄 프롬프트("에이전틱 AI에 관한 뉴스레터를 써줘")에서 완성까지

프로젝트 구조가 잡히고, 브랜드 에셋이 준비되었습니다. 이제 실제로 뉴스레터를 만들어 볼 차례입니다.

그 전에 한 가지 설정을 확인합니다. 클로드 코드 채팅창 하단에는 모드를 전환하는 토글이 있습니다. "플랜 모드(Plan Mode)"로 시작합니다. 이 모드에서는 에이전트가 생각하고, 조사하고, 계획을 세우되, 실제로 파일을 만들거나 코드를 실행하지는 않습니다. 건축가가 삽을 들기 전에 도면을 그리는 단계입니다.

채팅창에 입력합니다.

"에이전틱 AI에 관한 뉴스레터를 만들고 싶어. 주제에 대한 리서치를 하고, HTML로 예쁘게 구성하고, 인포그래픽도 몇 장 넣어줘. 어떤 기술 스택을 쓸지, 내가 빠뜨린 것은 없는지 알려줘."

이 정도면 충분합니다. 완벽한 프롬프트가 아닙니다. 하지만 플랜 모드의 힘이 여기서 드러납니다. 에이전트는 이 모호한 요청을 받아들인 뒤, 스스로 채워야 할 빈칸을 찾아냅니다.

에이전트가 돌아옵니다. 질문 세 개를 던집니다.

"리서치를 위해 외부 검색 API를 연결할까요? 퍼플렉시티(Perplexity) 같은 것을 추천합니다."

"뉴스레터를 비하이브(Beehive) 같은 플랫폼으로 보낼까요, 아니면 Gmail로 직접 발송할까요?"

"브랜드 에셋이 있으면 공유해 주세요. 뉴스레터에 일관된 스타일을 적용할 수 있습니다."

에이전트가 프로젝트 매니저답게 행동하고 있습니다. 클라이언트의 모호한 요청을 받아서, 실행 가능한 사양서로 변환하기 위해 필요한 정보를 역으로 질문하는 것입니다. 사람이었다면 경험 많은 기획자만 할 수 있는 일입니다.

답변합니다. "리서치는 퍼플렉시티로 해줘. 발송은 Gmail로. 브랜드 에셋은 이미 폴더에 넣어뒀어."

(1) 리서치, 콘텐츠 작성, 인간 검토, 발송의 단계

에이전트가 최종 계획을 제시합니다. 뉴스레터 자동화 워크플로우는 다섯 단계로 구성됩니다.

리서치 단계에서 퍼플렉시티 API를 사용해 에이전틱 AI 관련 최신 동향을 수집합니다. 콘텐츠 작성 단계에서 클로드가 수집된 자료를 바탕으로 뉴스레터 본문을 HTML로 작성합니다. 인포그래픽 생성 단계에서 이미지 생성 도구를 사용해 데이터 시각화 이미지를 제작합니다. 인간 검토 단계에서 제목 후보를 제시하고 사용자의 승인을 기다립니다. 발송 단계에서 승인된 제목으로 Gmail을 통해 수신자 목록에 이메일을 보냅니다.

계획의 마지막 부분이 흥미롭습니다. "사용자가 아직 생각하지 못했을 수 있는 항목"이라는 섹션을 에이전트가 스스로 추가했습니다. 인간 검토 단계의 필요성, 이메일 제목줄과 메타데이터 최적화, 브랜드 일관성 점검. 에이전트가 단순 실행자가 아니라 기획 파트너로 기능하는 순간입니다.

계획이 마음에 들면, 모드를 "바이패스 퍼미션(Bypass Permissions)"으로 전환합니다. 이 모드에서는 에이전트가 파일을 만들고, 코드를 실행하고, 외부 API를 호출하는 모든 과정을 자율적으로 수행합니다. 에이전트는 투두 리스트(To-do List)를 만들고, 항목을 하나씩 처리하며, 완료된 항목에 줄을 긋습니다.

왼쪽 탐색기에 파일들이 하나둘 나타나기 시작합니다. 설정 파일 두 개(뉴스레터 스타일 설정, 수신자 목록), 도구 다섯 개(리서치, 인포그래픽 생성, HTML 조립, Gmail 발송, 구글 시트 아카이브), 그리고 워크플로우 하나. 이 모든 파일이 사람의 개입 없이 생성되었습니다.

(2) 브랜드 폰트와 색상이 자동 적용되는 원리

에이전트가 뉴스레터를 조립할 때, 앞서 넣어둔 브랜드 가이드라인이 작동합니다. HTML 코드 안에 가이드라인에서 추출한 색상 코드가 삽입됩니다. 헤더 배경에 브랜드 주색상이 깔리고, 본문 텍스트에 지정된 서체가 적용되고, 섹션 구분선에 보조 색상이 사용됩니다. 인포그래픽에도 같은 색상 체계가 반영되어, 뉴스레터 전체가 하나의 브랜드 아이덴티티를 유지합니다.

이것이 가능한 이유는 에이전트가 브랜드 가이드라인 파일을 "읽었기" 때문입니다. 사람이 디자이너에게 "우리 브랜드 색상은 이거야"라고 전달하는 것과 같은 과정이, 파일 태그 한 번으로 이루어진 것입니다.

■라 실패와 수정, 그리고 최종 이메일 확인

이제 에이전트에게 한 마디를 던집니다. "에이전틱 AI에 관한 뉴스레터를 써줘." 에이전트는 워크플로우를 찾아 읽고, 리서치를 시작하고, 인포그래픽을 생성하고, HTML을 조립합니다. 중간에 인간 검토 단계에서 제목 후보 다섯 개를 제시하고 어떤 것을 사용할지 물어봅니다. 하나를 선택하면 이메일이 발송됩니다.

그런데 이메일을 열어보니 문제가 있습니다. HTML이 깨져서 배경색만 보이고 본문 텍스트가 읽히지 않습니다. 레이아웃이 엉망입니다.

이 순간이 에이전틱 시스템의 진가가 드러나는 지점입니다. 전통적인 자동화였다면, 사람이 HTML 코드를 열어서 어디가 잘못되었는지 직접 찾아야 합니다. 클로드 코드에서는 자연어 한 문장이면 됩니다.

"이메일을 받았는데 HTML이 완전히 깨졌어. 텍스트가 하나도 안 읽혀. 원인을 찾아서 고치고 다시 보내줘."

에이전트는 HTML 코드를 검사합니다. 인라인 스타일과 이메일 클라이언트 호환성 문제를 발견합니다. Gmail이 특정 CSS(Cascading Style Sheets, 웹 페이지의 디자인을 제어하는 언어) 속성을 지원하지 않아서 레이아웃이 무너진 것입니다. 에이전트는 문제를 수정하고, 워크플로우와 도구 파일 모두를 업데이트해서 같은 문제가 재발하지 않도록 합니다. 그리고 뉴스레터를 다시 발송합니다.

두 번째 이메일을 엽니다. 상단에 로고가 선명하게 자리잡고 있습니다. 브랜드 색상이 헤더와 섹션 구분선에 일관되게 적용되어 있습니다. 본문에는 에이전틱 AI 시장 동향, 아키텍처 해설, 실무 적용 사례가 섹션별로 정리되어 있습니다. 중간중간에 인포그래픽이 삽입되어 있고, 이 인포그래픽도 브랜드 색상 체계를 따릅니다. 하단에는 핵심 요약과 행동 촉구(Call to Action) 문구가 있고, 그 아래에 리서치 출처 링크가 나열되어 있습니다.

이 결과물이 완벽하지는 않습니다. 날짜가 잘못 표기되어 있을 수 있고, 인포그래픽의 로고 위치가 미세하게 어긋나 있을 수 있습니다. 하지만 이것은 첫 번째 반복(Iteration)입니다. "인포그래픽 왼쪽 상단에 로고를 고정해줘", "날짜를 오늘 날짜로 수정해줘"라고 말하면 에이전트가 바로 반영합니다. 반복할수록 결과물은 정교해지고, 워크플로우와 도구는 더 단단해집니다.

여기서 한 발 뒤로 물러서서 전체 과정을 조감해 보겠습니다. 빈 폴더에서 시작해서, claude.md를 넣고, 브랜드 에셋을 추가하고, 자연어로 계획을 세우고, 에이전트가 워크플로우와 도구를 자동 생성하고, 실행하고, 실패하고, 수정하고, 최종 이메일을 수신하기까지. 이 전체 과정에서 여러분이 직접 작성한 코드는 한 줄도 없습니다. API 문서를 읽지도, JSON 구조를 설계하지도, HTML 태그를 손으로 치지도 않았습니다.

이 경험을 한번 겪고 나면, 자연스럽게 다음 질문이 떠오릅니다. 이 워크플로우를 매주 월요일 아침 6시에 자동으로 실행되게 할 수 있을까? 리서치 범위를 넓히거나 수신자 목록을 세분화할 수 있을까? 뉴스레터 말고 경쟁사 분석 보고서도 같은 방식으로 만들 수 있을까?

답은 모두 "그렇다"입니다. 그리고 이 모든 가능성을 열기 위해 먼저 필요한 것이 있습니다. 클로드 코드가 살아가는 환경, 즉 VS Code의 설치와 설정, 그리고 에이전트와 처음으로 악수하는 과정입니다.

4장 VS Code와 클로드 코드 확장 설치

■가 VS Code 다운로드와 기본 인터페이스 이해

사무실에서 새 컴퓨터를 받으면 가장 먼저 하는 일이 있습니다. 책상 위치를 정하고, 모니터 높이를 맞추고, 자주 쓰는 프로그램을 설치합니다. 클로드 코드를 시작하기 전에 해야 할 일도 같습니다. 에이전트가 일할 수 있는 작업 공간을 마련하는 것입니다.

그 작업 공간이 VS Code(Visual Studio Code, 비주얼 스튜디오 코드)입니다. VS Code는 마이크로소프트가 만든 무료 코드 편집기인데, "코드 편집기"라는 이름에 겁먹을 필요가 없습니다. 이 책에서 VS Code는 코드를 직접 작성하는 도구가 아니라, 클로드 코드 에이전트가 거주하는 집입니다. 파일을 보고, 폴더를 정리하고, 에이전트와 대화하는 창구입니다.

설치는 간단합니다. 웹 브라우저에서 "VS Code"를 검색하면 공식 다운로드 페이지가 나옵니다. 윈도우, 맥, 리눅스 중 여러분의 운영체제에 맞는 버전을 내려받아 설치합니다. 설치가 끝나면 프로그램을 열어봅니다.

처음 열면 환영 화면이 뜹니다. 이 화면에서 눈여겨볼 것은 많지 않습니다. 왼쪽에 세로로 아이콘이 줄지어 있는 메뉴바가 보입니다. 가장 위의 아이콘이 탐색기(Explorer)입니다. 서류 두 장이 겹쳐진 모양입니다. 이곳이 프로젝트의 파일과 폴더를 보여주는 패널입니다. 그 아래에 돋보기 모양의 검색, 가지가 갈라지는 형태의 소스 제어(Git 연동), 그리고 네모 블록 모양의 확장(Extensions) 아이콘이 있습니다.

지금 당장 외워야 할 것은 두 가지뿐입니다. 탐색기 아이콘과 확장 아이콘. 나머지는 필요할 때 하나씩 알아가면 됩니다.

■나 클로드 코드 확장(Extension) 설치와 구독 플랜 선택

VS Code 자체만으로는 클로드 코드를 사용할 수 없습니다. 확장(Extension)을 설치해야 합니다. 확장이란 VS Code에 새로운 기능을 추가하는 플러그인(Plug-in)입니다. 스마트폰에 앱을 설치하는 것과 같습니다.

왼쪽 세로 메뉴바에서 네모 블록 모양의 확장 아이콘을 클릭합니다. 상단에 검색창이 나타납니다. "Claude Code"를 입력하면 앤트로픽(Anthropic)이 배포한 공식 확장이 상단에 표시됩니다. 이 확장이 VS Code 안에서 클로드 코드 에이전트와 대화할 수 있는 창구를 열어줍니다. "Install" 버튼을 누릅니다.

설치가 완료되면 VS Code 상단 오른쪽 구석에 앤트로픽 로고 모양의 작은 버튼이 생깁니다. 이 버튼이 클로드 코드를 여는 열쇠입니다.

(1) Pro, Max 플랜의 차이

버튼을 클릭하면 로그인을 요구합니다. 클로드 코드를 사용하려면 앤트로픽의 유료 구독이 필요합니다. 무료 플랜에서는 클로드 코드에 접근할 수 없습니다.

구독 플랜은 크게 두 가지입니다. 프로(Pro) 플랜은 월 17달러(한화 약 23,000원)이고, 맥스(Max) 플랜은 월 100달러(한화 약 137,000원)부터 시작합니다. 프로 플랜으로 시작해도 클로드 코드의 모든 기능을 사용할 수 있습니다. 다만 사용량 한도에 빨리 도달합니다. 워크플로우를 구축하고, 테스트하고, 수정하는 반복 과정에서 토큰(6장에서 자세히 설명)이 빠르게 소모되기 때문입니다. 한도에 도달하면 일정 시간 대기해야 합니다.

맥스 플랜은 이 한도가 훨씬 넉넉합니다. 에이전트와 긴 세션을 유지하며 복잡한 프로젝트를 진행할 때, 중간에 끊기지 않고 작업할 수 있습니다. 비용이 부담될 수 있지만, 관점을 바꿔보면 이렇습니다. 소프트웨어 개발자 한 명의 월급이 수백만 원에서 수천만 원입니다. 클로드 코드는 그 개발자가 하는 일의 상당 부분을 월 10만 원대에 대신합니다. 구독료가 아니라 초고속 주니어 개발자의 인건비로 생각하면, 투자 대비 회수율이 완전히 달라집니다.

처음에는 프로 플랜으로 시작해서 한도에 얼마나 자주 부딪히는지 경험해 보고, 필요하면 맥스로 올리는 것이 합리적입니다.

(2) 인증 과정과 첫 화면 구성

플랜에 가입한 뒤 VS Code로 돌아옵니다. 클로드 코드 버튼을 클릭하면 브라우저 창이 열리며 앤트로픽 계정 로그인을 요청합니다. 이메일과 비밀번호를 입력하고 인증을 완료하면, 브라우저가 자동으로 VS Code로 돌아옵니다. 인증이 성공했다는 메시지와 함께 채팅 인터페이스가 오른쪽에 나타납니다.

이 채팅창은 카카오톡이나 클로드(claude.ai) 웹 인터페이스와 비슷한 형태입니다. 아래쪽에 입력란이 있고, 메시지를 보내면 에이전트의 응답이 위에 쌓입니다. 차이가 있다면, 이 채팅창의 에이전트는 여러분의 컴퓨터에 있는 파일을 읽고, 수정하고, 새로 만들 수 있다는 점입니다. 단순한 대화 상대가 아니라, 여러분의 작업 환경 안에서 실제로 행동하는 존재입니다.

■다 왼쪽 파일 탐색기와 오른쪽 에이전트 채팅창의 역할

인증이 끝나면, 화면 구성을 정리합니다. 환영 탭, 릴리스 노트 탭 등 불필요한 탭을 모두 닫습니다. 깨끗한 화면에 두 개의 영역만 남깁니다.

왼쪽은 파일 탐색기입니다. 프로젝트의 모든 폴더와 파일이 트리 구조로 표시됩니다. 에이전트가 워크플로우 파일을 만들면 여기에 나타나고, 도구 스크립트를 생성하면 여기서 확인합니다. 파일을 클릭하면 중앙 편집 영역에서 내용을 볼 수 있습니다.

오른쪽은 에이전트 채팅창입니다. 여러분이 에이전트에게 지시를 내리고, 에이전트가 진행 상황을 보고하고, 질문을 던지고, 결과를 알려주는 곳입니다.

이 두 영역의 관계를 이해하는 것이 VS Code 사용의 전부라고 해도 과언이 아닙니다. 왼쪽에서 파일을 확인하고, 오른쪽에서 에이전트와 소통합니다. 에이전트가 왼쪽의 파일을 만들고 수정하면, 그 변화가 실시간으로 탐색기에 반영됩니다.

이제 프로젝트를 열어봅니다. 탐색기 상단에 "폴더 열기(Open Folder)" 버튼이 있습니다. 클릭해서 작업할 폴더를 선택합니다. 새 프로젝트라면 빈 폴더를 하나 만들어서 선택하면 됩니다. 이전 장에서 뉴스레터 데모를 위해 만든 폴더든, 완전히 새로운 폴더든 상관없습니다.

폴더를 선택하면 탐색기에 해당 폴더의 이름이 표시되고, 그 안의 파일이 나열됩니다. 빈 폴더라면 아무것도 나타나지 않습니다. 여기에 claude.md를 넣고, 에이전트에게 초기화를 요청하면, 3장에서 보았던 프로젝트 셋업 과정이 시작됩니다.

자주 발생하는 문제 하나를 미리 짚어두겠습니다. VS Code를 처음 설치한 분들 중 상당수가 "폴더를 열지 않은 채로" 클로드 코드를 사용하려고 합니다. 탐색기에 "폴더를 열지 않았습니다"라는 메시지가 표시된 상태에서 채팅을 시작하면, 에이전트가 파일을 만들 위치를 알 수 없어서 제대로 작동하지 않습니다. 클로드 코드를 사용하기 전에 반드시 작업 폴더를 먼저 여십시오. 이것은 집 주소를 알려주지 않고 택배를 보내달라고 하는 것과 같습니다.

VS Code가 설치되고, 클로드 코드 확장이 켜지고, 유료 구독이 인증되고, 작업 폴더가 열렸습니다. 에이전트가 살 집이 준비되었습니다. 그런데 집에 입주한 에이전트에게 가장 먼저 건네야 할 문서가 있습니다. 이 집에서 어떻게 일해야 하는지를 알려주는, 단 하나의 파일. claude.md입니다.

5장 claude.md: 에이전트에게 집을 주는 파일

■가 claude.md의 정체와 시스템 프롬프트로서의 기능

채용 면접을 통과한 신입 사원이 첫 출근을 합니다. 책상에 앉았는데 아무런 안내 문서가 없습니다. 업무 매뉴얼도, 조직도도, 프로젝트 현황판도 없습니다. 옆 동료에게 "저 뭘 하면 되나요?"라고 물어볼 수는 있지만, 매번 물어봐야 하고, 답변의 품질은 동료의 기분과 기억력에 달려 있습니다.

반대의 상황을 떠올려 보십시오. 첫 출근일에 책상 위에 깔끔한 온보딩 문서가 놓여 있습니다. "당신은 마케팅팀 콘텐츠 담당입니다. 주간 뉴스레터 발행이 핵심 업무입니다. 브랜드 가이드라인은 이 폴더에, 이전 뉴스레터 아카이브는 저 폴더에 있습니다. 문체는 격식보다는 친근하게, 인포그래픽은 반드시 브랜드 색상을 사용하세요." 이 문서를 읽은 신입 사원은 첫날부터 방향을 잡고 움직일 수 있습니다.

claude.md가 바로 그 온보딩 문서입니다.

클로드 코드 에이전트는 여러분이 메시지를 보낼 때마다, 여러분의 메시지를 읽기 전에 claude.md를 먼저 읽습니다. 매번입니다. 예외 없이. 이것이 claude.md가 단순한 메모가 아니라 시스템 프롬프트(System Prompt)인 이유입니다. 에이전트의 행동 방식을 근본적으로 규정하는 문서입니다.

claude.md가 없는 에이전트는 아무런 맥락 없이 여러분의 질문에만 반응합니다. 결과물이 들쭉날쭉하고, 파일을 어디에 저장할지 매번 다르게 판단하고, 이전에 합의한 규칙을 잊어버립니다. claude.md가 있는 에이전트는 프로젝트의 목적, 기술 스택, 폴더 구조, 작업 방식을 일관되게 유지합니다.

■나 WAT 프레임워크를 claude.md에 담는 법

2장에서 배운 WAT 프레임워크를 claude.md에 어떻게 담는지 살펴보겠습니다. claude.md 파일을 열면 마크다운 형식의 텍스트가 나타납니다. 내용은 크게 세 부분으로 나뉩니다.

첫 번째 부분은 "무엇(What)"입니다. 이 프로젝트가 무엇인지, 기술 스택은 무엇인지, 핵심 구성요소는 무엇인지 서술합니다. "이 프로젝트는 WAT 프레임워크 안에서 작동합니다. 세 개의 계층이 있습니다. 워크플로우는 마크다운 지침서이고, 에이전트는 당신이며, 도구는 파이썬 스크립트입니다."

두 번째 부분은 "왜(Why)"입니다. 각 구성요소가 왜 존재하는지 설명합니다. "AI가 모든 단계를 한꺼번에 처리하면 정확도가 급격히 떨어집니다. 각 단계를 모듈형 도구로 분리하면, 실패한 단계만 재실행할 수 있어서 전체 신뢰성이 높아집니다."

세 번째 부분은 "어떻게(How)"입니다. 에이전트가 일상적으로 따라야 할 행동 규칙입니다. "새 도구를 만들기 전에 기존 도구 폴더를 먼저 확인하라. 오류가 발생하면 로그를 읽고, 원인을 파악하고, 스크립트를 수정하고, 워크플로우를 업데이트하라. API 키는 절대 코드 안에 직접 적지 말고 .env 파일에 저장하라."

이 세 부분 외에 중요한 항목이 하나 더 있습니다. 파일 구조(File Structure) 안내입니다. 에이전트가 파일을 만들 때 어디에 저장해야 하는지 명시합니다. "워크플로우 파일은 /workflows 폴더에, 도구 스크립트는 /tools 폴더에, 임시 파일은 /temp 폴더에 저장하라. API 키와 비밀번호는 .env 파일에 보관하라." 이 안내가 없으면 에이전트가 파일을 프로젝트 루트에 무질서하게 쌓아놓아서, 나중에 무엇이 어디 있는지 찾기 어려워집니다.

■다 slash init 명령어로 프로젝트 초기화하기

claude.md를 직접 작성하는 것이 부담스러울 수 있습니다. 그런 경우 클로드 코드에 내장된 슬래시 명령어(Slash Command)를 사용할 수 있습니다. 채팅창에 /init이라고 입력하면, 에이전트가 현재 프로젝트의 폴더 구조와 파일을 스캔한 뒤, 적절한 claude.md 초안을 자동으로 생성합니다.

물론 자동 생성된 초안은 출발점일 뿐입니다. WAT 프레임워크의 세부 규칙이나 여러분만의 브랜드 정보, 특정 API 서비스 선호도 같은 항목은 직접 추가해야 합니다. 그래도 백지에서 시작하는 것보다는 훨씬 수월합니다.

또 다른 방법은 이미 잘 만들어진 claude.md 템플릿을 가져오는 것입니다. WAT 프레임워크용 claude.md 템플릿은 커뮤니티에서 공유되고 있으며, 이를 프로젝트에 드래그해서 넣은 뒤 자신의 프로젝트에 맞게 수정하면 됩니다.

어떤 방법을 사용하든, 중요한 것은 claude.md가 살아 있는 문서라는 점입니다. 처음에 만들어 놓고 다시 보지 않는 문서가 아닙니다. 프로젝트가 진행되면서 새로운 규칙이 필요해지거나, 에이전트가 반복적으로 같은 실수를 저지르면, claude.md에 해당 내용을 추가합니다. 에이전트에게 "이 규칙을 claude.md에 넣어줘"라고 말하면 에이전트가 직접 파일을 업데이트하기도 합니다.

■라 claude.md가 길어질 때 다른 파일로 라우팅하는 전략

claude.md의 효용에는 역설이 숨어 있습니다. 유용한 정보를 많이 담을수록 파일이 길어지고, 파일이 길어질수록 에이전트가 매 대화마다 소비하는 토큰이 늘어납니다. 토큰에 대해서는 다음 장에서 자세히 다루겠지만, 지금은 "길수록 비용이 오르고 성능이 떨어질 수 있다"는 점만 기억해 주십시오.

실무에서는 claude.md를 200줄 이내로 유지하는 것이 권장됩니다. 그렇다면 200줄 안에 프로젝트의 모든 맥락을 담을 수 있을까요? 대부분의 경우 그럴 수 없습니다. 이그제큐티브 어시스턴트 프로젝트(6부에서 다룹니다)를 예로 들면, 팀 정보, 우선순위, OKR(Objectives and Key Results, 목표 및 핵심 결과), 프로젝트 현황까지 모두 넣으면 수백 줄이 됩니다.

해결책은 라우팅(Routing)입니다. claude.md에는 "어디서 찾을 수 있는지"만 적고, 실제 내용은 별도 파일에 둡니다. 도서관의 색인 카드와 같은 원리입니다. 색인 카드에 책의 전체 내용을 적지 않습니다. 책 제목과 서가 번호만 적습니다. 필요할 때 그 서가로 가서 책을 꺼내 읽습니다.

claude.md에서 라우팅은 이런 식으로 작동합니다. "팀 정보가 필요하면 /context/team.md를 참조하라. 브랜드 가이드라인은 /brand-assets/guidelines.md에 있다. 이메일 작성 규칙은 /rules/email-style.md를 읽어라." 에이전트는 평소에는 이 파일들을 읽지 않습니다. 관련된 요청이 들어왔을 때만 해당 파일을 열어봅니다. 이렇게 하면 claude.md는 짧게 유지되고, 매 대화의 토큰 소비도 줄어들며, 필요한 정보는 여전히 접근 가능합니다.

라우팅이 필요하다는 신호를 알아차리는 방법이 있습니다. claude.md에 같은 유형의 정보를 반복해서 추가하고 있다면, 그것은 별도 파일로 분리하라는 신호입니다. "이메일은 이런 어조로 써라", "슬랙 메시지는 이런 형식으로 보내라", "보고서는 이런 구조로 만들어라"를 전부 claude.md에 넣는 대신, /rules/communication.md 파일을 만들고 claude.md에는 한 줄만 남깁니다. "커뮤니케이션 규칙은 /rules/communication.md를 참조하라."

claude.md의 본질을 한 문장으로 요약하면 이렇습니다. 에이전트에게 "너는 누구이고, 이 프로젝트에서 무엇을 하며, 더 자세한 정보가 필요하면 어디를 봐야 하는지"를 알려주는 목차(Table of Contents)입니다.

이 목차가 제 역할을 하려면, 에이전트가 읽고 처리하는 단위인 토큰에 대해 이해해야 합니다. claude.md가 길어지면 토큰이 많이 소모된다고 했는데, 토큰이 정확히 무엇이고, 왜 중요하며, 어떻게 관리하는지. 이것이 다음 장의 주제입니다.

6장 토큰, 컨텍스트 윈도우, 컨텍스트 관리

■가 토큰이란 무엇인가: 약 3~4글자, 단어의 75% 정도

식당 주방에 주문이 밀려들고 있습니다. 주방장이 동시에 처리할 수 있는 주문서의 수에는 한계가 있습니다. 카운터 위에 올려놓을 수 있는 주문서가 열 장이라면, 열한 번째 주문서는 어딘가에서 기다려야 합니다. 그리고 주문서가 쌓일수록 주방장의 주의력은 분산되어, 다섯 번째쯤 들어온 주문의 세부 요청("양파는 빼주세요")을 놓칠 확률이 올라갑니다.

클로드 코드 에이전트에게도 이와 비슷한 물리적 한계가 있습니다. 그 한계를 이해하는 열쇠가 토큰(Token)입니다.

사람은 글을 글자와 단어 단위로 읽습니다. AI는 토큰 단위로 읽습니다. 토큰은 AI가 텍스트를 처리하는 최소 단위입니다. 영어 기준으로 한 토큰은 대략 3~4개의 글자에 해당하며, 단어 하나의 약 75%에 해당합니다. "information"이라는 단어는 두세 개의 토큰으로 쪼개질 수 있습니다. 쉼표나 마침표도 각각 하나의 토큰을 차지합니다. 띄어쓰기도 토큰에 포함됩니다.

한국어의 경우 영어보다 토큰 효율이 다소 낮습니다. 한글 한 글자가 하나 이상의 토큰을 차지하는 경우가 많기 때문입니다. 같은 의미의 문장을 한국어로 쓰면 영어보다 토큰을 더 많이 소모할 수 있다는 점을 알아두면 좋습니다.

토큰이 중요한 이유는 두 가지입니다. 비용과 품질. 여러분의 구독 플랜은 일정 기간 내에 사용할 수 있는 토큰 총량에 한도가 있습니다. 토큰을 많이 쓸수록 한도에 빨리 도달합니다. 그리고 한 번의 대화에서 토큰이 많이 쌓일수록, 에이전트의 응답 품질이 떨어집니다. 이것이 다음 항목의 주제입니다.

■나 컨텍스트 윈도우는 클로드의 작업 메모장이다

(1) 시스템 프롬프트, 도구, MCP 서버, 대화 이력이 모두 이 안에 들어간다

컨텍스트 윈도우(Context Window)는 에이전트의 작업 메모장입니다. 에이전트가 한 번에 볼 수 있는 정보의 총량이라고 생각하면 됩니다.

이 메모장 안에는 여러 가지가 들어 있습니다. 가장 먼저 claude.md(시스템 프롬프트)가 자리를 차지합니다. 그 다음으로 에이전트가 사용할 수 있는 도구 목록, MCP 서버(16장에서 다룹니다) 정보, 스킬(17장에서 다룹니다) 내용이 들어갑니다. 그리고 여러분과 에이전트 사이의 대화 이력, 에이전트가 읽은 파일 내용, 실행한 명령어의 결과까지 전부 이 메모장에 기록됩니다.

(2) 200K 토큰의 표준 윈도우

이 메모장의 크기는 무한하지 않습니다. 이 책을 집필하는 시점에서 클로드 모델의 표준 컨텍스트 윈도우는 약 200,000토큰입니다. 200,000토큰이면 대략 영어 기준 150,000단어, A4 용지 약 300쪽 분량입니다. 상당히 넓은 공간이지만, 복잡한 프로젝트에서는 생각보다 빠르게 채워집니다.

에이전트에게 긴 워크플로우를 실행시키면서 여러 차례 대화를 주고받고, 여러 파일을 읽고, MCP 서버를 여러 개 연결해 놓으면, 컨텍스트 윈도우가 순식간에 절반 이상 차는 것을 목격하게 됩니다.

■다 컨텍스트 로트(Context Rot): 토큰이 쌓일수록 품질이 떨어진다

(1) "중간에서 길 잃기" 현상

컨텍스트 윈도우가 가득 차기 전에도 문제가 발생할 수 있습니다. 컨텍스트 로트(Context Rot)라고 부르는 현상입니다.

이해를 돕기 위해, 두꺼운 소설책을 한 번에 읽는 상황을 떠올려 보십시오. 처음 50쪽은 등장인물의 이름과 관계를 선명하게 기억합니다. 마지막 50쪽에서 벌어지는 사건도 생생합니다. 그런데 중간의 200쪽은? 기억이 흐릿합니다. "아, 이 인물이 여기서 뭔가 했었는데..." 하고 되뇌지만 세부 사항이 떠오르지 않습니다.

AI 모델에서도 비슷한 현상이 관찰됩니다. 대화의 시작 부분과 가장 최근 부분에 있는 정보는 비교적 정확하게 참조하지만, 중간에 있는 정보는 놓치거나 왜곡할 확률이 높아집니다. 이것을 "중간에서 길 잃기(Lost in the Middle)" 현상이라고 합니다.

(2) 모든 모델에서 관찰되는 정확도 하락 곡선

컨텍스트 로트는 클로드만의 문제가 아닙니다. GPT를 포함한 모든 대규모 언어모델(LLM, Large Language Model)에서 관찰되는 현상입니다. 토큰이 쌓일수록 에이전트의 응답 정확도가 꾸준히 하락하는 곡선을 그립니다. 특정 임계점을 넘으면 하락이 급격해집니다.

실무적 함의는 명확합니다. 에이전트가 갑자기 이상한 답변을 하거나, 이전에 합의한 규칙을 무시하거나, 존재하지 않는 정보를 만들어내기 시작하면, 컨텍스트 로트를 의심해야 합니다.

■라 필수 명령어 네 가지: /context, /compact, /clear, /rewind

컨텍스트 로트에 대응하는 도구가 슬래시 명령어입니다. 네 가지만 기억하면 됩니다.

/context는 현재 토큰 사용 현황을 보여줍니다. 채팅창에 이 명령어를 입력하면, 전체 컨텍스트 윈도우의 몇 퍼센트가 사용 중인지, 시스템 프롬프트가 몇 토큰을 차지하는지, 도구와 MCP 서버가 얼마나 먹고 있는지, 대화 이력이 얼마인지를 항목별로 보여줍니다. 병원에서 건강 검진을 받는 것과 같습니다. 어디에 토큰이 집중되어 있는지 파악해야 대책을 세울 수 있습니다.

/compact는 대화를 압축합니다. 에이전트가 지금까지의 대화에서 핵심 정보만 추출하고, 나머지를 버립니다. 200,000토큰 중 60%를 사용하고 있었다면, 압축 후 10~15%로 줄어들 수 있습니다. 핵심 정보는 유지되므로, 압축 전과 후의 에이전트 행동에 큰 차이가 없어야 합니다.

/compact에는 유용한 옵션이 있습니다. /compact 뒤에 "웹사이트 디자인에 대한 정보를 유지해줘"라고 덧붙이면, 에이전트가 그 주제와 관련된 정보를 우선적으로 보존하고 나머지를 정리합니다. 중요한 맥락을 지정해서 압축할 수 있는 것입니다.

/clear는 대화를 완전히 지웁니다. 컨텍스트 윈도우를 백지 상태로 되돌립니다. 작업 주제가 완전히 바뀔 때, 혹은 컨텍스트 로트가 심해져서 에이전트의 응답을 신뢰하기 어려울 때 사용합니다. /clear를 실행해도 프로젝트의 파일(워크플로우, 도구, claude.md)은 그대로 남아 있습니다. 사라지는 것은 대화 이력뿐입니다.

/rewind는 대화의 특정 시점으로 되돌아갑니다. 에이전트가 코드를 수정했는데 결과가 나빠졌다면, /rewind로 수정 전 시점으로 되돌릴 수 있습니다. 워드 프로세서의 "실행 취소(Ctrl+Z)"와 비슷한 기능입니다.

■마 오토컴팩트 기능과 초보자를 위한 조언

이 네 가지 명령어를 매번 기억하고 적시에 실행하는 것이 부담스러울 수 있습니다. 다행히 클로드 코드에는 오토컴팩트(Auto-compact) 기능이 내장되어 있습니다. 컨텍스트 윈도우가 일정 수준 이상 차면, 에이전트가 자동으로 대화를 압축합니다. 채팅창 하단의 상태 표시줄에 "context: 45% remaining until auto-compact" 같은 메시지가 나타나서, 현재 여유 공간이 얼마나 남았는지 알려줍니다.

처음 클로드 코드를 사용할 때는 컨텍스트 관리에 지나치게 신경 쓸 필요가 없습니다. 오토컴팩트가 알아서 처리해 줍니다. 다만, 에이전트가 갑자기 이상하게 행동하기 시작하면 /context로 토큰 현황을 확인하고, 필요하면 /compact나 /clear를 사용하는 습관을 들이십시오.

경험이 쌓이면 자신만의 기준이 생깁니다. "컨텍스트 사용률이 60%를 넘으면 /compact를 한다", "작업 주제가 바뀌면 무조건 /clear를 한다" 같은 개인 규칙입니다. 8부의 해킹 팁 장에서 이런 실전 노하우를 더 자세히 다룹니다.

토큰과 컨텍스트 윈도우를 이해했으니, 이제 에이전트의 두뇌 자체를 선택하는 문제가 남았습니다. 클로드 코드에서 사용할 수 있는 모델은 하나가 아닙니다. 빠르지만 가벼운 모델, 균형 잡힌 모델, 무겁지만 깊이 사고하는 모델. 상황에 따라 적절한 모델을 골라 쓰는 전략이 필요합니다.

7장 모델 선택 전략

■가 Haiku, Sonnet, Opus 세 모델 패밀리의 성격

자동차를 고르는 상황을 생각해 보십시오. 시내 출퇴근용으로는 연비 좋은 소형차가 적합합니다. 가족 여행에는 넓은 SUV가 필요하고, 이삿짐을 옮기려면 트럭이어야 합니다. 세 차가 각각 나쁜 차인 것이 아니라, 목적에 따라 최적의 선택이 달라질 뿐입니다.

클로드 코드에서 사용할 수 있는 AI 모델도 마찬가지입니다. 앤트로픽은 세 가지 모델 패밀리를 제공합니다. 하이쿠(Haiku), 소네(Sonnet), 오퍼스(Opus). 이름 뒤에 붙는 숫자(3.5, 4, 4.5, 4.6 등)는 버전을 나타냅니다. 숫자가 올라갈수록 성능이 개선된 새 버전입니다. 자동차의 연식이 올라가면 안전 장비와 연비가 좋아지는 것과 같습니다.

하이쿠는 소형차입니다. 가장 빠르고, 가장 가볍고, 토큰 소비가 가장 적습니다. 복잡한 추론보다는 단순 반복 작업, 대량의 텍스트 처리, 빠른 응답이 필요한 상황에 적합합니다.

소네는 중형 세단입니다. 속도와 추론 능력의 균형이 잡혀 있습니다. 일상적인 코딩, 워크플로우 구축, 데이터 분석 같은 대부분의 작업에서 충분한 성능을 발휘합니다. 가격 대비 성능이 뛰어나서 범용 모델로 쓰기에 가장 무난합니다.

오퍼스는 대형 SUV입니다. 가장 느리지만 가장 깊이 사고합니다. 복잡한 아키텍처 결정, 다단계 추론이 필요한 디버깅, 미묘한 맥락을 파악해야 하는 전략적 판단에서 강합니다. 토큰 소비가 가장 많으므로, 한도에 도달하는 속도도 빠릅니다.

■나 Sonnet으로 80%, Opus로 복잡한 아키텍처 판단, 다시 Sonnet으로 돌아오기

세 모델 중 어떤 것을 기본으로 사용해야 할까요. 실무에서 검증된 전략은 "소네 중심, 오퍼스 보조"입니다.

일상 작업의 약 80%를 소네로 처리합니다. 워크플로우 파일 작성, 도구 생성, 테스트 실행, 간단한 수정. 이 모든 과정에서 소네는 충분히 빠르고 정확합니다.

나머지 20%, 특히 복잡한 판단이 필요한 순간에 오퍼스로 전환합니다. 프로젝트의 전체 아키텍처를 설계해야 할 때, 여러 도구가 얽혀 있는 까다로운 버그를 추적할 때, 또는 서로 상충하는 요구 사항 사이에서 최선의 타협안을 찾아야 할 때. 이런 상황에서 오퍼스의 깊은 추론 능력이 차이를 만듭니다.

판단이 끝나면 다시 소네로 돌아옵니다. 오퍼스가 설계한 구조를 소네가 구현하는 분업입니다.

하이쿠는 서브에이전트(23장에서 다룹니다)에 배정할 때 빛을 발합니다. 메인 에이전트가 소네나 오퍼스로 전략적 판단을 하고, 반복적인 데이터 처리 같은 하위 작업은 하이쿠에게 맡기면 토큰 비용을 크게 절감할 수 있습니다.

처음 시작하는 단계에서는 이런 전략을 고민할 필요 없이, 기본 설정(소네 또는 오퍼스)을 그대로 사용하면 됩니다. 프로젝트가 복잡해지고 토큰 관리가 중요해지는 시점에 모델 전환 전략을 적용해도 늦지 않습니다.

■다 /model 명령어로 세션 중간에 모델 전환하기

모델 전환은 어렵지 않습니다. 채팅창에 /model을 입력하면, 선택 가능한 모델 목록이 팝업으로 나타납니다. 기본(Default), 소네(Sonnet), 하이쿠(Haiku), 오퍼스(Opus) 중 하나를 클릭하면 즉시 전환됩니다. 대화 도중에 언제든 바꿀 수 있습니다.

예를 들어, 소네로 워크플로우를 구축하다가 에이전트가 프로젝트 구조에 대해 잘못된 판단을 내렸다고 느끼면, /model로 오퍼스로 전환한 뒤 "이 프로젝트의 전체 구조를 다시 검토해줘"라고 요청합니다. 오퍼스가 더 깊이 분석한 결과를 바탕으로 구조를 수정한 뒤, 다시 소네로 돌아와서 세부 구현을 이어갑니다.

■라 서브에이전트에 Haiku를 배정해 토큰 비용 절감하기

7부에서 서브에이전트 개념을 본격적으로 다루겠지만, 모델 선택과 직결되는 내용이므로 핵심만 미리 짚어두겠습니다.

서브에이전트(Sub-agent)는 메인 에이전트가 특정 하위 작업을 위임하는 별도의 에이전트입니다. 메인 에이전트가 "이 데이터를 정리해줘"라고 서브에이전트에게 요청하면, 서브에이전트는 자체 컨텍스트 윈도우 안에서 독립적으로 작업을 수행하고 결과를 돌려줍니다.

이때 서브에이전트에 하이쿠를 배정하면 토큰 비용이 크게 줄어듭니다. 데이터 정리, 단순 변환, 반복적 검색 같은 작업은 깊은 추론이 필요 없습니다. 빠르고 저렴한 하이쿠가 안성맞춤입니다.

정리하면 이렇습니다. 오퍼스는 건축가, 소네는 현장 감독, 하이쿠는 작업 인부. 건축가가 매번 벽돌을 나를 필요가 없고, 작업 인부에게 건물 전체의 구조 설계를 맡길 수도 없습니다. 각자 잘하는 일을 맡기는 것이 효율적인 팀 운영입니다.

모델을 골랐으니, 이제 에이전트가 실제로 사용하는 도구를 한번 훑어보겠습니다. 에이전트가 파일을 읽고, 터미널 명령을 실행하고, 웹에서 데이터를 가져올 때, 내부에서는 어떤 빌트인 도구가 작동하는지. 이름을 외울 필요는 없습니다. 흐름 속에서 "아, 이게 그거구나" 하고 알아볼 수 있으면 충분합니다.

8장 빌트인 도구 이해하기

■가 Read, Write, Edit: 파일 조작의 기본

여러분이 사무실에서 서류를 다루는 방식을 생각해 보십시오. 캐비닛에서 파일을 꺼내 읽고, 새 문서를 작성해서 넣고, 기존 문서의 일부를 수정합니다. 클로드 코드 에이전트도 파일을 다루는 기본 동작이 있습니다. 리드(Read), 라이트(Write), 에디트(Edit). 각각 파일 읽기, 파일 생성, 파일 수정에 해당합니다.

에이전트가 claude.md를 읽을 때 리드 도구가 작동합니다. 새 워크플로우 파일을 만들 때 라이트 도구가 작동합니다. 기존 도구 스크립트에서 한 줄을 고칠 때 에디트 도구가 작동합니다. 에이전트의 채팅창에서 이런 동작이 일어날 때, "Read file: claude.md" 또는 "Write file: tools/scrape_website.py" 같은 메시지가 표시됩니다.

여러분이 직접 이 도구를 호출할 일은 없습니다. 에이전트가 상황에 맞게 자동으로 선택합니다. 다만, 채팅창에서 이런 표시를 보았을 때 "아, 에이전트가 지금 파일을 읽고 있구나" 혹은 "새 파일을 만들고 있구나"라고 알아차릴 수 있으면 됩니다.

■나 Bash, Glob, Grep, LS: 터미널 명령과 파일 탐색

사무실 비유를 이어가겠습니다. 캐비닛에서 특정 서류를 찾으려면 서랍을 하나씩 열어봐야 합니다. 서류가 많으면 이름표를 보고 찾습니다. 때로는 서류 안의 특정 문구를 기준으로 검색해야 할 때도 있습니다.

배시(Bash)는 에이전트가 터미널 명령을 실행하는 도구입니다. 터미널이란 컴퓨터에게 텍스트로 명령을 내리는 창입니다. 에이전트가 파이썬 스크립트를 실행하거나, 패키지를 설치하거나, API를 테스트할 때 배시 도구를 사용합니다. 채팅창에 "Bash: pip install requests" 같은 메시지가 나타나면, 에이전트가 터미널에서 소프트웨어 패키지를 설치하고 있다는 뜻입니다.

글로브(Glob)는 파일 이름 패턴으로 여러 파일을 한꺼번에 찾는 도구입니다. "tools 폴더에서 .py로 끝나는 파일을 모두 찾아라" 같은 작업에 사용됩니다.

그렙(Grep)은 파일 내용 안에서 특정 텍스트를 검색하는 도구입니다. "모든 파이썬 파일에서 'API_KEY'라는 문자열이 들어 있는 줄을 찾아라" 같은 작업입니다.

LS는 특정 폴더 안에 어떤 파일이 있는지 목록을 보여주는 도구입니다. 서랍을 열어서 안에 무엇이 있는지 훑어보는 것과 같습니다.

이 네 가지 도구의 이름을 외울 필요는 없습니다. 에이전트가 채팅창에서 이런 이름을 표시할 때, "파일을 찾고 있구나", "명령을 실행하고 있구나" 정도만 파악하면 됩니다.

■다 WebFetch, WebSearch: 외부 데이터 가져오기

에이전트가 여러분의 컴퓨터 안에 있는 파일만 다룰 수 있다면, 활용 범위가 제한됩니다. 웹페치(WebFetch)와 웹서치(WebSearch)는 에이전트가 인터넷에서 정보를 가져오는 도구입니다.

웹페치는 특정 URL의 내용을 읽어옵니다. 에이전트에게 "이 웹페이지의 내용을 요약해줘"라고 요청하면, 웹페치가 해당 페이지의 텍스트를 가져와서 에이전트에게 전달합니다.

웹서치는 검색 엔진을 통해 정보를 찾습니다. 에이전트에게 "2025년 에이전틱 AI 시장 규모를 찾아줘"라고 요청하면, 웹서치가 관련 검색 결과를 가져옵니다.

뉴스레터 자동화에서 퍼플렉시티 API를 사용한 리서치 단계가 바로 이 웹서치 계열 도구의 활용 사례입니다. 에이전트가 외부 데이터 소스에 접근해서, 최신 정보를 프로젝트 안으로 끌어들이는 과정입니다.

■라 도구 이름을 외울 필요 없이 흐름 속에서 자연스럽게 익히는 법

이 장에서 소개한 빌트인 도구를 정리하면 리드, 라이트, 에디트, 배시, 글로브, 그렙, LS, 웹페치, 웹서치입니다. 아홉 가지입니다.

아홉 가지를 지금 당장 암기하려 하지 마십시오. 그 대신, 클로드 코드를 사용하면서 채팅창에 표시되는 도구 이름을 눈여겨보십시오. "Bash: python tools/research.py"라는 메시지가 나오면, "배시 도구로 파이썬 스크립트를 실행하고 있구나"라고 읽으면 됩니다. "Glob: tools/*.py"가 나오면, "도구 폴더에서 파이썬 파일을 찾고 있구나"라고 읽으면 됩니다.

에이전트의 행동을 관찰하는 습관이 기술 이해의 가장 빠른 길입니다. 에이전트가 무엇을 생각하고, 어떤 도구를 선택하고, 어떤 명령을 실행하는지 읽다 보면, 자연스럽게 도구의 역할이 체화됩니다. 모르는 도구 이름이 나오면 에이전트에게 물어보면 됩니다. "방금 실행한 Glob이 뭐야?"라고 치면 에이전트가 친절하게 설명해 줍니다.

이것으로 제2부가 마무리됩니다. VS Code를 설치하고, 클로드 코드를 연결하고, claude.md로 에이전트에게 프로젝트의 맥락을 주고, 토큰과 컨텍스트 윈도우의 원리를 이해하고, 모델 선택 전략을 알고, 빌트인 도구의 존재를 인지했습니다. 에이전틱 시스템의 기초 체력이 갖춰진 셈입니다.

제3부에서는 이 기초 위에 실전 프로젝트를 올려놓습니다. 슬래시 명령어를 총정리하고, 프로젝트 폴더의 설계 원칙을 배우고, RAG(검색 증강 생성)와 벡터 데이터베이스라는 강력한 도구를 만납니다. 에이전트가 외부 문서 수천 건을 검색해서 정확한 답을 찾아내는 과정. 거기에 어떤 마법이 숨어 있는지 알게 되면, 에이전틱 시스템에 대한 시야가 한 단계 넓어질 것입니다.

9장 빌트인 명령어 총정리

■가 /init: 프로젝트 초기화

새 학기 첫날, 담임 선생님이 칠판에 이번 학기 시간표를 적습니다. 교과서 목록, 준비물, 수업 규칙. 이 정보가 있어야 학생들은 내일부터 무엇을 들고 와야 하는지 알 수 있습니다. /init 명령어는 클로드 코드 프로젝트의 "첫날 오리엔테이션"입니다.

채팅창에 /init을 입력하면, 에이전트가 현재 폴더의 구조와 파일을 스캔합니다. 그리고 프로젝트에 맞는 claude.md 초안을 자동으로 생성합니다. 이미 코드가 들어 있는 폴더에서 실행하면, 에이전트가 기존 코드의 언어, 프레임워크, 의존성 패키지까지 파악해서 claude.md에 반영합니다. 빈 폴더에서 실행하면 기본적인 프로젝트 구조를 제안합니다.

5장에서 강조했듯이, /init이 만들어주는 claude.md는 출발점일 뿐입니다. WAT 프레임워크의 세부 규칙이나 브랜드 정보 같은 프로젝트 고유의 맥락은 직접 추가해야 합니다. 그래도 백지 상태에서 시작하는 것보다 훨씬 빠르게 궤도에 오를 수 있습니다.

■나 /model: 모델 전환

7장에서 다룬 모델 전환을 실행하는 명령어입니다. /model을 입력하면 선택 가능한 모델 목록이 팝업으로 나타납니다. 기본(Default), 소네(Sonnet), 하이쿠(Haiku), 오퍼스(Opus) 중 하나를 클릭하면 즉시 전환됩니다.

대화 도중 언제든 바꿀 수 있다는 점이 핵심입니다. 소네로 워크플로우를 구축하다가 아키텍처 판단이 필요한 순간에 /model로 오퍼스로 전환하고, 판단이 끝나면 다시 소네로 돌아옵니다. 모델 전환은 같은 세션 안에서 대화 맥락을 유지한 채 이루어지므로, 이전 대화 내용을 다시 설명할 필요가 없습니다.

■다 /doctor, /status: 환경 진단과 상태 확인

/doctor는 클로드 코드 설치 환경을 진단합니다. 확장이 제대로 설치되었는지, 인증이 유효한지, 필요한 의존성이 갖춰져 있는지를 점검합니다. 컴퓨터를 새로 세팅했거나, 클로드 코드가 예상과 다르게 동작할 때 가장 먼저 실행해 볼 명령어입니다. 건강 검진과 같습니다. 문제가 발견되면 원인과 해결 방법을 함께 알려줍니다.

/status는 현재 세션의 기본 정보를 표시합니다. 클로드 코드의 버전, 사용 중인 모델, 연결된 계정, 구독 플랜 정보 등이 한눈에 나타납니다. "내가 지금 어떤 모델을 쓰고 있지?"가 궁금할 때, /model을 입력해서 전환 화면을 열 필요 없이 /status로 확인할 수 있습니다.

■라 /context, /compact, /clear, /rewind: 컨텍스트 관리 도구

6장에서 상세히 다룬 네 가지 명령어입니다. 반복이 되더라도, 이 장에서는 실무적 사용 시나리오 중심으로 다시 정리합니다.

/context를 실행하면 토큰 사용 현황이 항목별로 나타납니다. 시스템 프롬프트가 차지하는 비율, MCP 서버와 스킬이 소비하는 토큰, 대화 이력의 누적량을 파악할 수 있습니다. "왜 이렇게 빨리 한도에 도달하지?"라는 의문이 들 때, /context가 원인을 짚어줍니다. 예를 들어 MCP 서버 세 개를 연결해 놓았는데 그 중 하나만 실제로 사용하고 있다면, 사용하지 않는 서버를 해제해서 토큰을 절약할 수 있습니다.

/compact는 대화를 압축합니다. 실무에서 가장 자주 사용하는 시점은 컨텍스트 사용률이 60%를 넘었을 때입니다. 압축할 때 "웹사이트 디자인 관련 정보를 유지해줘"처럼 보존할 주제를 지정할 수 있다는 점을 6장에서 설명했습니다. 이 기능은 작업 중간에 주제가 섞여 있을 때 유용합니다.

/clear는 대화를 완전히 지웁니다. 작업 주제가 바뀔 때 사용합니다. 예를 들어 뉴스레터 워크플로우를 구축하다가, 이제 경쟁사 분석 워크플로우로 넘어갈 때. 이전 대화의 잔여 맥락이 새 작업을 오염시키는 것을 방지합니다.

/rewind는 대화의 이전 시점으로 되돌립니다. 에이전트가 코드를 수정했는데 오히려 나빠졌을 때, /rewind로 수정 전 상태로 복원합니다.

■마 기타 슬래시 명령어 모음

위의 핵심 명령어 외에도 알아두면 유용한 명령어가 있습니다.

/help는 사용 가능한 모든 슬래시 명령어 목록을 보여줍니다. 어떤 명령어가 있는지 기억나지 않을 때, /help 하나면 충분합니다.

/cost는 현재 세션의 토큰 사용량과 비용을 표시합니다. 구독 한도 관리에 도움이 됩니다.

/memory는 에이전트의 자동 기억(Auto Memory) 파일을 편집합니다. 에이전트에게 "항상 pnpm을 사용해"라고 말하면, 에이전트가 이 선호를 글로벌 메모리에 저장합니다. /memory로 저장된 내용을 확인하거나 수정할 수 있습니다.

/permissions는 에이전트의 권한 설정을 관리합니다. 어떤 명령을 자동으로 실행할 수 있고, 어떤 명령은 사용자 승인이 필요한지를 제어합니다. 28장의 권한 설정에서 자세히 다룹니다.

/mcp는 연결된 MCP 서버를 관리합니다. 서버 추가, 제거, 상태 확인이 가능합니다. 16장에서 본격적으로 살펴봅니다.

/agents는 서브에이전트를 생성하고 관리합니다. 23장의 서브에이전트 챕터에서 실습합니다.

이 명령어들을 전부 외울 필요는 없습니다. /help 하나만 기억하면 나머지를 언제든 찾을 수 있습니다. 클로드 코드를 사용하면서 자연스럽게 필요한 명령어가 손에 익게 됩니다. 명령어를 잊었다면, 자연어로 "토큰 사용 현황을 보여줘"라고 말해도 에이전트가 알아서 /context를 실행합니다.

슬래시 명령어로 에이전트를 제어하는 방법을 알았으니, 이제 에이전트가 일하는 공간 자체를 설계하는 문제로 넘어갑니다. 프로젝트 폴더를 어떻게 구성하느냐에 따라 에이전트의 효율이 크게 달라집니다.

10장 프로젝트 폴더 아키텍처

■가 세 단계 설정 계층구조

아파트에 사는 것을 생각해 보십시오. 아파트 단지 전체에 적용되는 관리 규약이 있습니다. 쓰레기 분리수거 요일, 주차 규칙, 공용 시설 이용 시간. 그 위에 각 동(棟)마다 다른 세부 규칙이 있을 수 있습니다. 그리고 여러분의 세대(世帶) 안에서는 여러분만의 생활 규칙이 적용됩니다. 식기세척기를 돌리는 시간, 청소기를 돌리는 요일.

클로드 코드의 설정도 이와 같은 계층구조를 가집니다. 세 개의 단계가 있습니다.

(1) 글로벌(사용자) 수준: 틸다(~) 경로, 모든 프로젝트에 적용

글로벌 설정은 여러분의 컴퓨터에 있는 모든 클로드 코드 프로젝트에 적용됩니다. 홈 디렉토리의 틸다(~) 경로 아래에 위치합니다. 경로 앞에 ~ 기호가 붙어 있으면 글로벌 설정입니다.

여기에 저장하는 것들의 예를 들면, 프런트엔드 디자인 스킬처럼 모든 프로젝트에서 사용하고 싶은 스킬, "항상 pnpm을 사용하라"처럼 개인적인 선호, 또는 특정 MCP 서버를 항상 허용하는 설정 등입니다.

(2) 프로젝트 수준: .claude/settings.json, 팀 공유 설정

프로젝트 수준 설정은 해당 프로젝트 폴더 안의 .claude 디렉토리에 위치합니다. settings.json 파일이 여기에 들어갑니다. 이 파일은 프로젝트에 접근하는 모든 사람이 공유합니다. 팀으로 작업할 때, 팀원 모두가 같은 규칙 아래에서 에이전트를 사용하도록 보장합니다.

(3) 로컬 수준: settings.local.json, 개인 오버라이드

로컬 설정은 같은 .claude 디렉토리 안의 settings.local.json 파일입니다. 프로젝트 설정을 따르되, 특정 항목만 여러분 개인의 환경에 맞게 덮어쓰고 싶을 때 사용합니다.

■나 설정 우선순위: 로컬이 프로젝트를, 프로젝트가 글로벌을 덮어쓴다

세 단계의 설정이 충돌하면 어떻게 될까요. 우선순위는 명확합니다. 로컬이 가장 높고, 그 다음이 프로젝트, 마지막이 글로벌입니다.

에이전트가 어떤 동작을 수행하려 할 때, 먼저 로컬 설정을 확인합니다. 로컬 설정에서 해당 동작이 허용되어 있으면, 그대로 실행합니다. 로컬 설정에 해당 항목이 없으면, 프로젝트 설정을 확인합니다. 프로젝트 설정에도 없으면, 글로벌 설정을 확인합니다.

예를 들어 글로벌 설정에서 "파일 읽기(Read)를 항상 허용"으로 설정해 두었다고 합시다. 그런데 특정 프로젝트의 settings.json에서 "파일 읽기 금지"로 설정되어 있다면, 그 프로젝트에서는 에이전트가 파일을 읽지 못합니다. 프로젝트 설정이 글로벌을 덮어쓴 것입니다.

이 계층구조가 실무에서 중요한 이유는 보안과 편의의 균형 때문입니다. 글로벌 수준에서는 넉넉하게 권한을 열어두되, 민감한 데이터를 다루는 프로젝트에서는 프로젝트 수준에서 권한을 좁히는 식으로 운영할 수 있습니다.

■다 실전 폴더 구성 사례: 이그제큐티브 어시스턴트 프로젝트의 디렉토리

(1) .claude, archives, brand-assets, projects, skills 폴더의 역할

이론만으로는 와닿지 않으니, 실제 프로젝트의 폴더 구조를 들여다보겠습니다. 이 책의 6부에서 구축할 이그제큐티브 어시스턴트 프로젝트의 디렉토리입니다.

최상위에 .claude 폴더가 있습니다. 설정 파일(settings.json, settings.local.json), claude.md, 규칙(rules), 스킬(skills), 에이전트(agents) 파일이 이 안에 들어갑니다. 프로젝트의 두뇌에 해당하는 폴더입니다.

archives 폴더에는 과거 실행 결과물이 날짜별로 보관됩니다. 이전 분석 보고서, 지난주 뉴스레터 아카이브 같은 것들입니다.

brand-assets 폴더에는 로고, 브랜드 가이드라인, 색상 팔레트 파일이 들어갑니다.

projects 폴더에는 현재 진행 중인 하위 프로젝트가 각각의 서브폴더로 관리됩니다.

skills 폴더에는 이 프로젝트에서만 사용하는 로컬 스킬 파일이 들어갑니다. 글로벌 스킬과 구분됩니다.

프로젝트 루트에는 claude.md, claude.local.md, .env, .gitignore 파일이 위치합니다.

(2) .gitignore 설정으로 민감 파일 제외하기

폴더 구조에서 빼놓을 수 없는 파일이 .gitignore입니다. 이 파일은 깃(Git, 15장과 30장에서 자세히 다룹니다)에게 "이 파일들은 절대 업로드하지 마"라고 지시하는 목록입니다.

.env 파일(API 키와 비밀번호가 저장된 파일), OAuth 인증 토큰 파일, 개인 설정 파일 같은 것들을 .gitignore에 등록해 둡니다. 이렇게 하면 프로젝트를 깃허브(GitHub)에 올려도 민감한 정보가 노출되지 않습니다.

VS Code의 파일 탐색기에서 .gitignore에 등록된 파일은 회색으로 표시됩니다. 이 시각적 단서 덕분에 "이 파일은 공개되지 않는다"는 것을 한눈에 확인할 수 있습니다. 반대로, 초록색으로 표시된 파일은 깃에 아직 등록되지 않은 새 파일이고, 노란색은 수정된 파일입니다. 이 색상 체계에 익숙해지면 프로젝트의 현재 상태를 탐색기만 훑어봐도 파악할 수 있습니다.

프로젝트의 뼈대를 잡는 방법을 알았으니, 이제 에이전트가 외부 지식을 끌어와 활용하는 강력한 기법으로 넘어갑니다. 에이전트의 훈련 데이터에 없는 정보, 여러분의 회사 내부 문서나 제품 매뉴얼 같은 것을 에이전트가 검색해서 정확한 답을 찾아내는 구조. 이것이 RAG(검색 증강 생성)이고, 그 뒤에는 벡터 데이터베이스라는 기술이 작동하고 있습니다.

11장 RAG와 벡터 데이터베이스

■가 RAG(검색 증강 생성)의 개념

도서관 사서에게 질문을 했다고 합시다. "최신 무선청소기의 필터 청소 방법을 알려주세요." 사서가 가진 지식만으로는 특정 제품의 필터 교체 절차를 정확히 대답하기 어렵습니다. 하지만 사서가 서가에서 해당 제품의 사용 설명서를 꺼내 관련 페이지를 펼쳐보고 나면, 정확한 답변을 할 수 있습니다. 사서의 전문성(답변 능력)과 서가의 자료(외부 정보)가 결합된 것입니다.

RAG(Retrieval-Augmented Generation, 검색 증강 생성)가 바로 이 과정입니다. AI 에이전트가 자신의 훈련 데이터에 없는 정보를 외부에서 "검색(Retrieval)"해 와서, 답변을 "증강(Augmented)"한 뒤, 최종 응답을 "생성(Generation)"합니다.

(1) 문서를 청크로 나누고 임베딩 모델로 벡터화하는 흐름

RAG가 작동하려면, 외부 정보를 AI가 검색할 수 있는 형태로 미리 가공해 두어야 합니다. 이 과정을 임베딩(Embedding)이라고 합니다.

68쪽짜리 무선청소기 사용 설명서 PDF가 있다고 합시다. 이 문서를 통째로 AI에게 넘기면 컨텍스트 윈도우를 너무 많이 차지합니다. 그래서 문서를 작은 조각으로 나눕니다. 이 조각을 청크(Chunk)라고 부릅니다. 한 청크는 문단 하나, 혹은 페이지 반쪽 분량 정도입니다.

각 청크를 임베딩 모델(Embedding Model)에 통과시키면, 텍스트가 숫자 배열, 즉 벡터(Vector)로 변환됩니다. 벡터는 해당 텍스트의 "의미"를 수학적으로 표현한 것입니다. "필터 청소 방법"에 관한 청크와 "배터리 충전 시간"에 관한 청크는 서로 다른 위치의 벡터로 변환됩니다. 의미가 다르기 때문입니다.

이렇게 변환된 벡터들을 벡터 데이터베이스(Vector Database)에 저장합니다. 파인콘(Pinecone)이 대표적인 벡터 데이터베이스 서비스입니다.

(2) 사용자 질문을 벡터로 변환해 유사 청크를 검색하는 원리

사용자가 "필터는 어떻게 청소하나요?"라고 질문하면, 이 질문도 같은 임베딩 모델을 통과해서 벡터로 변환됩니다. 벡터 데이터베이스는 이 질문 벡터와 가장 가까운(의미가 유사한) 청크 벡터를 찾아냅니다. "필터 청소 절차"가 담긴 청크, "필터 교체 주기"가 담긴 청크 등이 상위에 올라옵니다.

AI 에이전트는 이 검색된 청크들을 받아서, 자신의 언어 능력으로 자연스러운 답변을 구성합니다. 원본 문서의 정보를 기반으로 하되, 사용자의 질문에 맞게 재구성하는 것입니다.

이 전체 흐름을 정리하면: 문서 → 청크 분할 → 임베딩(벡터 변환) → 벡터 데이터베이스 저장 → 사용자 질문 → 질문 벡터 변환 → 유사 청크 검색 → AI가 답변 생성. 이것이 RAG의 파이프라인입니다.

■나 구글 제미나이 임베딩 2: 최초의 네이티브 멀티모달 임베딩

(1) 텍스트, 이미지, 비디오, 오디오를 하나의 벡터 공간에 담는다

전통적인 임베딩 모델은 텍스트만 처리할 수 있었습니다. 이미지를 검색하려면 이미지에 대한 텍스트 설명을 별도로 작성해서 임베딩해야 했습니다. 비디오나 오디오는 더 복잡했습니다.

구글이 발표한 제미나이 임베딩 2(Gemini Embedding 2)는 이 한계를 돌파했습니다. 텍스트, 이미지, 비디오, 오디오를 하나의 벡터 공간에 함께 배치할 수 있는 최초의 네이티브 멀티모달(Multimodal) 임베딩 모델입니다.

이것이 무슨 의미인지 감자 모양 스마일 감자튀김 사진, 기타 치는 강아지 동영상, 클로드 코드 사용법을 설명하는 텍스트 파일을 한꺼번에 임베딩한 실험으로 설명하겠습니다. 임베딩 결과를 2차원 공간에 시각화하면, 감자튀김 사진은 "음식" 카테고리 근처에, 강아지 동영상은 "엔터테인먼트" 근처에, 기술 문서는 "테크" 근처에 각각 자리를 잡습니다. 서로 다른 형식(이미지, 비디오, 텍스트)의 데이터가, 의미에 따라 같은 공간에서 정리된 것입니다.

(2) 지붕 수리 업체 사례: 사진 한 장으로 유사 과거 프로젝트 검색

이 기술의 실용적 가치를 보여주는 사례가 있습니다. 지붕 수리 업체가 과거 프로젝트 사진 13장을 벡터 데이터베이스에 저장했습니다. 각 사진에는 비용, 소요 기간, 투입 인원 같은 메타데이터가 함께 기록되어 있습니다.

새 고객이 자기 지붕 사진을 한 장 보냅니다. 이 사진을 벡터로 변환해서 데이터베이스를 검색하면, 가장 비슷한 과거 프로젝트 다섯 건이 유사도 점수와 함께 반환됩니다. "이 지붕과 비슷한 과거 프로젝트는 리치먼드 소재 2층 주택이었고, 비용은 얼마, 기간은 이틀이었습니다." 견적서를 작성할 때 참고 자료가 즉시 제공되는 것입니다.

사진 한 장으로 수백 건의 과거 프로젝트를 검색하는 이 과정이, 텍스트 검색만으로는 불가능했던 영역입니다. "빨간 기와 지붕에 물 얼룩이 있는 프로젝트를 찾아줘"라고 텍스트로 설명하는 것보다, 사진을 직접 보여주는 것이 훨씬 정확합니다.

■다 Pinecone 벡터 데이터베이스 연동 데모

(1) 데이터 폴더에 이미지, 비디오, 텍스트 넣기

이 모든 것을 직접 구축하려면 얼마나 복잡할까요. 미국의 한 AI 자동화 컨설턴트가 클로드 코드로 멀티모달 RAG 시스템을 구축한 과정은 이렇습니다.

VS Code에서 빈 프로젝트를 열고, 클로드 코드에게 말합니다. "구글의 새 임베딩 모델을 사용해서 파인콘 벡터 데이터베이스를 만들고 싶어. 이미지, 비디오, 텍스트를 다 넣을 수 있게 해줘. 끝나면 챗 웹 앱도 만들어줘." 에이전트가 계획을 세우고, 필요한 API 키(제미나이, 파인콘, 챗 모델용)의 자리표시자를 .env 파일에 만들어줍니다. API 키를 붙여넣고, 데이터 폴더에 파일을 드래그해 넣으면 준비가 끝납니다.

에이전트는 파일 형식을 자동으로 감지합니다. PNG는 이미지로, MP4는 비디오로, TXT는 텍스트로 분류합니다. 각 파일을 제미나이 임베딩 모델에 통과시켜 벡터로 변환하고, 파인콘 데이터베이스에 저장합니다.

n8n 같은 전통적 도구로 이 파이프라인을 구축하려면 몇 시간에서 며칠이 걸립니다. 파일 형식별 처리 노드를 따로 구성하고, 청크 분할 로직을 설계하고, 임베딩 API 호출을 설정하고, 데이터베이스 저장 노드를 연결해야 합니다. 클로드 코드로는 자연어 몇 문장과 API 키 세 개로 같은 결과를 얻었습니다.

(2) 웹 앱에서 자연어 질의와 이미지 검색 시연

데이터가 저장되면, 에이전트가 간단한 챗 웹 앱을 로컬호스트(Localhost, 여러분의 컴퓨터에서만 접근 가능한 웹 서버)에 띄워줍니다.

무선청소기 사용 설명서를 넣어둔 경우를 예로 들면, 챗 앱에 "필터는 어떻게 청소하나요?"라고 입력합니다. 시스템이 파인콘 데이터베이스를 검색해서 관련 텍스트 청크와 이미지를 가져옵니다. "필터를 분리하려면 이 버튼을 누르세요"라는 텍스트 답변과 함께, 해당 절차를 보여주는 다이어그램 이미지가 함께 표시됩니다. 이미지를 클릭하면 원본 크기로 볼 수 있습니다. 각 결과에는 신뢰도 점수(Confidence Score)가 표시되어, 검색 결과의 정확도를 판단할 수 있습니다.

텍스트로 된 설명만으로는 부족할 때, 실제 다이어그램이나 사진이 함께 제공되는 것. 이것이 멀티모달 RAG의 힘입니다.

RAG와 벡터 데이터베이스는 에이전틱 시스템의 기억력을 외부로 확장하는 기술입니다. 에이전트의 훈련 데이터에 없는 정보, 여러분의 회사 문서, 제품 사진, 교육 영상까지 검색 가능한 지식으로 바꿔줍니다.

이것으로 제3부가 마무리됩니다. 프로젝트를 초기화하고, 폴더 구조를 설계하고, 외부 지식까지 연동하는 방법을 익혔습니다. 에이전트의 능력이 점점 넓어지고 있습니다. 제4부에서는 이 능력을 눈에 보이는 결과물로 전환합니다. 웹사이트를 클론하고, 앱을 구축하고, 깃허브와 버셀(Vercel)을 통해 세상에 배포하는 과정. 여러분이 만든 것을 다른 사람들이 실제로 접속해서 사용하는 순간이 다가옵니다.

12장 웹사이트 클론과 커스터마이징

■가 참조 사이트 URL을 주고 클론 지시하기

부동산 중개사무소에 들어갔다고 합시다. "이런 집을 원합니다"라고 말로 설명하는 것과, 스마트폰에서 사진 한 장을 보여주며 "이런 느낌의 집이요"라고 말하는 것. 어느 쪽이 더 빠르게 원하는 결과에 가까워질까요. 웹사이트를 만드는 과정도 다르지 않습니다.

클로드 코드에게 "모던하고 깔끔한 랜딩 페이지를 만들어줘"라고 말할 수도 있습니다. 에이전트는 자신이 생각하는 "모던"과 "깔끔"의 기준으로 무언가를 만들어 줄 것입니다. 그러나 여러분의 머릿속에 있는 이미지와 에이전트의 해석 사이에는 간극이 있기 마련입니다. 여러 차례 수정을 거쳐야 원하는 결과에 도달합니다.

더 빠른 방법이 있습니다. 마음에 드는 웹사이트를 하나 찾아서, 그 URL을 클로드 코드에게 건네는 것입니다. "이 사이트를 클론해줘." 에이전트는 해당 사이트를 방문해서 구조를 파악하고, 레이아웃과 색상 체계를 분석한 뒤, 비슷한 외형의 웹사이트를 코드로 재현합니다.

클론이라고 해서 원본을 그대로 복제하는 것은 아닙니다. 저작권이 있는 이미지, 텍스트, 로고는 포함되지 않습니다. 재현되는 것은 레이아웃 구조, 색상 배치, 타이포그래피 스타일, 섹션 배열 같은 디자인 패턴입니다. 이 위에 여러분의 브랜드 에셋과 콘텐츠를 입히면, 참조 사이트의 세련된 느낌을 유지하면서도 완전히 고유한 웹사이트가 됩니다.

영감을 찾을 수 있는 웹사이트가 여러 곳 있습니다. 드리블(Dribbble), 갓리(Godly.website), 어워즈(Awwwards) 같은 디자인 갤러리에서 업종이나 스타일로 검색하면 참조할 만한 사이트를 금방 찾을 수 있습니다.

실습은 간단합니다. 참조할 사이트를 브라우저에서 열고, F12(윈도우 기준) 키를 눌러 개발자 도구를 엽니다. 콘솔(Console)에서 Ctrl+Shift+P를 누르고 "screenshot"을 검색하면 전체 페이지의 스크린샷을 캡처할 수 있습니다. 스타일 정보도 개발자 도구의 스타일(Styles) 섹션에서 복사합니다. 이 두 가지, 전체 스크린샷과 스타일 코드를 클로드 코드에게 함께 전달하면, 에이전트가 참조 사이트의 구조와 스타일을 훨씬 정확하게 재현합니다.

■나 스크린샷 루프: 클로드 코드가 코드를 짜고 스스로 비교 검증하는 순환

클론을 지시하면 에이전트가 코드를 작성하기 시작합니다. 그런데 에이전트는 코드만 작성하지 않습니다. 코드가 실제로 어떻게 렌더링되는지 스스로 확인합니다.

이 과정이 스크린샷 루프(Screenshot Loop)입니다. 에이전트가 웹사이트 코드를 작성한 뒤, 퍼피티어(Puppeteer, 웹 브라우저를 코드로 제어하는 도구)를 사용해 자신이 만든 페이지의 스크린샷을 찍습니다. 그리고 그 스크린샷을 참조 사이트의 스크린샷과 비교합니다. 색상이 다른 곳, 레이아웃이 틀어진 곳, 요소가 빠진 곳을 찾아냅니다. 차이를 발견하면 코드를 수정하고, 다시 스크린샷을 찍어 비교합니다.

(1) 최소 2회 이상의 비교 라운드

이 비교 과정은 최소 두 번 반복됩니다. 첫 번째 라운드에서 큰 구조적 차이를 수정하고, 두 번째 라운드에서 세부적인 색상, 여백, 글꼴 크기를 다듬습니다. 왼쪽 탐색기의 임시 스크린샷 폴더에 비교 이미지가 하나둘 쌓이는 것을 볼 수 있습니다.

(2) 스크린샷 파일 명명 규칙을 claude.md에 명시하기

스크린샷 루프를 사용하다 보면 임시 파일이 빠르게 쌓입니다. screenshot_1.png, screenshot_2.png처럼 무의미한 이름이 붙으면, 어떤 것이 참조 사이트이고 어떤 것이 클론 결과인지 구분하기 어렵습니다. claude.md에 "참조 스크린샷은 ref_ 접두어를, 클론 스크린샷은 clone_ 접두어를 붙여라"라는 명명 규칙을 추가해 두면, 파일 관리가 수월해집니다.

■다 동적 애니메이션에서 스크린샷 루프를 끄는 판단

스크린샷 루프에는 한 가지 함정이 있습니다. 배경에 애니메이션이 있는 요소, 예를 들어 물결치는 그라데이션이나 떠다니는 파티클 효과를 클론할 때, 스크린샷은 애니메이션의 한 프레임만 포착합니다. 에이전트가 그 정지 화면을 보고 "아직 원본과 다르다"고 판단해서 계속 수정을 반복하는 악순환에 빠질 수 있습니다. 움직이는 것을 정지 사진으로 비교하니 영원히 일치할 수 없는 것입니다.

이런 상황에서는 에이전트에게 명시적으로 말해야 합니다. "이건 애니메이션이니까 스크린샷 비교를 하지 마. 코드만 작성하고, 내가 직접 브라우저에서 확인할게." 이 한마디가 불필요한 루프 수십 회를 절약합니다.

■라 브랜드 에셋(색상, 로고, 사진)을 클론 위에 입히기

클론이 완성되면 참조 사이트의 색상과 레이아웃을 유지한 채로, 여러분의 브랜드 아이덴티티를 입힐 차례입니다.

3장에서 사용한 brand_assets 폴더에 로고와 브랜드 가이드라인이 들어 있습니다. 에이전트에게 말합니다. "이 클론에 우리 브랜드를 적용해줘. 로고는 @AIS.png이고, 가이드라인은 @brand-guidelines.png야." 에이전트는 참조 사이트의 색상을 여러분의 브랜드 색상으로 교체하고, 로고를 삽입하고, 서체를 변경합니다. 텍스트도 여러분의 사업에 맞게 재작성합니다.

프랑스어 사이트를 클론했다면 한국어로 번역까지 자동으로 이루어집니다. "전체를 한국어로 바꿔줘"라는 한 문장이면 됩니다.

클론과 커스터마이징으로 웹사이트의 전체적인 틀이 잡혔습니다. 그런데 히어로 섹션(Hero Section, 웹사이트 상단의 첫인상 영역)의 배경이 조금 밋밋하다면? 특정 버튼에 눈길을 끄는 효과를 넣고 싶다면? 전체 사이트를 다시 만들 필요 없이, 개별 컴포넌트 단위로 영감을 받아 교체할 수 있습니다.

13장 21st.dev 컴포넌트로 개별 요소 고도화

■가 21st.dev란 무엇인가: 고품질 웹 컴포넌트 라이브러리

인테리어를 할 때, 집 전체를 새로 짓지 않고도 분위기를 바꿀 수 있습니다. 거실 조명을 간접 조명으로 교체하거나, 현관문 손잡이를 황동으로 바꾸거나, 창가에 블라인드를 다는 것만으로 공간의 인상이 달라집니다. 웹사이트도 마찬가지입니다.

21st.dev는 고품질 웹 컴포넌트를 모아놓은 라이브러리입니다. 컴포넌트(Component)란 웹사이트를 구성하는 개별 부품을 말합니다. 버튼 하나, 배경 애니메이션 하나, 네비게이션 바 하나가 각각 하나의 컴포넌트입니다. 21st.dev에는 무지개 빛 테두리가 흐르는 버튼, 파도치는 배경 효과, 마우스 움직임에 반응하는 하이라이트, 셰이더(Shader) 배경 등 수백 가지 컴포넌트가 올라와 있습니다.

■나 전체 사이트가 아닌 개별 컴포넌트 단위로 영감 받기

21st.dev를 사용하는 핵심 전략은 전체 사이트를 이 라이브러리에서 가져오지 않는다는 것입니다. 전체 구조는 이미 클론이나 직접 구축으로 잡아놓았습니다. 21st.dev에서 가져오는 것은 특정 부분의 세련된 표현입니다.

예를 들어, 히어로 섹션의 배경이 단조롭다고 느낀다면, 21st.dev에서 "backgrounds" 카테고리를 탐색합니다. 물결치는 파란 그라데이션이 마음에 들면, 해당 컴포넌트의 프롬프트(21st.dev에서 제공하는 코드 조각)를 복사합니다.

■다 애니메이션 배경 등 특정 컴포넌트를 기존 사이트에 삽입하는 과정

복사한 프롬프트를 클로드 코드 채팅창에 붙여넣으면서 말합니다. "이 배경 요소를 히어로 텍스트 뒤에 넣어줘. 그리고 이건 애니메이션이니까 스크린샷 비교는 하지 마. 코드만 작성하고 내가 확인할게."

에이전트는 기존 웹사이트의 HTML 구조를 분석하고, 히어로 섹션의 배경 레이어에 21st.dev 컴포넌트의 코드를 삽입합니다. 로컬호스트에서 결과를 확인합니다. 배경 애니메이션이 텍스트를 가려서 읽기 어렵다면, "텍스트 뒤에 반투명 배경을 깔아줘"라고 피드백합니다. 버튼의 글로우 효과가 너무 산만하다면, "글로우를 좀 더 은은하게 줄여줘"라고 말합니다.

이 과정은 몇 분이면 끝납니다. 전체 사이트를 다시 만드는 것이 아니라, 레고 블록 하나를 교체하는 것이기 때문입니다.

개별 컴포넌트까지 다듬었으니, 이제 웹사이트의 영역을 넘어서 봅니다. 웹사이트는 정보를 보여주는 데 그치지만, 웹 앱(Web App)은 사용자와 상호작용합니다. 채팅 인터페이스를 통해 AI 피트니스 코치와 대화하고, 운동 기록이 게임처럼 레벨업되는 경험. 이런 동적인 애플리케이션도 클로드 코드로 구축할 수 있습니다.

14장 피트니스 코치 AI 웹 앱 라이브 빌드

■가 플랜 모드에서 기능 설계하기: 채팅 인터페이스, 게이미피케이션 트래커

토요일 아침, 운동을 하고 싶은데 오늘 뭘 해야 할지 모르겠습니다. 헬스장에 트레이너가 있으면 좋겠지만, 개인 트레이너 비용은 부담스럽습니다. 웹 브라우저를 열고 AI 피트니스 코치에게 물어봅니다. "30분짜리 고강도 인터벌 트레이닝을 짜줘." 코치가 워밍업부터 쿨다운까지 단계별 루틴을 제시합니다. 대화할 때마다 포인트가 쌓이고, 일정 포인트에 도달하면 레벨이 올라갑니다. 게임을 하는 것처럼 운동 습관이 붙습니다.

이 웹 앱을 처음부터 끝까지 클로드 코드로 구축합니다.

플랜 모드에서 시작합니다. 채팅창에 입력합니다.

"n8n에 피트니스 코치 워크플로우가 있어. 이걸 웹 앱으로 만들고 싶어. 메인 화면에 채팅 인터페이스가 있고, 오른쪽에 게이미피케이션 트래커가 있으면 좋겠어. 다크 모드, 미니멀한 디자인으로 해줘. 프런트엔드 디자인 스킬을 사용해서 전문적으로 만들어줘."

에이전트가 질문을 던집니다. "어떤 기능을 핵심으로 넣을까요? 일반 피트니스 Q&A, 맞춤형 운동 계획, 진행 상황 추적 중에서 선택해 주세요." "게이미피케이션은 메시지 횟수 기반으로 레벨업하면 될까요?" "사용자 데이터(레벨, 메시지 횟수)를 어디에 저장할까요?"

답변을 주고받으면서 사양이 확정됩니다.

■나 클로드 코드의 질문에 답하며 사양 확정하기

이 과정에서 여러분이 하는 일은 판단(Decision)입니다. 코딩이 아닙니다. "전부 다 넣어줘", "우선 메시지 횟수만으로 하자", "데이터 저장은 나중에 결정할게. 지금은 로컬 스토리지로 해줘." 이런 판단을 내려주면 에이전트가 나머지를 처리합니다.

모든 질문에 답하고 나면, 에이전트가 종합 계획서를 제시합니다. 앱 이름, 색상 체계, 기술 스택, 기능 목록, 구현 단계가 정리되어 있습니다. 계획이 마음에 들면 "좋아, 만들어줘"라고 말합니다.

■다 빌드, 스크린샷 검증, 수정의 반복 사이클

바이패스 퍼미션 모드로 전환합니다. 에이전트가 투두 리스트를 만들고, 항목을 하나씩 처리하기 시작합니다. HTML 구조를 작성하고, CSS로 스타일을 입히고, 자바스크립트(JavaScript)로 채팅 기능과 게이미피케이션 로직을 구현합니다. 프런트엔드 디자인 스킬이 자동으로 호출되어, 코드의 디자인 품질을 높입니다.

몇 분 뒤, 에이전트가 로컬호스트 주소를 알려줍니다. 브라우저에서 열어봅니다.

다크 모드 배경 위에 채팅 인터페이스가 나타납니다. 왼쪽에는 대화창이, 오른쪽에는 레벨과 포인트 현황이 표시됩니다. 메시지를 보내봅니다. "30분짜리 HIIT 루틴을 짜줘." 백엔드 워크플로우가 작동하고, 몇 초 뒤 코치의 응답이 돌아옵니다. 그런데 응답이 마크다운 형식의 볼드체와 글머리 기호가 그대로 노출되어 보기 좋지 않습니다.

클로드 코드로 돌아옵니다. "응답이 마크다운 형식으로 나와. 일반 텍스트로만 보이게 고쳐줘." 에이전트가 프런트엔드 코드를 수정합니다. 다시 확인합니다. 이번에는 깔끔합니다. 그런데 게이미피케이션 포인트가 올라가지 않습니다. "메시지를 보냈는데 포인트가 안 올라가. 고쳐줘." 에이전트가 로컬 스토리지 로직의 오류를 찾아 수정합니다.

이 빌드-확인-수정 사이클이 웹 앱 구축의 핵심 리듬입니다. 한 번에 완벽한 결과물이 나오지 않습니다. 그러나 매 사이클이 몇 분 단위로 돌아가기 때문에, 30분에서 한 시간 안에 상당히 완성도 높은 앱이 나옵니다.

■라 다섯 가지 AI 바이브 코딩 방지 해킹 팁

클로드 코드로 만든 웹사이트나 앱이 "AI가 만든 것 같다"는 인상을 주는 것을 바이브 코딩(Vibe Coding)이라는 속어로 부릅니다. 획일적인 레이아웃, 밋밋한 색상, 생기 없는 타이포그래피가 그 특징입니다. 이를 방지하는 다섯 가지 방법을 정리합니다.

claude.md에 디자인 원칙을 명시하는 것이 시작점입니다. "프런트엔드 디자인 스킬을 항상 먼저 호출하라. 예외 없다." 이 한 줄이 결과물의 디자인 품질을 끌어올립니다.

프런트엔드 디자인 스킬을 설치하면, 에이전트가 코드를 작성하기 전에 디자인 원칙을 읽고 적용합니다. 애니메이션, 여백, 색상 대비, 타이포그래피 위계가 전문 디자이너 수준으로 구현됩니다.

스크린샷 루프로 에이전트가 자기 결과물을 눈으로 확인하고 개선하게 합니다.

참조 사이트를 제공해서, "이런 느낌으로"라는 시각적 기준점을 줍니다.

21st.dev 같은 컴포넌트 라이브러리에서 개별 요소를 가져와 마무리합니다.

이 다섯 가지를 모두 적용하면, 같은 프롬프트로도 결과물의 품질이 체감될 정도로 달라집니다.

웹 앱이 로컬호스트에서 만족스럽게 작동합니다. 이제 이것을 세상에 내놓을 차례입니다. 여러분의 컴퓨터가 꺼져 있어도 누구나 접속할 수 있는 실제 웹 주소로 배포하는 과정, 그것이 다음 장의 주제입니다.

15장 GitHub과 Vercel로 실시간 배포

■가 GitHub 계정 생성과 클로드 코드 연동

지금까지 만든 모든 것, 랜딩 페이지든 피트니스 코치 앱이든, 여러분의 컴퓨터 안에만 존재합니다. 로컬호스트 주소는 여러분의 기기에서만 접속할 수 있습니다. 친구에게 이 주소를 보내면 빈 화면만 뜹니다.

웹사이트를 세상에 내놓으려면 코드를 클라우드에 올려야 합니다. 그 첫 번째 단계가 깃허브(GitHub)입니다.

깃허브는 코드를 저장하고 버전을 관리하는 플랫폼입니다. 구글 드라이브가 문서를 저장하듯, 깃허브는 코드를 저장합니다. 차이가 있다면, 깃허브는 모든 변경 이력을 추적합니다. 언제, 누가, 어떤 줄을 바꿨는지 기록됩니다. 잘못된 수정이 있으면 이전 버전으로 되돌릴 수 있습니다.

깃허브 계정 생성은 무료입니다. github.com에서 이메일과 비밀번호를 등록하면 됩니다. 계정을 만든 뒤, 설정(Settings) → 개발자 설정(Developer Settings) → 개인 접근 토큰(Personal Access Token)에서 토큰을 하나 생성합니다. 이 토큰이 클로드 코드가 여러분의 깃허브 계정에 코드를 올릴 수 있게 해주는 열쇠입니다.

토큰을 .env 파일에 저장합니다. 클로드 코드에게 "깃허브에 연결해줘"라고 말하면, 에이전트가 인증 과정을 안내합니다. 브라우저에서 깃허브 로그인 화면이 뜨고, 승인하면 연결이 완료됩니다.

■나 코드베이스를 GitHub 리포지토리에 푸시하기

연결이 완료되면, 에이전트에게 말합니다. "이 프로젝트를 깃허브에 올려줘. 리포지토리 이름은 fit-coach-ai-app으로 해줘."

에이전트가 깃허브에 새 리포지토리(Repository, 코드 저장소)를 만들고, 프로젝트의 모든 파일을 업로드합니다. 이 과정을 "푸시(Push)"라고 합니다.

(1) API 키 등 민감 정보를 커밋에서 제외하는 법

푸시하기 전에 반드시 확인해야 할 것이 있습니다. .env 파일이 .gitignore에 등록되어 있는지. API 키, OAuth 토큰, 비밀번호가 담긴 파일이 깃허브에 올라가면 누구나 볼 수 있습니다. 퍼블릭 리포지토리라면 전 세계 누구나, 프라이빗 리포지토리라도 권한이 있는 사람 모두가 접근할 수 있습니다.

에이전트에게 "푸시 전에 보안 점검을 해줘. 민감한 정보가 커밋에 포함되지 않는지 확인해"라고 요청하는 습관을 들이십시오. 에이전트가 코드를 스캔해서 API 키가 노출된 곳이 없는지 확인해 줍니다.

(2) 퍼블릭 vs 프라이빗 리포지토리 설정

리포지토리를 만들 때 공개(Public) 또는 비공개(Private)를 선택합니다. 학습 목적의 데모라면 공개로 해도 무방하지만, 클라이언트 프로젝트나 상업용 웹사이트라면 비공개를 권합니다. 비공개 리포지토리도 버셀과의 연동에는 아무 문제가 없습니다.

■다 Vercel 대시보드에서 리포지토리 임포트, 원클릭 배포

깃허브에 코드가 올라갔습니다. 이제 이 코드를 실제 웹사이트로 변환해 줄 서비스가 필요합니다. 그것이 버셀(Vercel)입니다.

버셀 계정을 만들 때, 깃허브 계정으로 로그인하면 연동이 자동으로 이루어집니다. 버셀 대시보드에서 "새 프로젝트 추가(Add New Project)"를 클릭하면, 여러분의 깃허브 리포지토리 목록이 나타납니다. 방금 만든 fit-coach-ai-app을 선택하고 "임포트(Import)"를 클릭합니다. 그리고 "배포(Deploy)"를 누릅니다.

몇 십 초 뒤, 버셀이 배포 완료 메시지를 보여줍니다. fit-coach-ai-app.vercel.app이라는 주소가 생성됩니다. 이 주소를 브라우저에 입력하면, 여러분이 로컬에서 만들던 피트니스 코치 앱이 세상에 공개된 상태로 작동합니다. 스마트폰에서도 접속할 수 있습니다.

환경변수(API 키 등)는 버셀 대시보드의 설정(Settings) → 환경변수(Environment Variables)에서 별도로 등록합니다. 깃허브에는 올리지 않았지만, 버셀이 코드를 실행할 때는 필요한 정보이기 때문입니다.

■라 라이브 업데이트 파이프라인: 코드 수정, 푸시, 자동 재배포

배포가 끝난 뒤에도 수정할 일은 생깁니다. 버튼 색을 바꾸고 싶다, 새 섹션을 추가하고 싶다, 오타를 발견했다. 이럴 때마다 버셀에 가서 다시 배포할 필요가 없습니다.

파이프라인은 이렇게 작동합니다. 클로드 코드에서 코드를 수정합니다. 로컬호스트에서 변경 사항을 확인합니다. 만족스러우면 "깃허브에 푸시해줘"라고 말합니다. 깃허브에 새 커밋이 올라갑니다. 버셀이 깃허브의 변경을 자동으로 감지하고, 20~30초 안에 실제 웹사이트에 반영합니다.

이 흐름을 정리하면: 클로드 코드(개발) → 로컬호스트(테스트) → 깃허브(저장) → 버셀(배포). 네 단계가 매끄럽게 연결됩니다.

주의할 점이 하나 있습니다. 로컬호스트에서 충분히 테스트하지 않은 변경 사항을 깃허브에 푸시하면, 결함이 있는 코드가 실제 웹사이트에 바로 반영됩니다. 클로드 코드에게 "로컬호스트에서 먼저 테스트하고, 내가 명시적으로 말하기 전까지는 깃허브에 푸시하지 마"라고 claude.md에 적어두는 것이 안전합니다. 배포 전 테스트의 원칙은 1장의 열차 궤도 비유와 같습니다. 다양한 시나리오로 배틀 테스트를 마친 뒤에 실전 운행에 들어가는 것입니다.

이것으로 제4부가 마무리됩니다. 참조 사이트를 클론하고, 컴포넌트를 고도화하고, AI 웹 앱을 구축하고, 세상에 배포하는 전체 과정을 밟았습니다. 웹사이트와 앱이 세상에 나왔으니, 에이전트의 손이 닿는 범위를 더 넓혀야 할 때입니다. 이메일을 보내고, 캘린더를 읽고, 구글 드라이브에서 파일을 가져오고, 웹에서 데이터를 긁어오는 능력. 에이전트에게 외부 서비스의 문을 열어주는 MCP 서버, 재사용 가능한 지침서인 스킬, 그리고 워크플로우를 클라우드에 올려 24시간 자동 실행하는 배포 기법. 이 모든 것이 제5부에서 펼쳐집니다.

16장 MCP(Model Context Protocol) 서버

■가 MCP의 개념: 에이전트에게 슈퍼마켓 접근권을 주는 프레임워크

케이크를 만드는 셰프에게 주방이 있고, 레시피가 있고, 칼과 오븐이 있습니다. 그런데 재료가 없습니다. 달걀, 밀가루, 설탕, 버터가 냉장고에 없으면 아무리 실력이 좋아도 케이크를 구울 수 없습니다. 셰프에게 슈퍼마켓 출입증을 주면 어떨까요. 필요한 재료가 있을 때마다 슈퍼마켓에 가서 직접 골라 옵니다. 달걀이 몇 개 필요한지, 밀가루는 어떤 브랜드인지, 셰프가 판단합니다.

MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)가 바로 그 슈퍼마켓 출입증입니다.

지금까지 클로드 코드 에이전트는 여러분의 컴퓨터 안에 있는 파일을 읽고 쓰는 빌트인 도구만 가지고 있었습니다. 강력하지만, 에이전트의 세계가 로컬 파일 시스템으로 제한되어 있었습니다. MCP 서버를 연결하면 이 경계가 사라집니다. 에이전트가 지메일(Gmail)에서 이메일을 읽고, 구글 캘린더에 일정을 잡고, 구글 드라이브에서 문서를 가져오고, 웹사이트에서 데이터를 긁어올 수 있습니다.

MCP를 이해하는 핵심은 "하나의 연결, 여러 기능"입니다. 지메일을 예로 들면, 이메일 보내기, 이메일 읽기, 이메일 검색, 라벨 붙이기, 초안 만들기 등 여러 동작이 있습니다. MCP 없이 이 기능들을 사용하려면 각 동작마다 별도의 API(Application Programming Interface, 소프트웨어 간의 통신 규약) 엔드포인트를 설정하고, 인증을 구성하고, 요청 형식을 맞춰야 합니다. MCP 서버를 연결하면, 에이전트가 이 모든 동작에 한꺼번에 접근합니다. 어떤 엔드포인트를 호출할지, 어떤 파라미터를 넣을지는 에이전트가 상황에 맞게 판단합니다.

슈퍼마켓 비유를 이어가면, 달걀 가게, 밀가루 가게, 설탕 가게를 따로 다닐 필요 없이, 슈퍼마켓 하나에서 모든 재료를 구하는 것입니다.

■나 FireCrawl MCP 서버 설치와 웹 스크래핑 실습

MCP 서버를 처음 연결하는 실습으로 파이어크롤(Firecrawl)을 사용합니다. 파이어크롤은 웹사이트의 데이터를 추출하는 서비스입니다. 스크래핑(페이지 내용 긁어오기), 크롤링(사이트 전체 탐색), 맵핑(사이트 구조 파악), 검색(웹 검색 후 결과 추출) 등 여러 도구를 하나의 MCP 서버로 제공합니다.

설치 과정은 놀라울 정도로 간단합니다. 파이어크롤의 공식 문서에서 클로드 코드용 설치 명령어를 복사합니다. 클로드 코드 채팅창에 붙여넣으면서 "이 MCP 서버를 설치해줘. API 키는 내가 .env에 넣을 테니 거기서 읽어"라고 말합니다. 에이전트가 설치를 처리합니다.

파이어크롤 웹사이트에서 무료 계정을 만들면 500크레딧이 제공됩니다. 대시보드에서 API 키를 복사해 .env 파일에 붙여넣고 저장합니다.

설치가 끝나면 바로 테스트할 수 있습니다. "이 URL의 내용을 마크다운으로 가져와줘"라고 말하면, 에이전트가 파이어크롤 MCP 서버의 스크래핑 도구를 호출해서 해당 페이지의 텍스트를 가져옵니다. 어떤 도구를 사용할지, 어떤 형식으로 요청할지는 에이전트가 자체적으로 결정합니다.

4부에서 다룬 웹사이트 클론에서도, 뉴스레터 자동화의 리서치 단계에서도, 이 MCP 서버가 데이터를 가져오는 역할을 합니다. 한번 연결해 두면 여러 워크플로우에서 재사용됩니다.

■다 Gmail, Calendar, Drive 등 서비스별 MCP 서버 연결

파이어크롤은 웹 데이터용 MCP 서버입니다. 구글 서비스에 접근하려면 별도의 MCP 서버가 필요합니다. 지메일 MCP 서버, 구글 캘린더 MCP 서버, 구글 드라이브 MCP 서버가 각각 존재합니다. 깃허브 MCP 서버도 있어서, 15장에서 다룬 코드 푸시를 에이전트가 직접 처리할 수 있습니다.

각 서비스의 MCP 서버를 연결하는 방식은 파이어크롤과 동일합니다. 공식 문서에서 설치 명령어를 가져오고, API 키나 인증 정보를 .env에 저장하고, 클로드 코드에게 설치를 지시합니다.

연결된 MCP 서버 정보는 프로젝트 루트의 MCP 설정 파일(mcp.json 등)에 기록됩니다. 이 파일에는 각 서버의 URL과 인증 정보가 담기므로, .gitignore에 등록해서 깃허브에 올라가지 않도록 해야 합니다. 15장에서 강조한 보안 원칙이 여기서도 적용됩니다.

■라 MCP 서버가 컨텍스트 윈도우에 미치는 토큰 비용

MCP 서버를 연결하면 편리하지만, 공짜는 아닙니다. 6장에서 다룬 컨텍스트 윈도우를 기억하십시오. 연결된 MCP 서버의 도구 목록과 설명이 컨텍스트 윈도우의 일부를 차지합니다. 서버 하나가 수십 개의 도구를 제공하면, 그 목록만으로도 수천 토큰이 소모됩니다. 서버를 세 개, 네 개 연결하면 시작하자마자 컨텍스트 윈도우의 상당 부분이 MCP 정보로 채워집니다.

실무적 조언은 이렇습니다. 현재 작업에 실제로 필요한 MCP 서버만 연결해 두십시오. 뉴스레터 자동화 프로젝트에서 깃허브 MCP 서버가 필요한 경우는 드뭅니다. 경쟁사 분석 프로젝트에서 구글 캘린더 MCP 서버는 불필요합니다. /context 명령어로 토큰 사용 현황을 확인하면, MCP 서버가 얼마나 토큰을 소비하고 있는지 항목별로 볼 수 있습니다. 사용하지 않는 서버가 토큰을 잡아먹고 있다면 해제하는 것이 현명합니다.

MCP 서버가 에이전트에게 외부 세계의 문을 열어준다면, 스킬은 에이전트에게 전문 지식을 불어넣는 방법입니다. 같은 일을 반복할 때마다 품질이 들쭉날쭉하다면, 그 작업을 스킬로 정리할 때입니다.

17장 스킬(Skills): 재사용 가능한 자연어 지침서

■가 스킬의 정체: 워크플로우와 동일한 구조, 다른 이름

신입 사원에게 매번 같은 설명을 반복하는 상황을 떠올려 보십시오. "보고서 표지는 이 서체로, 머리글에는 로고를 넣고, 페이지 번호는 하단 중앙에..."라고 세 번째 말하고 있다면, 그 내용을 문서로 정리할 때가 된 것입니다. 문서를 건네주면 다음부터는 설명이 필요 없습니다.

스킬(Skill)이 바로 그 문서입니다. 기술적으로 보면 스킬은 마크다운 파일입니다. 2장에서 배운 워크플로우와 구조가 같습니다. 목표, 입력, 단계, 출력, 예외 처리가 자연어로 기술되어 있습니다. 차이는 용도에 있습니다. 워크플로우가 "이번에 실행할 특정 작업의 절차"라면, 스킬은 "반복적으로 활용되는 전문 지식과 행동 규칙"입니다.

4부에서 사용한 프런트엔드 디자인 스킬이 좋은 예입니다. 이 스킬 파일에는 "모던한 웹사이트를 만들 때 따라야 할 디자인 원칙"이 담겨 있습니다. 색상 대비 규칙, 타이포그래피 위계, 여백 비율, 애니메이션 가이드라인. 에이전트는 웹사이트 관련 요청이 들어올 때마다 이 스킬을 읽고 적용합니다.

■나 글로벌 스킬 vs 프로젝트 스킬의 설치 위치

스킬의 설치 위치에 따라 적용 범위가 달라집니다.

글로벌 스킬은 여러분의 모든 클로드 코드 프로젝트에서 사용할 수 있습니다. 프런트엔드 디자인 스킬처럼 프로젝트를 가리지 않고 유용한 스킬이 여기에 해당합니다. 글로벌 스킬은 홈 디렉토리의 .claude 폴더 아래에 저장되므로, 특정 프로젝트의 파일 탐색기에서는 보이지 않을 수 있습니다.

프로젝트 스킬은 해당 프로젝트 안의 .claude/skills 폴더에 저장됩니다. 그 프로젝트에서만 사용됩니다. 뉴스레터 인포그래픽 생성 스킬처럼 특정 프로젝트에만 의미 있는 스킬이 여기에 해당합니다.

스킬 설치는 대부분 명령어 한 줄이면 됩니다. 커뮤니티에서 공유되는 스킬의 설치 명령어를 클로드 코드 채팅창에 붙여넣으면 에이전트가 처리합니다. 직접 설치하기 귀찮으면 "이걸 설치해줘"라고 말하면 됩니다.

■다 에이전트가 작업에 맞는 스킬을 동적으로 로드하는 메커니즘

스킬의 작동 방식에서 가장 중요한 특성은 동적 로딩(Dynamic Loading)입니다. 에이전트가 모든 스킬을 항상 읽고 있는 것이 아닙니다. 요청이 들어오면, 에이전트는 사용 가능한 스킬 목록을 훑어봅니다. 현재 요청과 관련된 스킬이 있으면 그때 읽어서 적용합니다. 관련 없는 스킬은 무시합니다.

이것이 중요한 이유는 토큰 절약 때문입니다. 스킬을 claude.md에 직접 넣으면 매 대화마다 그 내용이 컨텍스트 윈도우를 차지합니다. 스킬로 분리해 두면, 필요할 때만 로드되므로 평소에는 토큰을 소비하지 않습니다.

이것이 5장에서 다룬 라우팅 전략의 연장선입니다. claude.md에 같은 유형의 지침을 반복해서 추가하고 있다면, 그것을 스킬로 분리하라는 신호입니다.

■라 스킬과 MCP의 차이점: 지침서인가, 외부 도구 연결인가

MCP와 스킬은 모두 에이전트의 능력을 확장하지만, 확장하는 방향이 다릅니다.

MCP는 에이전트에게 행동 수단을 줍니다. 지메일에서 이메일을 읽는 능력, 파이어크롤로 웹사이트를 긁어오는 능력. 새로운 도구를 손에 쥐어주는 것입니다.

스킬은 에이전트에게 판단 기준을 줍니다. "웹사이트를 만들 때 이런 디자인 원칙을 따르라", "인포그래픽을 만들 때 이 브랜드 색상을 사용하라". 무엇을 해야 하는지가 아니라, 어떻게 해야 하는지를 알려주는 것입니다.

비유하면, MCP는 셰프에게 새 칼을 주는 것이고, 스킬은 새 레시피를 주는 것입니다. 둘 다 필요하지만, 역할이 다릅니다.

에이전트가 외부 서비스에 접근하고(MCP), 전문 지식을 갖추었으니(스킬), 이제 이 능력을 실전에 투입할 차례입니다. 구글 워크스페이스의 모든 서비스를 하나의 인터페이스로 다루는 도구가 있습니다.

18장 구글 워크스페이스 CLI(GWS CLI)

■가 GWS CLI란: Gmail, Drive, Docs, Sheets, Calendar을 하나의 인터페이스로

월요일 아침. 지메일에서 읽지 않은 이메일 30통을 확인하고, 구글 캘린더에서 오늘의 일정을 점검하고, 구글 드라이브에서 회의 자료를 찾고, 구글 독스에서 보고서를 작성해야 합니다. 네 개의 탭을 번갈아 열면서 한 시간이 지나갑니다. 이 네 개의 서비스를 하나의 명령어 체계로 묶을 수 있다면 어떨까요.

GWS CLI(Google Workspace Command Line Interface, 구글 워크스페이스 명령줄 인터페이스)가 바로 그 도구입니다. 구글이 오픈 소스로 공개한 이 CLI는 지메일, 드라이브, 독스, 시트(Sheets), 슬라이드(Slides), 캘린더를 하나의 인터페이스에서 조작할 수 있게 해줍니다.

(1) 100가지 이상의 프리빌트 레시피

GWS CLI에는 "레시피(Recipe)"라고 부르는 프리빌트 워크플로우가 100가지 이상 내장되어 있습니다. 시트 데이터를 읽어서 보고서 독스를 만드는 레시피, 빈 시간대를 찾아 회의를 잡는 레시피, 이메일을 라벨별로 분류하고 아카이브하는 레시피, 템플릿에서 문서를 생성하는 레시피. 이 레시피들은 스킬과 비슷한 역할을 합니다. 에이전트가 구글 서비스를 다룰 때 참조할 수 있는 패턴 라이브러리입니다.

(2) JSON 기반 구조화 응답으로 에이전트 친화적

GWS CLI의 응답은 JSON(JavaScript Object Notation, 데이터 교환 형식) 기반으로 구조화되어 있습니다. AI 에이전트가 텍스트를 파싱(Parsing, 구조 분석)하기 쉬운 형태라는 뜻입니다. 일반 텍스트로 "이메일이 3통 있습니다. 첫 번째는..."이라고 오는 대신, 각 이메일의 제목, 발신자, 날짜, 내용이 명확한 필드로 구분되어 옵니다. 에이전트가 이 데이터를 바로 처리할 수 있어서 정확도가 높아집니다.

■나 설치 과정: 구글 클라우드 콘솔 프로젝트 생성과 OAuth 설정

GWS CLI 설치는 MCP 서버보다 한 단계 더 복잡합니다. 구글 클라우드 콘솔에서 프로젝트를 만들고, OAuth(Open Authorization, 개방형 인증) 동의 화면을 설정하고, 클라이언트 ID를 생성해야 합니다.

복잡하게 들리지만, 실제로는 클로드 코드에게 GWS CLI의 깃허브 주소를 주고 "이걸 설치해줘"라고 말하면, 에이전트가 문서를 읽고 단계별로 안내해 줍니다. 여러분이 직접 해야 하는 부분은 구글 클라우드 콘솔에서 버튼을 클릭하는 것과, 생성된 인증 파일을 지정된 폴더에 넣는 것 정도입니다.

설치가 완료되면 인증을 확인합니다. 브라우저에 구글 로그인 화면이 뜨고, 접근 권한을 승인하면 연결이 완료됩니다. 이후에는 클로드 코드에서 구글 서비스에 자유롭게 접근할 수 있습니다.

한 가지 알아둘 점이 있습니다. 이 책을 집필하는 시점에서 GWS CLI는 공식 지원 제품이 아닌 오픈 소스 베타 상태입니다. 안정성은 높지만, 버전 업데이트에 따라 일부 기능이 변경될 수 있습니다. 구글 워크스페이스가 새 API 엔드포인트를 추가하면 GWS CLI가 자동으로 반영하므로, 도구 자체는 계속 최신 상태를 유지합니다.

■다 Gmail 이메일 우선순위 자동 분류 실습

GWS CLI가 연결된 상태에서 실전 활용을 해보겠습니다.

클로드 코드에게 말합니다. "오늘 읽지 않은 이메일을 가져와서, 내 사업 우선순위에 따라 1점부터 10점까지 점수를 매겨줘. 5점 미만인 이메일은 자동으로 읽음 처리해줘."

에이전트는 GWS CLI를 통해 지메일에서 미읽 이메일 목록을 가져옵니다. 그리고 claude.md에 기록된 사업 맥락, 현재 프로젝트 정보, 팀 우선순위를 참고해서 각 이메일에 점수를 매깁니다. 광고 메일이나 뉴스레터 구독은 낮은 점수를, 핵심 클라이언트의 메일이나 긴급한 내부 요청은 높은 점수를 받습니다. 5점 미만 이메일은 자동으로 읽음 처리됩니다.

결과를 확인합니다. 30통의 이메일이 우선순위 순으로 정렬되어 있습니다. 상위 5통만 직접 읽으면 아침 이메일 정리가 끝납니다. 이전에는 30통을 하나하나 열어보며 20분을 쓰던 작업이, 에이전트의 판단으로 5분 안에 마무리됩니다.

■라 구글 슬라이드를 마크다운이 아닌 실제 포맷으로 생성하는 법

API를 통해 구글 독스나 슬라이드를 만들면, 흔히 마크다운 텍스트가 그대로 출력되는 문제가 발생합니다. 서체, 색상, 레이아웃이 적용되지 않은 날것의 텍스트입니다.

GWS CLI는 이 문제를 해결합니다. CLI가 구글 슬라이드의 네이티브 포맷을 직접 조작하기 때문에, 에이전트가 만든 프레젠테이션에 실제 서체, 색상, 이미지가 적용됩니다. 브랜드 가이드라인에서 추출한 색상 코드가 슬라이드 배경과 텍스트에 반영되고, 로고가 지정된 위치에 삽입됩니다.

여기에 4부에서 배운 스크린샷 루프를 결합하면, 에이전트가 슬라이드를 만든 뒤 실제 화면을 캡처해서 레이아웃을 검증하고 수정하는 순환이 가능합니다. 크롬 개발자 도구를 열어 슬라이드를 스크린샷 찍고, 여백이 어긋난 곳이나 텍스트가 잘린 곳을 발견하면 코드를 수정합니다.

■마 유튜브 리소스 가이드 자동 생성 데모

GWS CLI의 활용을 보여주는 또 다른 사례입니다. 유튜브 영상의 URL을 클로드 코드에 넣고, "이 영상의 리소스 가이드를 구글 독스로 만들어줘"라고 요청합니다.

에이전트는 영상의 트랜스크립트(자막/전사문)를 다운로드합니다. 핵심 내용을 추출하고, 리소스 가이드 형식으로 구성합니다. 그리고 GWS CLI의 배시(Bash) 명령어를 사용해 구글 독스를 생성합니다. API 호출이 아니라 터미널 명령어로 구글 서비스와 직접 소통하는 것입니다.

결과물은 실제 구글 독스입니다. 상단에 헤더 이미지가 삽입되고, 유튜브 채널 링크가 포함되고, 영상의 주요 주제별로 섹션이 나뉘어 있습니다. 하단에는 행동 촉구 문구와 커뮤니티 링크가 배치됩니다. 마크다운 원본이 아닌, 서식이 적용된 완성된 문서입니다.

외부 서비스와 연결하는 방법(MCP), 전문 지식을 캡슐화하는 방법(스킬), 구글 워크스페이스 전체를 하나로 다루는 방법(GWS CLI)까지 살펴보았습니다. 이 모든 역량을 갖춘 워크플로우가 여러분의 컴퓨터 안에서만 돌아가고 있다면 아쉬운 일입니다. 매주 월요일 아침 자동으로 실행되게 하려면, 워크플로우를 클라우드에 올려야 합니다.

19장 워크플로우를 클라우드에 배포하기

■가 배포의 원칙: 에이전트가 아니라 워크플로우와 도구를 올린다

1장에서 강조한 원칙을 다시 짚겠습니다. 배포할 때 클라우드에 올라가는 것은 에이전트가 아닙니다. 워크플로우(W)와 도구(T)만 올라갑니다. 에이전트(A)는 여러분의 로컬 환경에 남습니다.

이것은 의도적인 설계입니다. 클라우드에서 자동으로 실행되는 코드는 예측 가능해야 합니다. 같은 입력이 들어오면 같은 출력이 나와야 합니다. 에이전트의 추론 능력은 구축 단계에서 빛을 발하지만, 배포 이후에는 그 추론의 결과물인 코드가 결정론적으로 실행되는 것이 안전합니다.

배포 후에도 워크플로우를 개선하고 싶으면, 로컬의 클로드 코드에서 수정하고, 테스트하고, 다시 배포합니다. 이 사이클을 반복하면서 워크플로우는 점점 견고해집니다.

■나 Modal 배포

(1) Modal이란: 실행할 때만 과금되는 AI 인프라

모달(Modal)은 서버리스(Serverless) AI 인프라 서비스입니다. "서버리스"라는 말이 혼란스러울 수 있는데, 서버가 없다는 뜻이 아니라, 서버 관리를 여러분이 하지 않아도 된다는 뜻입니다. 코드를 올려두면 모달이 필요할 때만 서버를 켜서 실행하고, 실행이 끝나면 꺼줍니다. 과금은 실행 시간 기준이므로, 코드가 돌아가지 않는 시간에는 비용이 발생하지 않습니다.

계정을 만들면 5달러(한화 약 6,800원)의 무료 크레딧이 제공되고, 신용카드를 등록하면 30달러(한화 약 41,000원)로 늘어납니다. 주 1회 실행되는 뉴스레터 워크플로우라면 이 크레딧으로 상당 기간 운영할 수 있습니다.

(2) 클로드 코드에 "이 워크플로우를 Modal에 푸시하라"고 지시하기

배포 과정은 클로드 코드에게 자연어로 지시하는 것으로 시작합니다. "이 유튜브 분석 워크플로우를 모달에 올려서 매주 월요일 오전 6시에 자동 실행되게 해줘."

에이전트가 계획을 세웁니다. 워크플로우와 도구 스크립트를 모달 배포 파일로 패키징하고, 크론(Cron) 스케줄을 설정하고, 환경변수(API 키 등)를 모달 시크릿(Secret)으로 등록합니다. 계획을 확인하고 승인하면, 에이전트가 실행합니다.

(3) 보안 리뷰: 배포 전 민감 키 처리 점검

배포 전에 반드시 보안 점검을 합니다. "보안 리뷰를 해줘. API 키가 노출되지 않는지, 웹훅에 인증이 걸려 있는지 확인해"라고 에이전트에게 요청합니다. 에이전트가 코드를 스캔해서 잠재적 취약점을 보고합니다.

API 키가 코드 안에 하드코딩되어 있으면 경고합니다. 모달 시크릿으로 이동해야 한다고 알려줍니다. 웹훅 엔드포인트가 인증 없이 열려 있으면, 누구나 요청을 보낼 수 있다고 지적합니다.

(4) 크론 스케줄 설정과 즉시 실행 테스트

모달 대시보드에서 배포된 앱을 확인합니다. 스케줄 탭에서 "매주 월요일 오전 6시"로 설정된 크론을 볼 수 있습니다. 즉시 실행 버튼으로 테스트할 수 있습니다. 실행 결과와 로그를 대시보드에서 실시간으로 확인합니다.

테스트 실행에서 오류가 발생하면, 오류 로그를 복사해서 클로드 코드에 붙여넣습니다. "모달에서 이 오류가 났어. 원인을 찾아줘." 에이전트가 원인을 진단하고, 코드를 수정하고, 다시 배포합니다.

■다 Trigger.dev 배포

(1) Modal과의 차이: 스케줄, 웹훅, 대시보드, 로그의 장점

트리거닷데브(Trigger.dev)는 모달과 유사한 역할을 하지만, 워크플로우 자동화에 좀 더 특화된 서비스입니다. 스케줄 실행(크론), 웹훅 트리거, 자동 재시도, 큐잉(대기열 관리), 오케스트레이션(복수 태스크 조율)을 기본 제공합니다. 대시보드에서 각 실행의 단계별 진행 상황, 소요 시간, 성공/실패 여부를 시각적으로 확인할 수 있습니다.

모달이 범용 AI 인프라라면, 트리거닷데브는 워크플로우 운영에 맞춤화된 환경입니다. 실패한 실행이 자동으로 재시도되고, 지연(Delay)을 두고 재시도 간격을 조절할 수 있어서, 워크플로우 운영의 안정성이 높습니다.

(2) claude.md에 Trigger.dev 참조 파일을 연결하는 구성

트리거닷데브로 배포하려면, 에이전트가 타입스크립트(TypeScript) 파일을 작성해야 합니다. claude.md에 트리거닷데브의 API 참조 파일(trigger-ref.md)을 라우팅해 두면, 에이전트가 배포 코드를 작성할 때 이 문서를 참고합니다.

배포 파이프라인은 4부에서 배운 깃허브-버셀 흐름과 비슷합니다. 클로드 코드에서 코드를 작성하고, 깃허브에 푸시하면, 트리거닷데브가 깃허브의 변경을 자동으로 감지해서 프로덕션 환경에 반영합니다.

(3) 웹훅 트리거와 스케줄 트리거 비교

스케줄 트리거는 "매주 월요일 오전 8시"처럼 정해진 시간에 실행됩니다. 뉴스레터 발송, 정기 보고서 생성, 주간 경쟁사 분석 같은 반복 작업에 적합합니다.

웹훅 트리거는 외부 이벤트에 반응해서 실행됩니다. 웹사이트의 문의 양식이 제출되었을 때, 클릭업(ClickUp)에 새 태스크가 추가되었을 때, 고객이 결제를 완료했을 때. 이런 이벤트가 웹훅 URL로 신호를 보내면, 트리거닷데브가 해당 워크플로우를 즉시 실행합니다.

실무에서는 두 유형을 조합하는 경우가 많습니다. 고객 문의가 들어오면(웹훅 트리거) 즉시 분석하고, 매일 저녁(스케줄 트리거) 당일 문의 현황을 종합 보고서로 생성하는 식입니다.

■라 배포 후 워크플로우 업데이트 사이클

배포는 끝이 아니라 새로운 시작입니다. 워크플로우가 클라우드에서 실행되면서 예상치 못한 데이터를 만나거나, 외부 API의 응답 형식이 변경되거나, 새로운 요구사항이 추가될 수 있습니다.

업데이트 사이클은 이렇습니다. 클라우드에서 실행된 결과를 확인합니다(모달이나 트리거닷데브 대시보드의 로그). 문제가 발견되면 로컬의 클로드 코드에서 워크플로우나 도구를 수정합니다. 로컬에서 테스트합니다. 만족스러우면 깃허브에 푸시하고, 클라우드 환경이 자동으로 업데이트합니다.

이 사이클의 핵심은, 에이전트의 자기치유 능력은 로컬 구축 단계에서만 작동한다는 점입니다. 클라우드에 배포된 코드는 스스로 고치지 않습니다. 오류가 나면 로그를 남기고 멈춥니다. 그래서 배포 전의 배틀 테스트가 중요합니다. 1장에서 다룬 열차 궤도 비유를 기억하십시오. 다양한 열차로 시험 운행을 마친 뒤에 실전 운행에 들어가는 것입니다.

이것으로 제5부가 마무리됩니다. MCP 서버로 에이전트의 손이 외부 서비스에 닿게 했고, 스킬로 전문 지식을 캡슐화했고, GWS CLI로 구글 워크스페이스 전체를 하나로 엮었으며, 모달과 트리거닷데브로 워크플로우를 클라우드에 배포해 24시간 자동 실행되게 했습니다.

제6부에서는 이 모든 역량을 하나의 프로젝트에 집결시킵니다. AI 이그제큐티브 어시스턴트. 매일 아침 여러분의 일정을 정리하고, 이메일 우선순위를 매기고, 팀 현황을 브리핑하고, 프로젝트의 다음 행동을 제안하는 에이전트. 네 단계의 구축 프레임워크를 따라가며, 집을 짓고, 생명을 불어넣고, 손을 달아주고, 성장하게 하는 여정이 시작됩니다.

20장 네 단계 구축 프레임워크

■가 1단계, 집(Home): VS Code 설정, 폴더 생성, claude.md 작성

화요일 오전 9시 15분. 이메일 수신함에 읽지 않은 메일이 47통 쌓여 있습니다. 캘린더에는 오전 회의 두 개와 오후 통화 한 건이 잡혀 있고, 클릭업(ClickUp)에는 이번 주 마감인 태스크가 일곱 개 남아 있습니다. 슬랙(Slack) 알림은 세 채널에서 동시에 깜빡이고 있습니다. 어느 것부터 손을 대야 할지 몇 초간 멈칫합니다. 결정 피로(Decision Fatigue)가 하루의 가장 생산적인 시간을 잡아먹는 순간입니다.

이 장부터 세 장에 걸쳐, 이 결정 피로를 끝내줄 AI 이그제큐티브 어시스턴트를 구축합니다. 매일 아침 캘린더와 태스크를 종합해서 하루 계획을 세워주고, 이메일 우선순위를 매기고, 팀의 프로젝트 현황을 브리핑하고, 리서치를 수행하고, 콘텐츠를 생성하는 에이전트입니다. 네 개의 에이전트를 동시에 병렬로 돌려서, 25분짜리 작업을 2분 안에 끝낼 수 있습니다.

구축은 네 단계로 이루어집니다. 집(Home), 생명(Life), 손(Hands), 성장(Growth). 이 비유를 따라가면 전체 과정이 자연스럽게 이어집니다.

첫 번째 단계는 집을 짓는 것입니다. 에이전트가 거주할 물리적 공간을 마련합니다.

VS Code를 열고, 새 폴더를 만듭니다. "EA-project" 같은 이름이면 됩니다. 이 폴더를 VS Code에서 열면 왼쪽 탐색기에 빈 공간이 나타납니다. 오른쪽에 클로드 코드 채팅창을 엽니다.

에이전트에게 말합니다. "이 폴더는 네가 나의 이그제큐티브 어시스턴트로 일하는 공간이야. 기본적인 폴더 구조를 잡아줘."

에이전트가 폴더를 생성합니다. .claude(설정, 규칙, 스킬, 에이전트 파일), context(나에 관한 정보, 업무 맥락, 팀 정보, 현재 우선순위), projects(진행 중인 프로젝트별 서브폴더), decisions(중요 결정 로그), archives(과거 결과물 아카이브), references(참조 문서와 SOP), templates(반복 사용하는 양식).

claude.md 파일을 작성합니다. 처음에는 한 문단이면 충분합니다. "너는 [이름]의 이그제큐티브 어시스턴트다. 일정 관리, 태스크 정리, 리서치, 커뮤니케이션 초안 작성을 돕는다." 이 파일은 프로젝트 내내 진화할 것이므로, 완벽하게 만들려 하지 않아도 됩니다.

집이 지어졌습니다. 빈 방에 가구가 없는 상태입니다. 다음 단계에서 생명을 불어넣습니다.

■나 2단계, 생명(Life): 비즈니스 컨텍스트를 불어넣기

집에 입주한 어시스턴트에게 가장 먼저 해야 할 일은 온보딩입니다. 5장에서 신입 사원의 첫 출근에 비유했던 것을 기억하십시오. 온보딩 문서 없이 출근한 사원은 매번 물어봐야 합니다. 에이전트도 마찬가지입니다.

(1) 팀 정보, 우선순위, OKR, 프로젝트 현황

에이전트에게 여러분의 비즈니스 맥락을 전달하는 가장 효과적인 방법은 인터뷰입니다. 에이전트에게 말합니다. "나에 대해, 우리 사업에 대해, 팀에 대해, 현재 우선순위에 대해 알아야 할 것들을 물어봐. 질문을 하나씩 해줘."

에이전트가 질문을 시작합니다. "이름과 역할은 무엇인가요?" "사업의 핵심 서비스는 무엇인가요?" "팀원은 몇 명이고, 각자 어떤 역할을 맡고 있나요?" "이번 분기의 최우선 목표는 무엇인가요?" "현재 진행 중인 프로젝트를 알려주세요."

답변할 때 완벽하게 정리된 문장을 쓸 필요가 없습니다. 음성 입력으로 브레인 덤프(Brain Dump)를 해도 됩니다. 에이전트가 여러분의 말을 정리해서 구조화된 파일로 저장합니다.

인터뷰가 끝나면 에이전트가 context 폴더에 파일을 만듭니다. me.md(여러분에 관한 정보), work.md(사업 개요), team.md(팀 구성과 역할), current-priorities.md(현재 우선순위), goals.md(분기별 목표). 각 파일에는 인터뷰에서 추출된 정보가 마크다운 형식으로 정리됩니다.

그리고 claude.md가 업데이트됩니다. 5장에서 배운 라우팅이 적용됩니다. "나에 대해 알아야 할 때는 /context/me.md를 읽어라. 사업 정보는 /context/work.md, 팀 정보는 /context/team.md를 참조하라." 이렇게 하면 claude.md는 짧게 유지되면서도 에이전트가 필요한 정보에 접근할 수 있습니다.

(2) GitHub 연동으로 코드 관리 자동화

집과 생명이 갖춰진 프로젝트를 깃허브에 올려두면 여러 가지 이점이 있습니다. 백업이 자동으로 이루어지고, 어떤 기기에서든 이 프로젝트를 불러와 어시스턴트를 사용할 수 있습니다. 변경 이력이 남아서, 어시스턴트의 설정이 잘못되었을 때 이전 버전으로 되돌릴 수 있습니다.

15장에서 배운 깃허브 연동 과정과 같습니다. "이 프로젝트를 깃허브에 올려줘"라고 말하면 에이전트가 처리합니다. .env 파일이 .gitignore에 등록되어 있는지 꼭 확인하십시오.

■다 3단계, 손(Hands): 스킬을 만들어 실제 작업을 수행하게 하기

집이 있고, 맥락을 이해했지만, 아직 에이전트는 아무것도 "하지" 못합니다. 질문에 답하고 조언을 줄 수는 있지만, 직접 이메일을 보내거나, 캘린더를 확인하거나, 리서치를 수행하려면 손이 필요합니다. 이 손이 스킬입니다.

이그제큐티브 어시스턴트에게 가장 먼저 달아줄 손은 프로젝트 관리 도구(클릭업, 노션, 아사나 등)와의 연결입니다. MCP 서버나 API를 통해 연결하면, 에이전트가 태스크를 읽고, 상태를 확인하고, 우선순위를 판단할 수 있습니다.

그 다음은 리서치 스킬입니다. 퍼플렉시티 API를 연동한 리서치 스킬을 만들면, 에이전트가 웹에서 정보를 검색하고, 여러분의 사업 맥락에 맞게 종합해서 보고서를 작성합니다. 단순 웹 검색이 아니라, me.md와 work.md에 담긴 사업 정보를 참조해서 "우리 사업에 이것이 어떤 의미인지"까지 분석하는 깊이 있는 리서치입니다.

스킬을 만드는 과정은 17장에서 배운 것과 같습니다. 플랜 모드에서 "리서치 스킬을 만들어줘. 퍼플렉시티를 사용하고, 내 사업 맥락을 반영해서 보고서를 작성하게 해줘"라고 요청하면, 에이전트가 스킬 파일을 생성하고 테스트합니다.

■라 4단계, 성장(Growth): 피드백과 반복으로 어시스턴트가 진화하는 구조

집이 있고, 맥락을 이해하고, 손이 달렸습니다. 네 번째 단계는 이 모든 것이 시간이 지나면서 더 나아지게 하는 것입니다.

성장의 핵심은 사용입니다. 이 어시스턴트를 매일 사용하십시오. 기존에 클로드 웹이나 ChatGPT에서 하던 작업을 여기서 하십시오. 커스텀 GPT의 프롬프트를 가져와서 스킬로 변환하십시오. 매번 에이전트의 결과물에 피드백을 주십시오. "이 부분은 좋았어", "이건 내 스타일이 아니야, 더 간결하게 해줘", "이 정보를 claude.md에 추가해줘."

일주일만 집중적으로 사용해도, 프로젝트 안에 리서치 보고서, 콘텐츠 초안, 의사결정 로그, 프로젝트 노트가 쌓입니다. 에이전트는 이 파일들을 참조할 수 있으므로, 사용할수록 맥락이 풍부해지고, 결과물의 품질이 올라갑니다. 한 달 뒤에는 지금과 전혀 다른 수준의 어시스턴트가 되어 있을 것입니다.

네 단계 프레임워크의 밑그림이 잡혔습니다. 다음 장에서는 두 번째 단계인 "생명"의 핵심, claude.md 컨텍스트 관리를 심화합니다. claude.md가 100줄이 넘기 시작하면 어떻게 해야 하는지, 같은 말을 반복하고 있다면 무엇을 해야 하는지.

21장 claude.md 컨텍스트 관리 심화

■가 비즈니스 전체 맥락을 어떻게 구조화하는가

이그제큐티브 어시스턴트의 claude.md는 다른 프로젝트의 claude.md보다 복잡합니다. 뉴스레터 프로젝트의 claude.md는 "뉴스레터를 만드는 방법"만 알면 됩니다. 어시스턴트의 claude.md는 여러분의 사업 전체를 이해해야 합니다. 이름, 역할, 팀, 프로젝트, 우선순위, 커뮤니케이션 스타일, 사용하는 도구, 의사결정 이력. 이 모든 것을 한 파일에 넣으면 수백 줄이 되고, 매 대화마다 소비되는 토큰이 폭증합니다.

해법은 5장에서 배운 라우팅입니다. claude.md를 목차로 만들고, 실제 내용은 별도 파일에 둡니다.

미국의 한 AI 자동화 컨설턴트의 이그제큐티브 어시스턴트 프로젝트에서 claude.md는 약 90줄입니다. 그 안에 담긴 실제 정보는 최소한입니다. 어시스턴트의 역할 한 줄("너는 [이름]의 이그제큐티브 어시스턴트다. 직접적이고, 간결하고, 캐주얼하게."), 현재 최우선 과제 한 줄("유튜브 채널 성장이 1순위. 나머지는 이를 지원한다."), 긴급 사안 한 줄("이번 주 금요일까지 클라이언트 제안서 완성."). 나머지는 전부 라우팅입니다. "나에 대해 알아야 하면 /context/me.md", "사업 정보는 /context/work.md", "팀은 /context/team.md", "현재 우선순위는 /context/current-priorities.md".

■나 claude.md가 길어질 때 분리 파일로 라우팅하기

시간이 지나면 claude.md에 새로운 항목이 추가됩니다. 새 MCP 서버를 연결했다면 그 정보가 들어가고, 새 스킬을 만들었다면 스킬 목록이 업데이트되고, 새 프로젝트가 시작되면 프로젝트 참조 경로가 추가됩니다.

150줄을 넘어가기 시작하면 경고등이 켜집니다. 200줄을 넘으면 적극적으로 분리 작업을 해야 합니다.

분리의 원칙은 간단합니다. claude.md에서 "카테고리"로 묶을 수 있는 정보 블록을 찾습니다. 그 블록을 별도 파일로 옮깁니다. claude.md에는 한 줄짜리 참조 경로만 남깁니다.

예를 들어 claude.md에 커뮤니케이션 스타일에 관한 규칙이 열다섯 줄 있다면, /rules/communication-style.md 파일을 만들어 옮기고, claude.md에는 "커뮤니케이션 규칙은 /rules/communication-style.md 참조"라고만 적습니다.

■다 같은 말을 반복하고 있다면 스킬로 분리하라는 신호

라우팅으로 해결되지 않는 경우가 있습니다. 같은 유형의 지시를 여러 대화에서 반복하고 있다면, 그것은 스킬로 분리해야 한다는 신호입니다.

"리서치할 때는 항상 퍼플렉시티를 사용하고, 출처를 반드시 포함하고, 우리 사업과의 관련성을 분석해줘"라는 말을 세 번째 하고 있다면, 이 지시를 리서치 스킬의 skill.md 안에 넣어야 합니다. 그러면 다음부터 "리서치해줘"라는 한마디면 에이전트가 스킬을 읽고 모든 규칙을 자동으로 적용합니다.

라우팅은 정보를 정리하는 방법이고, 스킬은 행동을 정리하는 방법입니다. 정보가 반복되면 라우팅으로, 행동이 반복되면 스킬로. 이 두 가지 도구를 적재적소에 사용하면 claude.md는 짧고 효율적으로 유지되면서, 에이전트의 능력은 계속 확장됩니다.

claude.md를 다듬는 방법을 알았으니, 이제 실제로 작동하는 스킬을 만들 차례입니다. 이그제큐티브 어시스턴트가 매일 아침 여러분의 하루를 계획해주는 "모닝커피 스킬"부터 시작합니다.

22장 실전 스킬 빌드

■가 모닝커피 스킬: 매일 아침 업무를 계획하는 루틴

수요일 아침 6시. 알람이 울리기 전에 에이전트가 이미 일을 시작했습니다. 캘린더를 확인하고, 클릭업에서 이번 주 태스크 현황을 가져오고, 팀원의 진행 상황을 점검합니다. 여러분이 커피를 내리는 동안, 에이전트가 오늘의 계획안을 정리해 놓습니다.

이것이 모닝커피 스킬입니다.

(1) 캘린더, 비디오 파이프라인, 팀 상태를 종합하는 로직

모닝커피 스킬의 skill.md에는 이런 단계가 기술되어 있습니다.

에이전트는 먼저 구글 캘린더(GWS CLI 또는 캘린더 MCP를 통해)에서 오늘의 일정을 가져옵니다. 회의 시간, 참석자, 안건을 파악합니다. 다음으로 프로젝트 관리 도구에서 이번 주 마감 태스크, 지연된 태스크, 새로 배정된 태스크를 읽어옵니다. context 폴더의 current-priorities.md를 참조해서 현재 최우선 과제가 무엇인지 확인합니다.

이 모든 정보를 종합해서, 오늘 해야 할 일의 우선순위를 매기고, 시간 블록 단위로 일정을 제안합니다. "9시~10시: 클라이언트 제안서 마무리(최우선 과제). 10시~10시 30분: 팀 스탠드업 미팅. 10시 30분~12시: 유튜브 영상 스크립트 작성."

여러분이 "좋아"라고 한마디 하면, 에이전트가 캘린더에 이 블록들을 등록합니다. 결정 피로가 사라집니다.

(2) 펄스체크 스킬과의 차이: 깊이의 수준

모닝커피 스킬이 하루의 계획을 세우는 가벼운 브리핑이라면, 펄스체크(Pulse Check) 스킬은 프로젝트 전체의 건강 상태를 점검하는 깊은 진단입니다.

펄스체크 스킬을 실행하면, 에이전트가 모든 진행 중인 프로젝트의 태스크를 가져옵니다. 각 태스크의 상태(완료, 진행 중, 지연)를 확인하고, 분기 목표(goals.md) 대비 진척도를 계산합니다. 수동 팔로업이 필요한 항목을 별도로 표시합니다.

두 스킬의 차이는 깊이와 빈도입니다. 모닝커피는 매일, 5분 안에 끝나는 가벼운 브리핑입니다. 펄스체크는 주 1~2회, 프로젝트 전체를 조감하는 깊이 있는 점검입니다.

■나 유튜브 분석 스킬: 영상 데이터를 리포트로 변환

이그제큐티브 어시스턴트의 스킬은 업무 관리에만 국한되지 않습니다. 사업에 필요한 모든 반복 작업을 스킬로 만들 수 있습니다.

유튜브 채널을 운영한다면, 주간 분석 리포트를 자동으로 생성하는 스킬을 만들 수 있습니다. 이 스킬은 유튜브 API를 통해 최근 7일간 발행된 영상의 조회수, 좋아요, 댓글을 수집합니다. 댓글 내용을 분석해서 시청자가 원하는 주제, 불만 사항, 칭찬 포인트를 추출합니다. 경쟁 채널의 인기 영상도 함께 조사합니다. 이 모든 데이터를 SWOT 분석 형식의 PDF 보고서로 만들어, 브랜드 로고와 색상이 적용된 상태로 projects 폴더에 저장합니다.

이 스킬을 19장에서 배운 스케줄 배포와 결합하면, 매주 월요일 아침 자동으로 지난주 분석 리포트가 생성됩니다. 여러분은 리포트를 읽고 의사결정에 반영하기만 하면 됩니다.

■다 스킬 크리에이터: 기존 작업 패턴을 자동으로 스킬화하는 도구

스킬을 많이 만들다 보면, 스킬을 만드는 과정 자체를 자동화하고 싶어집니다. 앤트로픽이 공식으로 제공하는 스킬 크리에이터(Skill Creator) 스킬이 이 역할을 합니다.

스킬 크리에이터는 스킬을 만드는 스킬입니다. 이 안에는 앤트로픽이 축적한 스킬 구축 모범 사례가 담겨 있습니다. YAML 프론트 매터(Front Matter)의 올바른 구조, 단계별 지침의 작성 원칙, 참조 파일의 배치 전략, 그리고 스킬의 품질을 평가하고 개선하는 이밸(Eval) 프로세스까지.

설치는 채팅창에서 /plugins를 입력하고, "skill-creator"를 검색해서 설치 버튼을 누르면 됩니다.

설치 후, "유튜브 주간 분석 스킬을 만들어줘"라고 요청하면, 스킬 크리에이터가 질문을 던지고, 답변을 바탕으로 skill.md를 자동 생성합니다. 생성된 스킬을 테스트하고, 결과를 기준 산출물(Golden Output)과 비교해서 품질을 평가하고, 개선점을 제안합니다.

스킬 크리에이터의 이밸 기능은 스킬의 장기적 관리에 유용합니다. AI 모델이 업데이트될 때, 기존 스킬이 여전히 잘 작동하는지 자동으로 검증합니다. 성능이 떨어졌으면 스킬을 수정해야 한다는 신호를 줍니다. 반대로, 모델이 개선되어 스킬 없이도 충분히 좋은 결과를 내면, 해당 스킬을 폐기해도 된다는 판단을 돕습니다.

이것으로 제6부가 마무리됩니다. 네 단계 프레임워크로 이그제큐티브 어시스턴트의 뼈대를 세우고, claude.md 컨텍스트 관리를 심화하고, 모닝커피 스킬과 유튜브 분석 스킬을 실전으로 구축했습니다. 스킬 크리에이터로 스킬 생성 과정 자체를 자동화하는 방법도 배웠습니다.

그런데 지금까지 에이전트는 한 번에 하나의 작업만 수행했습니다. 모닝커피 스킬을 실행하는 동안에는 리서치를 할 수 없고, 리서치를 하는 동안에는 콘텐츠를 만들 수 없습니다. 만약 여러 작업을 동시에, 각각 전문화된 에이전트에게 맡길 수 있다면? 리서처 에이전트가 조사하는 동안, 콘텐츠 에이전트가 초안을 쓰고, 분석 에이전트가 데이터를 정리하는 병렬 구조. 이것이 서브에이전트이고, 에이전트 팀입니다.

23장 서브에이전트의 개념과 작동 원리

■가 메인 세션에서 전문화된 에이전트로 작업을 위임하는 구조

파티를 준비한다고 합시다. 커스텀 컵케이크가 필요합니다. 동네 마트에서 대량 생산된 컵케이크를 사올 수도 있지만, 특별한 파티에는 전문 베이커리에 맞춤 주문을 하는 편이 낫습니다. 베이커리는 컵케이크만 만듭니다. 디저트 전체를 다루지 않습니다. 그 대신 컵케이크에 관해서는 여러분보다 훨씬 잘합니다.

서브에이전트(Sub-agent)가 바로 이 전문 베이커리입니다.

지금까지 여러분은 클로드 코드의 메인 세션 하나에서 모든 작업을 처리했습니다. 리서치도 하고, 코드도 짜고, PDF도 만들고, 이메일도 보냈습니다. 이 방식의 문제는 두 가지입니다. 첫째, 메인 세션의 컨텍스트 윈도우가 빠르게 채워집니다. 리서치 결과 수만 토큰이 쌓이면, 이후 코드 작성이나 PDF 생성의 품질이 떨어집니다. 6장에서 배운 컨텍스트 로트입니다. 둘째, 범용 에이전트가 모든 일을 다 하면, 어떤 것도 탁월하게 하지 못합니다. 사람도 마찬가지입니다. 마케팅, 재무, 개발을 한 사람이 다 하면 어느 하나도 전문가 수준에 이르기 어렵습니다.

서브에이전트는 이 두 문제를 동시에 해결합니다. 메인 세션이 프로젝트 매니저 역할을 하고, 전문화된 작업을 서브에이전트에게 위임합니다. 서브에이전트는 자신만의 컨텍스트 윈도우에서 독립적으로 작업합니다. 4만 토큰짜리 리서치를 서브에이전트가 처리하면, 메인 세션의 컨텍스트는 깨끗하게 유지됩니다. 서브에이전트가 결과를 요약해서 돌려보내면, 메인 세션은 핵심 정보만 받아서 다음 단계를 진행합니다.

■나 코더, 리뷰어, 디버거, 테스트 러너, 아키텍트, 리서처의 역할 분담

서브에이전트에 부여할 수 있는 전문 역할은 다양합니다. 클로드 코드를 만든 앤트로픽의 보리스 처니(Boris Cherny)는 자신이 일상적으로 사용하는 서브에이전트로 빌드 검증기(Build Validator), 코드 아키텍트(Code Architect), 코드 단순화기(Code Simplifier), 운영 가이드(On-call Guide), 앱 검증기(Verify App) 등을 언급한 바 있습니다.

실무에서 자주 등장하는 역할 분담을 정리하면 이렇습니다. 리서처(Researcher)는 웹 검색과 데이터 수집을 전담합니다. 코더(Coder)는 코드 작성을 맡습니다. 리뷰어(Reviewer)는 작성된 코드를 검토하고 품질을 점검합니다. 디버거(Debugger)는 오류를 추적하고 수정합니다. 테스트 러너(Test Runner)는 자동화된 테스트를 실행합니다. 아키텍트(Architect)는 프로젝트의 전체 구조를 설계합니다.

이 역할들을 모두 만들 필요는 없습니다. 여러분의 작업 패턴에서 반복적으로 나타나는 전문 영역부터 하나씩 서브에이전트로 분리하면 됩니다.

■다 서브에이전트는 자체 컨텍스트와 별도 모델로 병렬 실행된다

서브에이전트의 작동 방식에서 반드시 이해해야 할 세 가지 특성이 있습니다.

독립 컨텍스트입니다. 서브에이전트가 깨어나면, 메인 세션의 대화 이력을 물려받지 않습니다. 완전히 빈 상태에서 시작합니다. 메인 세션이 건네주는 프롬프트(작업 지시)만이 서브에이전트의 초기 입력입니다. 이 덕분에 메인 세션의 컨텍스트가 오염되지 않습니다.

별도 모델 선택입니다. 서브에이전트마다 다른 AI 모델을 지정할 수 있습니다. 리서치 서브에이전트에 하이쿠를 배정하면 토큰 비용이 절감됩니다. 아키텍처 결정이 필요한 서브에이전트에는 오퍼스를 배정해서 깊은 추론을 확보합니다. 7장에서 다룬 모델 선택 전략이 서브에이전트 수준에서 적용되는 것입니다.

병렬 실행입니다. 여러 서브에이전트를 동시에 띄울 수 있습니다. 리서치 에이전트가 웹을 검색하는 동안, 코드 에이전트가 기존 코드를 리팩토링하고, 테스트 에이전트가 기존 테스트를 실행할 수 있습니다. 세 에이전트가 동시에 작업하므로, 순차적으로 처리할 때보다 훨씬 빠릅니다.

서브에이전트의 한 가지 제약을 기억해야 합니다. 서브에이전트끼리는 서로 대화할 수 없습니다. 리서치 에이전트가 코드 에이전트에게 "이 데이터를 참고해"라고 직접 말할 수 없습니다. 모든 커뮤니케이션은 메인 세션을 거칩니다. 메인 세션이 리서치 결과를 받아서, 코드 에이전트에게 전달하는 구조입니다. 이 제약이 불편하다면, 25장에서 다룰 에이전트 팀이 대안입니다.

서브에이전트의 개념과 작동 원리를 이해했으니, 직접 만들어 보겠습니다.

24장 서브에이전트 커스텀 빌드

■가 캐러셀 플래닝 서브에이전트: 트랜스크립트를 슬라이드로 변환

이그제큐티브 어시스턴트 프로젝트에서 실용적인 서브에이전트를 하나 만들어 보겠습니다. 유튜브 영상의 트랜스크립트(전사문)를 소셜 미디어용 캐러셀(Carousel, 넘겨보는 형식의 이미지 슬라이드) 콘텐츠로 변환하는 서브에이전트입니다.

메인 세션의 캐러셀 스킬 안에서, 에이전트가 트랜스크립트를 받으면 핵심 메시지를 추출하고, 슬라이드별 텍스트와 레이아웃을 계획하고, 이미지를 생성합니다. 이 과정에서 "슬라이드 계획"이라는 단계를 별도 서브에이전트에게 맡기면, 메인 세션의 컨텍스트를 절약하면서 슬라이드 구성의 전문성을 높일 수 있습니다.

서브에이전트를 만드는 가장 간편한 방법은 /agents 명령어입니다. 터미널에서 이 명령어를 실행하면, "새 에이전트 생성(Create New Agent)" 옵션이 나타납니다. 프로젝트 에이전트(이 프로젝트에서만 사용)를 선택하고, "Claude로 생성(Generate with Claude)"을 택합니다. 에이전트의 역할을 설명합니다.

"이 에이전트는 캐러셀 플래너다. 유튜브 트랜스크립트를 받아서, 7~8장의 슬라이드로 구성된 캐러셀 콘텐츠 계획을 만든다. 각 슬라이드의 제목, 본문, 시각적 제안을 포함한다."

에이전트가 이 설명을 바탕으로 agent.md 파일을 자동 생성합니다. 사용할 도구, 모델(소네 또는 하이쿠), 에이전트 색상(터미널에서 구분용) 등을 설정합니다. 메모리 기능을 활성화하면, 서브에이전트가 이전 실행에서 학습한 패턴을 다음 실행에서 참조합니다.

이 서브에이전트를 스킬 안에서 호출하는 방법은 간단합니다. 캐러셀 스킬의 skill.md에 "슬라이드 계획 단계에서 캐러셀 플래너 에이전트에 위임하라"는 지시를 넣으면, 스킬이 실행될 때마다 서브에이전트가 자동으로 호출됩니다.

■나 리서치 서브에이전트 2기 병렬 운용: SMB용과 엔터프라이즈용

서브에이전트의 병렬 실행 능력이 빛을 발하는 사례입니다.

"AI 활용 전략에 대해 리서치해줘"라고 요청하되, 중소기업(SMB) 관점과 대기업(Enterprise) 관점을 동시에 조사하고 싶다면? 하나의 리서치 서브에이전트로 순차적으로 하면 시간이 두 배 걸립니다. 대신 리서치 서브에이전트를 두 기 동시에 띄웁니다.

"서브에이전트 두 개를 띄워줘. 하나는 중소기업의 AI 도입 사례를 조사하고, 다른 하나는 대기업의 AI 거버넌스 전략을 조사해. 둘 다 완료되면 결과를 종합해줘."

메인 세션이 두 서브에이전트를 동시에 생성합니다. 각각 독립 컨텍스트에서 웹을 검색하고 자료를 정리합니다. 두 에이전트가 동시에 작업하므로, 순차 처리 대비 시간이 거의 절반으로 줄어듭니다.

■다 결과를 메인 세션으로 수집하고 종합하는 흐름

두 서브에이전트가 작업을 마치면, 각각의 결과가 메인 세션으로 돌아옵니다. 이때 메인 세션이 받는 것은 서브에이전트의 전체 작업 과정이 아니라, 최종 요약입니다.

SMB 서브에이전트가 "중소기업 AI 도입 현황: 주요 사례 5건, 도입 장벽 3가지, 권장 시작점"을 반환하고, 엔터프라이즈 서브에이전트가 "대기업 AI 거버넌스: 프레임워크 3종 비교, 규제 대응 현황, 조직 구조 변화"를 반환합니다. 메인 세션은 이 두 결과를 받아서, 겹치는 부분과 차이점을 분석하고, 통합 보고서를 작성합니다.

이 구조의 핵심 가치는 컨텍스트 효율입니다. SMB 서브에이전트가 내부적으로 4만 토큰을 소비했더라도, 메인 세션이 받는 요약은 수천 토큰에 불과합니다. 메인 세션의 컨텍스트 윈도우는 깨끗하게 유지되면서, 두 분야의 깊이 있는 리서치를 확보한 것입니다.

서브에이전트가 개별 전문가라면, 에이전트 팀은 한 팀이 모여 협업하는 프로젝트 조직입니다. 구성원끼리 직접 대화하고, 공유 태스크 리스트를 관리하고, 서로의 작업물을 검토합니다.

25장 에이전트 팀

■가 서브에이전트와 에이전트 팀의 차이

서브에이전트를 다시 한번 정리하면 이렇습니다. 메인 세션이 지시를 내리고, 서브에이전트가 독립적으로 수행하고, 결과를 돌려줍니다. 일방통행입니다. 서브에이전트끼리는 대화하지 못합니다.

에이전트 팀(Agent Team)은 이 구조를 한 단계 끌어올립니다. 팀 내의 에이전트들이 서로 메시지를 주고받을 수 있습니다. 공유 태스크 리스트를 함께 관리합니다. 한 에이전트가 작업을 마치면 다른 에이전트에게 직접 "이거 확인해줘"라고 보낼 수 있습니다.

축구 팀에 비유하면 이해가 쉽습니다. 서브에이전트 구조에서는 감독이 각 선수에게 개별적으로 지시를 내리고, 선수들은 감독에게만 보고합니다. 선수끼리는 대화하지 않습니다. 에이전트 팀 구조에서는 감독이 전체 전략을 세우고, 선수들이 경기장에서 서로 소통하며 실시간으로 협업합니다. 수비수가 미드필더에게 공을 넘기고, 미드필더가 공격수에게 패스합니다.

■나 복수 에이전트가 하나의 목표를 향해 협업하는 패턴

에이전트 팀이 진가를 발휘하는 대표적인 패턴은 풀스택 웹 앱 구축입니다.

"랜딩 페이지를 만들어줘"라고 요청하면서, 팀을 구성합니다. "프런트엔드 개발자, 백엔드 개발자, QA 에이전트, 세 명으로 팀을 만들어. 소네 모델을 사용해."

메인 세션이 세 에이전트를 동시에 생성합니다. 공유 태스크 리스트가 만들어지고, 각 에이전트에게 담당 영역이 배정됩니다. 프런트엔드 개발자가 화면을 구성하고, 백엔드 개발자가 서버 로직을 만듭니다. 두 에이전트가 병렬로 작업한 뒤, QA 에이전트에게 "검수해줘"라는 메시지를 보냅니다. QA 에이전트가 테스트를 실행하고, 버그 세 건을 발견합니다. QA 에이전트가 프런트엔드 개발자와 백엔드 개발자에게 각각 "이 부분 수정해줘"라고 직접 메시지를 보냅니다. 수정이 끝나면 QA 에이전트가 다시 검수합니다. 통과하면 메인 세션에 "완료"를 보고합니다.

이 전체 과정에서 메인 세션은 오케스트레이터(Orchestrator, 총괄 지휘자) 역할만 합니다. 실제 작업과 품질 검증은 팀원들 사이에서 자율적으로 이루어집니다.

에이전트 팀을 사용하려면 실험적 기능을 활성화해야 합니다. 프로젝트의 .claude/settings.local.json에 해당 설정을 추가합니다. 에이전트에게 "이 설정을 넣어줘"라고 말하면 됩니다.

에이전트 팀 사용 시 주의할 점이 있습니다. 비용이 서브에이전트보다 높습니다. 세 에이전트가 동시에 작동하면 토큰 소비도 세 배 가까이 됩니다. 또한 에이전트끼리 같은 파일을 동시에 수정하면 충돌이 발생할 수 있으므로, 각 에이전트가 담당하는 파일 영역을 명확히 구분해야 합니다. 팀 규모는 3~5명이 적당합니다. 10명 이상의 팀은 조율 비용이 급격히 증가하고 비용 효율이 떨어집니다.

■다 컨텍스트 보존 전략: 에이전트 간 정보 유실을 방지하는 법

서브에이전트든 에이전트 팀이든, 가장 까다로운 문제는 정보 유실입니다. 서브에이전트는 깨어날 때 빈 상태에서 시작합니다. 에이전트 팀의 팀원도 마찬가지입니다. 메인 세션이 보내주는 초기 프롬프트 외에는 아무 맥락이 없습니다.

이 문제를 완화하는 전략이 세 가지 있습니다.

풍부한 초기 프롬프트입니다. 서브에이전트를 호출할 때, 작업 지시뿐 아니라 필요한 배경 정보를 함께 넘깁니다. "SMB 리서치를 해줘"라고만 하는 것이 아니라, "우리는 AI 자동화 컨설팅 회사다. 주요 고객은 10~50인 규모의 마케팅 에이전시다. 이 맥락에서 SMB의 AI 도입 사례를 조사해줘"라고 구체적으로 전달합니다.

프로젝트 파일 접근입니다. 서브에이전트와 에이전트 팀 팀원은 프로젝트의 모든 파일에 접근할 수 있습니다. context 폴더의 me.md, work.md를 읽을 수 있고, 스킬 파일도 사용할 수 있습니다. 초기 프롬프트에 "context 폴더의 파일을 참조하라"고 명시하면, 에이전트가 필요한 맥락을 스스로 로드합니다.

에이전트 메모리입니다. /agents 명령어로 서브에이전트를 만들 때 메모리 기능을 활성화하면, 에이전트 전용 메모리 파일이 생성됩니다. 실행이 끝날 때마다 에이전트가 학습한 내용(좋은 데이터 소스, 반복되는 주제, 효과적이었던 접근법)이 이 파일에 기록됩니다. 다음 실행 시 에이전트가 이 메모리를 읽고 시작하므로, 완전한 백지 상태보다 훨씬 효율적으로 작업합니다.

이것으로 제7부가 마무리됩니다. 서브에이전트로 전문화된 작업을 병렬로 위임하고, 에이전트 팀으로 복수의 전문가가 실시간 협업하는 구조를 구축했습니다. 에이전틱 시스템의 규모를 키우는 방법을 배운 것입니다.

제8부에서는 방향을 바꿉니다. 규모를 키우는 것이 아니라, 기존 시스템을 더 날카롭고 효율적으로 가다듬는 기법들입니다. 클로드 코드를 매일 사용하는 사람들이 경험을 통해 발견한 해킹 팁 32가지. 초급 10가지, 중급 12가지, 고급 10가지가 기다리고 있습니다. 깃 워크트리로 병렬 세션을 운영하는 방법, VPS에 클로드 코드를 올려 24시간 가동하는 방법, 권한 설정으로 안전한 자율성을 확보하는 방법. 이 팁들 하나하나가 여러분의 일상적인 작업 시간을 깎아줄 것입니다.

26장 초급 해킹 팁 (1~10)

■가 모든 프로젝트에서 /init 실행하기

새 프로젝트를 열면 가장 먼저 해야 할 일이 있습니다. /init을 입력하는 것입니다. 기존 파일이 있는 프로젝트라면 에이전트가 코드베이스를 스캔해서 아키텍처, 사용 언어, 주요 파일을 파악한 claude.md를 자동으로 생성합니다. 새 프로젝트라면 기본 폴더 구조를 제안합니다. 이 한 줄의 명령어가 매 세션의 시작을 10분은 단축해 줍니다.

■나 상태 표시줄(Status Line) 커스터마이징

터미널에서 클로드 코드를 사용한다면, /statusline 명령어로 화면 하단에 항상 보이는 상태 표시줄을 설정할 수 있습니다. 현재 사용 중인 모델, 컨텍스트 사용률, 세션 비용을 실시간으로 표시합니다. 별도의 명령어를 입력하지 않아도 컨텍스트가 60%를 넘는 순간을 바로 알아차릴 수 있습니다. 자동차 계기판의 연료 게이지처럼, 눈에 보여야 관리가 됩니다.

■다 음성 입력으로 프롬프트 속도 높이기

클로드 코드에 /voice 명령어가 도입되어 터미널에서 직접 음성 입력이 가능합니다. 음성이 타이핑보다 빠른 이유는 간단합니다. 손가락은 분당 40~60단어를 치지만, 입은 분당 120~150단어를 말합니다. 복잡한 요구사항을 브레인 덤프할 때, 키보드를 두드리며 문장을 다듬는 대신 머릿속 생각을 그대로 쏟아낼 수 있습니다. 에이전트는 구어체도 잘 이해합니다.

별도의 음성-텍스트 변환 앱을 사용하는 방법도 있습니다. 앱을 활성화하면 클로드 코드 채팅창뿐 아니라 어디서든 말한 내용이 텍스트로 변환됩니다.

■라 컨텍스트를 작게 유지하는 습관

에이전트에게 전체 코드베이스를 한꺼번에 던지지 마십시오. 현재 작업에 필요한 파일과 정보만 전달합니다. 큰 문제를 작고 집중된 단계로 쪼개서 진행합니다. 컨텍스트 윈도우에 불필요한 잡음이 적을수록 에이전트의 응답 품질이 올라갑니다. 6장에서 배운 원리의 일상적 적용입니다.

■마 /context로 토큰 소비원 파악하기

에이전트가 느려지거나 응답 품질이 떨어진다고 느낄 때, /context를 입력합니다. 시스템 프롬프트, MCP 서버, 스킬, 대화 이력 각각이 얼마나 토큰을 차지하는지 항목별로 보여줍니다. 사용하지 않는 MCP 서버가 컨텍스트의 10%를 잡아먹고 있다면, 해제하는 것만으로 성능이 체감될 정도로 개선됩니다. 가계부를 쓰는 것과 같습니다. 지출 내역을 보지 않으면 어디서 돈이 새는지 알 수 없습니다.

■바 60%에서 compact, 작업 전환 시 clear

컨텍스트 사용률이 60%에 도달하면 /compact를 실행합니다. 에이전트가 대화를 압축해서 핵심 정보만 남기고 나머지를 정리합니다. "API 연동 결정 사항은 유지해줘"처럼 보존할 내용을 지정할 수 있습니다.

작업 주제가 완전히 바뀔 때는 /clear로 대화를 초기화합니다. 뉴스레터 작업에서 경쟁사 분석으로 넘어갈 때, 이전 대화의 잔여 맥락이 새 작업을 오염시키는 것을 방지합니다. claude.md와 프로젝트 파일은 그대로 유지되므로, 진짜 처음부터 시작하는 것이 아닙니다.

■사 언제나 플랜 모드에서 시작하기

채팅창 하단에서 시프트+탭(Shift+Tab)을 눌러 플랜 모드로 전환합니다. 플랜 모드에서 에이전트는 읽고, 조사하고, 계획을 세우되, 파일을 만들거나 코드를 실행하지 않습니다.

이 한 가지 습관이 수정 횟수를 극적으로 줄여줍니다. 계획 없이 바로 구축에 들어가면, 에이전트가 잘못된 방향으로 코드를 쌓아올린 뒤에야 문제를 발견합니다. 되돌리고 다시 시작하는 비용이 큽니다. 플랜 모드에서 계획을 확인하고, 수정하고, 합의한 뒤에 실행 모드로 전환하면, 첫 번째 결과물의 품질이 훨씬 높습니다.

■아 클로드를 주니어 개발자처럼 대하기: 명령 대신 문제를 주기

"로그인 함수를 작성해"라고 직접 명령하는 대신, "사용자 인증을 어떻게 처리하면 좋을까?"라고 문제를 건네봅니다. 에이전트가 스스로 접근 방법을 고민하고, 여러 선택지를 제시하고, 각각의 장단점을 설명합니다. 이 과정에서 에이전트가 더 깊이 추론하므로, 최종 코드의 품질이 올라갑니다.

에이전트의 판단 과정을 읽는 것 자체가 학습이 됩니다. "왜 이 방법을 선택했어?"라고 물으면, 에이전트가 기술적 근거를 설명해 줍니다.

■자 클로드가 먼저 질문하게 만들기

프롬프트 끝에 이 한 문장을 추가합니다. "내가 원하는 것을 95% 확신할 때까지 질문을 계속해." 에이전트가 빠뜨린 정보, 모호한 요구 사항, 잠재적 갈등 지점을 스스로 발견해서 물어옵니다. 세 번째 수정 라운드에서야 "아, 이걸 처음에 말했어야 했는데"라고 후회하는 상황을 미리 방지합니다.

■차 투두 리스트에 자기검증 단계 넣기

에이전트가 투두 리스트를 만들 때, 구축 단계 사이에 검증 단계를 끼워 넣으라고 지시합니다. "웹사이트를 만든 뒤, 다음 단계로 넘어가기 전에 스크린샷을 찍어서 레이아웃이 맞는지 확인해." "API 연동을 완료한 뒤, 테스트 호출을 실행해서 응답이 정상인지 확인해."

"다음 단계로 넘어가기 전에 95% 확신이 들 때까지 검증해"라는 규칙을 추가하면, 에이전트가 60% 완성도의 결과물을 넘기는 대신 90% 완성도에서 넘깁니다.

초급 팁 열 가지를 적용하는 것만으로도 작업 효율이 눈에 띄게 달라집니다. 다음은 이미 클로드 코드에 손이 익은 분들을 위한 중급 팁입니다.

27장 중급 해킹 팁 (11~22)

■가 서브에이전트에 병렬 작업 위임하기

복잡한 작업을 만나면, 메인 세션에서 모든 것을 처리하려 하지 말고 서브에이전트에 위임합니다. "리서치는 서브에이전트에 맡기고, 결과만 요약해서 보내줘"라고 지시하면, 메인 세션의 컨텍스트가 깨끗하게 유지됩니다. 23장에서 배운 서브에이전트의 일상적 활용입니다.

■나 커스텀 스킬 직접 만들기

같은 유형의 작업을 세 번 이상 반복했다면, 스킬로 만들 때입니다. .claude/skills 폴더에 skill.md를 만들고, 작업의 단계, 규칙, 참조 파일을 기술합니다. 다음부터는 "이 스킬을 실행해"라는 한마디면 일관된 품질의 결과물이 나옵니다.

■다 서브에이전트에 Haiku 모델 배정하기

대량의 데이터를 처리하거나 단순 반복 작업을 수행하는 서브에이전트에는 하이쿠를 배정합니다. 수십만 토큰의 트랜스크립트를 읽고 핵심만 추출하는 작업에 오퍼스를 사용하면 비용이 불필요하게 높아집니다. 하이쿠로 처리한 뒤 요약만 메인 세션으로 돌려보내면, 품질 손실 없이 비용을 절감합니다.

■라 claude.md를 수시로 갱신하기

프로젝트에서 새로운 패턴을 발견하거나, 에이전트가 반복적으로 같은 실수를 저지를 때마다, claude.md를 업데이트합니다. "이 규칙을 claude.md에 추가해줘"라고 말하면 에이전트가 직접 파일을 수정합니다. claude.md는 살아 있는 문서입니다.

■마 claude.md가 500줄을 넘으면 외부 파일로 분리

claude.md의 적정 분량은 150~200줄입니다. 그 이상이 되면 매 대화의 토큰 소비가 급증합니다. 5장과 21장에서 배운 라우팅 전략을 적용합니다. 정보를 카테고리별로 분리하고, claude.md에는 참조 경로만 남깁니다.

■바 조기 종료 후 재질문하기

에이전트가 잘못된 방향으로 가고 있다면, 완료될 때까지 기다리지 마십시오. 에스케이프(Escape) 키를 눌러 실행을 중단합니다. 잘못된 방향으로 소비된 토큰은 되돌릴 수 없습니다. 방향을 수정하는 프롬프트를 보내고, 다시 시작합니다.

■사 결과물을 공격적으로 검증하고 되묻기

에이전트의 첫 번째 결과물이 "괜찮다" 수준이라면, 더 높은 기준을 제시합니다. "이걸 폐기하고 완전히 다른 접근법으로 해봐", "더 세련된 버전을 만들어봐". 에이전트는 첫 시도에서 무엇이 부족했는지 인식하고, 두 번째 시도에서 품질을 끌어올립니다. 피드백을 줄 때마다, 에이전트에게 "이 교훈을 스킬에 반영해"라고 말하면 같은 실수가 재발하지 않습니다.

■아 /rewind로 빠른 되돌리기

에이전트가 코드를 수정했는데 오히려 상태가 나빠졌다면, /rewind를 입력합니다. 수정 전 시점으로 대화와 코드 상태가 복원됩니다. 워드 프로세서의 실행 취소와 같은 개념이지만, 코드 변경까지 함께 되돌립니다.

■자 훅(Hooks)으로 알림 설정하기

/hooks 명령어로 특정 이벤트에 알림을 연결합니다. "세션이 끝나면 소리를 울려줘"라고 설정하면, 다른 작업을 하다가도 에이전트가 완료되었음을 즉시 알 수 있습니다. 여러 세션을 병렬로 돌릴 때 유용합니다.

■차 스크린샷을 찍어 시각적 검증하기

에이전트에게 "스크린샷을 찍어서 확인해"라고 지시하면, 퍼피티어가 현재 페이지를 캡처합니다. 에이전트가 이미지를 분석해서 레이아웃 오류, 색상 불일치, 텍스트 잘림을 발견합니다. 12장에서 배운 스크린샷 루프의 일상적 활용입니다.

■카 크롬 개발자 도구(Chrome DevTools) 활용

에이전트가 브라우저를 열어 웹 앱의 기능을 테스트할 수 있습니다. 버튼 클릭, 양식 제출, 페이지 이동을 자동으로 수행하면서 자바스크립트 오류나 네트워크 요청 실패를 감지합니다. 스크린샷이 디자인 검증이라면, 크롬 개발자 도구는 기능 검증입니다.

■타 영감 사이트 클론하기

12장에서 상세히 다룬 기법입니다. 마음에 드는 웹사이트의 스크린샷과 스타일 정보를 에이전트에게 건네고 "이런 느낌으로 만들어줘"라고 말합니다. 처음부터 디자인을 설명하는 것보다 시각적 참조를 제공하는 것이 훨씬 빠르고 정확합니다.

28장 고급 해킹 팁 (23~32)

■가 깃 워크트리로 병렬 세션 운영하기

(1) 같은 리포에서 여러 브랜치를 동시에 체크아웃하는 원리

일반적으로 깃(Git)에서는 한 번에 하나의 브랜치만 작업할 수 있습니다. 새 기능을 개발하다가 긴급 수정이 필요하면, 현재 작업을 저장하고 브랜치를 전환해야 합니다. 작업이 끊기고, 맥락이 흐트러집니다.

깃 워크트리(Git Worktree)는 이 제약을 풀어줍니다. 같은 리포지토리에서 여러 브랜치를 각각 별도의 폴더에 동시에 체크아웃할 수 있습니다. 폴더 A에서는 메인 브랜치를, 폴더 B에서는 기능 브랜치를, 폴더 C에서는 수정 브랜치를 동시에 열어놓는 것입니다.

(2) 각 워크트리에서 독립적 클로드 코드 세션 실행

각 워크트리 폴더에서 독립적인 클로드 코드 세션을 실행할 수 있습니다. 세션 A는 새 기능을 구축하고, 세션 B는 버그를 수정하고, 세션 C는 문서를 업데이트합니다. 세 세션이 같은 리포지토리에서 작업하지만, 서로의 파일을 건드리지 않습니다. 작업이 끝나면 각 브랜치를 메인에 병합합니다.

클로드 코드에서 워크트리를 만드는 명령어는 claude --worktree 기능이름입니다. 에이전트가 자동으로 새 브랜치와 작업 폴더를 생성합니다.

■나 MCP 서버 대신 API 엔드포인트 직접 호출하기

MCP 서버는 편리하지만 도구 정의 전체가 컨텍스트를 차지합니다. 특정 프로젝트에서 MCP 서버의 기능 중 하나만 사용한다면, 해당 API 엔드포인트를 직접 호출하는 것이 토큰 효율이 높습니다. 노션(Notion)의 데이터베이스 하나만 읽으면 되는데, 노션 MCP 서버의 수십 가지 도구 설명이 매 대화마다 로드될 필요는 없습니다.

■다 /loop으로 반복 작업 자동화하기

/loop 명령어 또는 "5분마다 배포 상태를 확인해줘"라는 자연어로, 에이전트가 같은 세션 안에서 지정된 간격으로 작업을 반복합니다. 배포 모니터링, PR(Pull Request) 검토, 에러 로그 감시에 활용됩니다. 세션이 열려 있는 동안 최대 3일까지 유지됩니다. 3일 이상의 장기 자동화가 필요하면, 19장에서 다룬 스케줄 배포나 데스크톱 앱의 스케줄 태스크를 사용합니다.

■라 VPS에 클로드 코드를 올려 항시 가동 세션 만들기

(1) SSH 접속과 Telegram 연동

VPS(Virtual Private Server, 가상 사설 서버)에 클로드 코드를 설치하면, 여러분의 컴퓨터가 꺼져 있어도 에이전트가 24시간 작동합니다. SSH(Secure Shell, 원격 접속 프로토콜)로 접속해서 에이전트와 대화할 수 있습니다. 텔레그램(Telegram) 브릿지를 설정하면, 스마트폰에서 에이전트에게 메시지를 보내고 답변을 받을 수 있습니다. 주머니 속의 클로드 코드입니다.

호스팅어(Hostinger) 같은 서비스에서 월 6달러(한화 약 8,200원) 수준의 VPS를 빌려 시작할 수 있습니다. 클로드 코드 설치는 터미널에서의 설치와 동일합니다.

■마 폰에서 원격 제어하기

클로드 코드의 원격 제어(Remote Control) 기능으로, 로컬 데스크톱에서 시작한 세션을 스마트폰 브라우저에서 이어갈 수 있습니다. 코드는 로컬 머신에 남아 있고, 원격 연결로 지시만 전달됩니다. 작업을 시작해놓고 자리를 비워야 할 때, 이동 중에도 에이전트를 관리할 수 있습니다.

■바 노코드 데이터 분석

빅쿼리(BigQuery)의 BQ CLI 같은 데이터 도구를 클로드 코드에 연결하면, 자연어로 데이터를 분석할 수 있습니다. "지난 분기 매출 상위 10개 제품을 알려줘"라고 말하면, 에이전트가 적절한 SQL 쿼리를 작성하고 실행해서 결과를 반환합니다. SQL을 모르는 사람도 데이터에 접근할 수 있습니다.

■사 울트라 씽크(Ultra Think) 모드

에이전트가 복잡한 문제에서 잘못된 답을 반복할 때, 프롬프트에 "ultrathink"라는 단어를 넣으면 최대 사고 예산(약 32,000토큰)을 할당합니다. 에이전트가 평소보다 훨씬 깊이 추론한 뒤 답변합니다. 아키텍처 설계, 복잡한 디버깅, 전체 시스템에 영향을 미치는 결정에 사용합니다. 일상적인 작업에는 불필요합니다.

■아 권한(Permissions) 설정으로 안전한 자율성 확보하기

(1) dangerously-skip-permissions의 위험성

바이패스 퍼미션 모드는 편리하지만, 에이전트가 어떤 명령이든 승인 없이 실행할 수 있다는 뜻입니다. 파일 삭제, 시스템 설정 변경, 외부 서비스 호출이 모두 자동으로 이루어집니다.

(2) 안전한 명령어만 허용 목록에 등록하는 방법

더 안전한 방법은 프로젝트 설정에서 허용할 명령어와 금지할 명령어를 명시하는 것입니다. 파일 읽기, 웹 검색은 허용하되, 파일 삭제(rm -rf)나 시스템 수정은 금지합니다. 금지 목록이 허용 목록보다 우선하므로, 허용 목록에 실수로 위험한 명령을 넣더라도 금지 목록이 막아줍니다.

이렇게 설정하면 바이패스 퍼미션과 비슷한 속도를 유지하면서도, 치명적인 실수를 방지하는 안전망이 생깁니다.

■자 에이전트 팀 구성

25장에서 다룬 에이전트 팀을 실험적 기능으로 활성화합니다. 프로젝트 설정 파일에 해당 옵션을 추가하면 됩니다. 3~5명의 전문 에이전트가 서로 소통하며 병렬로 작업합니다. 비용이 높으므로, 복잡하고 다면적인 프로젝트에서만 사용하는 것이 현명합니다.

■차 Context7 MCP 활용

컨텍스트 세븐(Context7)은 버전별 최신 기술 문서를 제공하는 MCP 서버입니다. 에이전트의 훈련 데이터에는 API 변경이나 라이브러리 업데이트가 반영되지 않을 수 있습니다. Context7을 연결하면, 에이전트가 코드를 작성하기 전에 해당 라이브러리의 최신 문서를 확인합니다. 이름이 바뀐 함수, 삭제된 파라미터, 새로 추가된 기능 때문에 발생하는 오류를 사전에 방지합니다.

32가지 해킹 팁이 모두 나왔습니다. 이 팁들은 한꺼번에 적용하는 것이 아니라, 하나씩 시도하면서 자신의 워크플로우에 맞는 것을 골라 습관으로 만드는 것입니다. 초급 팁부터 시작해서, 필요에 따라 중급과 고급으로 올라가면 됩니다.

에이전트가 브라우저를 직접 열고 조작하는 방법, 그리고 깃과 깃허브의 핵심 개념은 별도의 장에서 다룹니다.

29장 브라우저 자동화

■가 클로드 코드가 브라우저를 열고 조작하는 원리

컴퓨터 앞에 앉아서 마우스를 움직이고, 버튼을 클릭하고, 텍스트를 입력하는 모든 행위를 코드로 재현하는 것. 이것이 브라우저 자동화의 본질입니다.

클로드 코드에서는 플레이라이트 CLI(Playwright CLI)를 설치해서 이 기능을 활성화합니다. 플레이라이트는 웹 브라우저를 코드로 제어하는 도구입니다. 에이전트가 브라우저를 열고, URL을 입력하고, 페이지를 스크롤하고, 버튼을 누르고, 양식을 채우고, 스크린샷을 찍을 수 있습니다.

설치는 클로드 코드에게 "플레이라이트 CLI를 설치해줘"라고 말하면 됩니다. 에이전트가 필요한 패키지를 설치하고, 테스트 스크립트를 생성해서 브라우저가 정상적으로 열리는지 확인합니다.

■나 크롬 개발자 도구로 기능 오류를 자동 탐지하는 루프

14장에서 피트니스 코치 앱을 구축할 때, 게이미피케이션 포인트가 올라가지 않는 버그를 발견했습니다. 사람이 직접 앱을 사용하면서 찾아낸 것이었습니다.

브라우저 자동화를 사용하면 이 과정을 에이전트가 대신합니다. "웹 앱을 열고, 양식의 모든 필드를 채우고, 버튼을 클릭하고, 기능 오류가 있는지 확인해줘." 에이전트가 브라우저를 열어 실제 사용자처럼 앱을 사용합니다. 자바스크립트 에러, 네트워크 요청 실패, 예상과 다른 화면 전환을 감지합니다. 버그를 발견하면 스크린샷을 찍고, 원인을 진단하고, 코드를 수정합니다.

이 테스트-수정 루프를 반복하면, 배포 전에 대부분의 기능 오류가 잡힙니다.

■다 동적 콘텐츠 테스트에서 스크린샷 루프의 한계와 대안

12장에서 다룬 것처럼, 애니메이션이나 동적 콘텐츠가 있는 페이지에서는 스크린샷 기반 검증이 한계에 부딪힙니다. 스크린샷은 한 프레임만 포착하므로, 움직이는 요소를 정확히 평가할 수 없습니다.

대안은 두 가지입니다. 에이전트에게 "이 부분은 스크린샷 비교를 하지 마"라고 명시하는 것이 하나이고, 브라우저 자동화로 실제 인터랙션을 테스트하는 것이 다른 하나입니다. 버튼을 클릭했을 때 애니메이션이 시작되는지, 스크롤에 따라 요소가 나타나는지를 코드로 검증합니다.

30장 깃(Git)과 깃허브(GitHub) 핵심 개념

■가 리포지토리, 커밋, 브랜치, 푸시, 풀, 머지

은행 계좌를 떠올려 보십시오. 모든 거래 내역이 기록됩니다. 입금, 출금, 이체 날짜와 금액이 빠짐없이 남습니다. 깃(Git)은 코드를 위한 거래 장부입니다.

리포지토리(Repository)는 깃이 추적하는 프로젝트 폴더입니다. 모든 파일과 변경 이력을 담고 있습니다.

커밋(Commit)은 특정 시점의 스냅샷입니다. "로그인 기능 추가"라는 메시지와 함께 변경 사항을 기록합니다. 비디오 게임의 세이브 포인트와 같습니다.

브랜치(Branch)는 메인 코드에 영향을 주지 않고 실험할 수 있는 별도의 작업 공간입니다. 기본 브랜치는 보통 "main"이라고 부릅니다. 새 기능을 개발할 때 "feature-login" 같은 이름의 브랜치를 만들어 작업하고, 완성되면 메인에 합칩니다.

푸시(Push)는 로컬의 커밋을 깃허브(온라인)로 업로드하는 것입니다. 풀(Pull)은 깃허브의 최신 변경을 로컬로 가져오는 것입니다. 머지(Merge)는 한 브랜치의 변경 사항을 다른 브랜치에 합치는 것입니다.

■나 브랜치로 안전하게 실험하고 메인에 병합하는 워크플로우

이 개념들이 실무에서 어떻게 조합되는지 보겠습니다.

웹사이트 프로젝트에서 새 기능을 추가하고 싶습니다. 메인 브랜치에서 직접 작업하면, 실수가 생겼을 때 운영 중인 사이트에 즉시 반영될 위험이 있습니다. 대신 새 브랜치를 만듭니다. 이 브랜치에서 기능을 개발하고, 테스트합니다. 모든 것이 정상이면 메인 브랜치에 머지합니다. 버셀이 메인 브랜치의 변경을 감지해서 자동으로 배포합니다.

이 워크플로우가 전문 개발 팀이 사용하는 표준 방식입니다. 클로드 코드는 이 과정을 잘 이해하고 있어서, "새 브랜치를 만들어줘", "이 변경 사항을 커밋해줘", "메인에 머지해줘"라는 자연어 지시만으로 처리합니다.

■다 클로드 코드와 GitHub의 연동: 커밋 자동화

15장에서 클로드 코드와 깃허브를 연동하는 방법을 이미 다뤘습니다. 여기서 강조하고 싶은 것은 커밋 자동화입니다. 에이전트에게 "변경 사항을 커밋하고 깃허브에 푸시해줘"라고 말하면, 에이전트가 변경된 파일을 감지하고, 의미 있는 커밋 메시지를 작성하고, 푸시합니다.

커밋 메시지를 에이전트가 자동으로 작성하는 것이 의외로 유용합니다. "히어로 섹션에 글로우 효과 추가" 같은 설명적인 메시지가 붙어서, 나중에 변경 이력을 추적할 때 각 커밋이 무엇을 했는지 쉽게 파악됩니다.

이것으로 제8부가 마무리됩니다. 32가지 해킹 팁, 브라우저 자동화, 깃과 깃허브의 핵심까지 다뤘습니다. 도구를 날카롭게 가다듬는 기법을 익혔으니, 이제 이 모든 역량을 수익으로 전환하는 단계로 넘어갑니다. 제9부에서는 첫 클라이언트를 7일 안에 확보하는 프레임워크, 가치 기반 가격 책정, 워크플로우 테스트와 QA, 핸드오버와 유지보수, 그리고 실제 사례 연구를 다룹니다.

31장 세 가지 심리적 장벽 넘기

■가 임포스터 신드롬: 무료 또는 저가 파일럿으로 실전 경험 쌓기

거울 앞에 서면 보입니다. "내가 정말 이걸로 돈을 받아도 되는 걸까." 에이전틱 워크플로우를 구축하는 법을 배웠고, 데모 프로젝트도 만들어 보았지만, 클라이언트 앞에 서는 것은 전혀 다른 문제입니다. 이 감정에 이름이 있습니다. 임포스터 신드롬(Imposter Syndrome), 자신이 자격 없는 사기꾼이라는 느낌입니다.

미국의 한 AI 자동화 컨설턴트는 이 장벽을 이렇게 넘었습니다. 그의 커뮤니티에서 5일 만에 첫 클라이언트를 확보한 21세 청년은 처음부터 솔직했습니다. "저는 이 분야에 막 들어왔습니다. 배우는 것에 빠져 있고, 많이 만들어 보고 있습니다. 당신의 이 문제를 해결해 드리고 싶습니다." 이런 솔직함은 약점이 아니라 패턴 인터럽트(Pattern Interrupt)입니다. 상대방은 매일 판매 메시지를 받습니다. "저는 새로운데 도와드리고 싶습니다"라는 말은 진짜 사람의 목소리처럼 들립니다.

초기 한두 건의 프로젝트는 무료 또는 매우 저렴한 가격으로 진행합니다. 이것은 자선이 아닙니다. 투자입니다. 여러분이 투자하는 것은 시간이고, 돌려받는 것은 실전 경험, 사례 연구(Case Study), 그리고 자신감입니다. 클라이언트에게는 이렇게 제안합니다. "무료로 작은 자동화를 하나 만들어 드리겠습니다. 결과물은 어떻든 당신 것입니다. 제가 부탁드리는 것은 솔직한 피드백뿐입니다."

리스크가 0인 제안을 거절할 이유는 거의 없습니다. 그리고 그 한 건의 프로젝트가 끝나고 나면, 여러분은 "해본 적 있다"고 말할 수 있는 사람이 됩니다. 임포스터 신드롬은 경험으로만 녹습니다.

■나 가격 집착: 첫 클라이언트 전에 리테이너를 고민하지 않기

두 번째 장벽은 가격에 대한 조급함입니다. 아직 첫 프로젝트도 시작하지 않았는데, 월 리테이너(Retainer, 월정액 계약) 구조를 고민하고, 월 매출 1,000만 원 달성 로드맵을 그리는 사람들이 있습니다.

리테이너는 신뢰 위에 서는 건물입니다. 신뢰를 쌓기 전에 건물을 올리려 하면 무너집니다. 첫 프로젝트의 목표는 수익 극대화가 아닙니다. 가치를 전달하고, 그 가치를 숫자로 증명하고, 관계를 만드는 것입니다. 리테이너는 가치가 증명된 뒤에, 클라이언트가 "계속 같이 하고 싶다"고 말할 때 자연스럽게 제안하는 것입니다.

■다 과도한 준비: 완벽한 포트폴리오 없이도 시작할 수 있다

세 번째 장벽은 완벽주의입니다. "포트폴리오를 좀 더 다듬어야 해", "웹사이트를 먼저 만들어야 해", "사례 연구가 세 개는 있어야 해." 이런 생각이 시작을 무한히 미루게 합니다.

앞서 언급한 21세 청년은 웹사이트도 없었습니다. 포트폴리오도 없었습니다. 그가 가진 것은 배운 지식, 솔직함, 그리고 대화를 시작할 용기뿐이었습니다. 그리고 5일 만에 첫 클라이언트를 확보했습니다.

완벽한 준비란 없습니다. 첫 프로젝트가 완벽하지 않아도 됩니다. 중요한 것은 시작하는 것, 그리고 매 프로젝트에서 배우고 개선하는 것입니다.

32장 7일 클라이언트 확보 프레임워크

■가 1일차: 느슨한 방향 설정과 20명의 잠재 연락처 목록 작성

첫째 날의 목표는 두 가지입니다. 대략적인 방향을 정하는 것과, 연락할 사람 20명의 목록을 만드는 것입니다.

방향 설정은 "초정밀 니치(Niche)"가 아닙니다. "저는 중소기업의 반복 업무를 AI로 자동화해 드립니다" 정도면 충분합니다. 이 단계에서는 어떤 업종에 집중할지를 확정하는 것이 아니라, 대화를 시작할 수 있는 문장 하나를 만드는 것입니다.

목록은 구글 시트에 작성합니다. 이름, 업종, 관계의 강도(직접 아는 사람인지, 지인의 지인인지), 잠재적 역할(직접 클라이언트가 될 수 있는지, 누군가를 소개해 줄 수 있는지)을 기록합니다. 사업을 운영하는 친구, 전 직장 동료, 커뮤니티에서 알게 된 사람, 링크드인(LinkedIn) 연결. 20명을 채우는 것이 생각보다 어렵지 않다는 것을 알게 될 것입니다.

■나 2~3일차: 5~10회의 따뜻하고 부담 없는 대화

(1) 차가운 아웃리치가 아니라 신뢰 기반 접근

목록에서 5~10명에게 연락합니다. 판매 전화가 아닙니다. 호기심 있는 사업가로서 대화를 요청하는 것입니다.

메시지는 간결하게 씁니다. "저는 AI로 반복 업무를 자동화하는 사업을 시작하려 합니다. 아무것도 팔려는 것이 아닙니다. 15분만 대화할 수 있을까요? 일상에서 수작업으로 느껴지는 부분이 어디인지 듣고 싶습니다."

(2) "일상에서 수작업으로 느껴지는 부분이 어디인가요?"라는 질문

대화에서 핵심 질문은 하나입니다. "매주 반복하는 작업 중에, 누군가 대신해 주면 좋겠다고 느끼는 것이 있나요?" 이 질문이 고충(Pain Point)을 드러냅니다. 리드 관리에 매주 다섯 시간을 쓴다, 고객 온보딩이 너무 느리다, 데이터 입력을 수작업으로 한다. 이런 대답이 나옵니다. 모든 대화의 핵심 내용을 기록합니다.

■다 4~5일차: 대화에서 나온 고충을 작은 파일럿으로 전환

기록을 되짚어 봅니다. 가장 명확하고, 가장 고통스러운 반복 작업을 겪고 있는 사람을 고릅니다. 그리고 아주 작고 리스크가 낮은 파일럿을 제안합니다.

"지난번 대화에서 말씀하신 리드 후속 연락 자동화를 무료 파일럿으로 만들어 보고 싶습니다. 결과물은 당신 것이고, 저는 솔직한 피드백만 부탁드립니다."

파일럿의 범위를 가능한 한 좁게 잡습니다. 하나의 프로세스, 하나의 자동화, 하나의 결과물. 거대한 시스템이 아니라, 작지만 측정 가능한 개선을 목표로 합니다.

■라 6일차: 최소 기능 제품(MVP) 빌드

파일럿을 구축합니다. 이 책에서 배운 모든 것이 여기서 적용됩니다. 플랜 모드에서 에이전트와 계획을 세우고, 워크플로우와 도구를 만들고, 테스트합니다. 복잡하게 만들지 않습니다. 클라이언트가 "이것 때문에 시간이 절약되었다"고 느낄 수 있는 최소한의 기능만 구현합니다.

빌드가 끝나면 룸(Loom, 화면 녹화 서비스)으로 2~3분짜리 워크스루 영상을 녹화합니다. 자동화가 작동하는 모습을 보여주고, 어떤 문제를 어떻게 해결하는지 설명합니다.

■마 7일차: 파일럿 결과 리뷰와 다음 단계 협의

클라이언트와 함께 파일럿 결과를 검토합니다. 자동화가 절약해 준 시간, 줄여준 수작업, 개선된 정확도를 수치로 보여줍니다.

(1) 같은 클라이언트와 유지보수 또는 기능 확장

결과가 좋으면 다음 단계를 제안합니다. 유지보수(자동화를 유지하고 작은 수정을 처리하는 것)나 기능 확장(새로운 자동화를 추가하는 것) 중 적절한 옵션을 제시합니다.

(2) 영상 추천서(Video Testimonial) 요청 타이밍

클라이언트가 결과에 만족한 것이 확인된 뒤에, 짧은 영상 추천서를 부탁합니다. "30초짜리 영상으로 이 자동화가 어떻게 도움이 되었는지 말씀해 주실 수 있을까요?" 이 추천서가 다음 클라이언트를 확보할 때 가장 강력한 무기가 됩니다.

■바 이 사이클은 한 번이 아니라 반복이다

7일 프레임워크는 일회성이 아닙니다. 순환입니다. 첫 번째 사이클에서 경험을 쌓고, 두 번째 사이클에서 언어를 다듬고, 세 번째 사이클에서 자신감이 붙습니다. 사이클이 반복될수록 대화가 자연스러워지고, 제안이 정교해지고, 전환율이 올라갑니다.

33장 가치 기반 가격 책정(PRICE 프레임워크)

■가 P(Prepare): 비즈니스 고충을 시간과 비용 숫자로 환산하기

(1) 주당 낭비 시간 × 인건비 × 52주 = 연간 손실액

자동화할 프로세스가 매주 직원의 시간을 10시간 잡아먹는다고 합시다. 그 직원의 시급이 25달러(한화 약 34,000원)라면, 주당 250달러, 월 1,000달러, 연간 약 13,000달러(한화 약 1,780만 원)의 비용입니다.

(2) 워크플로우가 절감하는 비율 산출

여러분의 자동화가 이 프로세스의 60%를 처리할 수 있다면, 연간 절감액은 약 7,800달러(한화 약 1,070만 원)입니다.

■나 R(Research): 업종별 벤치마크와 경쟁 가격 조사

동종 업계에서 비슷한 자동화 서비스가 어떤 가격대에 거래되는지 조사합니다. 시장 가격을 알아야 자신의 가격이 적절한지 판단할 수 있습니다.

■다 I(Itemize): 산출 가치의 10~20%를 기준 가격으로 설정

경험 법칙(Rule of Thumb)은 이렇습니다. 클라이언트가 첫 해에 투자 대비 10배의 수익을 볼 수 있어야 합니다. 연간 절감액이 7,800달러라면, 프로젝트 비용을 780달러(약 10%) 선에서 시작합니다. 경험이 쌓이고 사례 연구가 늘어나면 15~20%까지 올릴 수 있습니다.

이 계산을 클라이언트 앞에서 투명하게 보여주는 것이 핵심입니다. "이 프로세스에 연간 13,000달러가 소비됩니다. 제 자동화가 60%를 절감하면 7,800달러를 아끼게 됩니다. 제 비용은 780달러입니다. 첫 달에 투자금을 회수하고, 나머지 11개월은 순이익입니다." 이 수학을 들으면 가격이 비용이 아니라 투자로 인식됩니다.

■라 C(Communicate): 가격을 말하기 전에 솔루션의 가치를 먼저 전달

숫자를 말하기 전에, 자동화가 적용된 뒤의 모습을 먼저 그려줍니다. "매주 월요일 아침, 더 이상 리드 목록을 수작업으로 정리하지 않아도 됩니다. 시스템이 자동으로 분류하고, 우선순위 높은 리드만 담당자에게 전달합니다." 클라이언트가 그 미래를 상상한 뒤에 가격을 제시하면, 숫자의 무게가 달라집니다.

■마 E(Evolve): QA 완료 후 유지보수 리테이너로 전환하는 경로

프로젝트가 완료된 뒤에도 관계는 계속됩니다. 유지보수 리테이너를 제안합니다. API 변경, 모델 업데이트, 소규모 기능 수정을 월정액으로 처리합니다. 원래 프로젝트 비용의 10~25% 수준이 적정선입니다.

34장 워크플로우 테스트와 QA

■가 클라이언트의 실제 데이터로 테스트 데이터 설계하기

가상 데이터로 테스트하면 가상의 버그만 찾습니다. 클라이언트에게 실제 업무 데이터의 샘플을 요청합니다. 이메일 원본, CRM 레코드, 지원 티켓. 개인정보가 포함된 경우 익명화 처리 후 사용합니다. 실제 데이터는 실제 엣지 케이스를 드러냅니다.

■나 내부 QA: 최악의 시나리오와 엣지 케이스를 의도적으로 탐색

개발자처럼 "정상 작동"만 확인하는 것이 아니라, 엔지니어처럼 "어디서 깨지는지"를 찾습니다. 빈 데이터, 중복 데이터, 예상 밖의 형식, 비정상적으로 큰 입력값을 의도적으로 넣어봅니다. 깨지는 방식이 안전한지(조용히 멈추는지, 오류 알림을 보내는지) 확인합니다.

■다 프롬프트와 모델 조합별 A/B 테스트

AI가 포함된 워크플로우에서는 프롬프트 문구와 모델 선택에 따라 출력 품질이 크게 달라집니다. 같은 입력 데이터에 대해 프롬프트 A와 프롬프트 B를 각각 실행해 보고, 어느 쪽이 더 정확하고 일관된 결과를 내는지 비교합니다.

■라 클라이언트 대면 QA: 체계적 피드백 수집 방법

내부 QA를 마친 뒤 클라이언트에게 테스트 환경을 제공합니다. 간단한 양식이나 채팅 인터페이스를 통해 직접 사용해 보게 합니다. 피드백은 체계적으로 수집합니다. "출력의 정확도는?", "어조는 적절한가?", "포맷은 마음에 드는가?" 항목별로 평가를 받습니다.

■마 QA 결과가 신뢰를 쌓는 증거가 되는 이유

테스트 과정과 결과를 문서로 정리합니다. 몇 건의 샘플을 테스트했는지, 어떤 엣지 케이스를 발견했는지, 어떻게 수정했는지. 이 문서를 클라이언트에게 공유하면, "이 사람은 꼼꼼하게 일한다"는 신뢰가 쌓입니다. 다음 프로젝트 수주 확률이 높아지고, 리테이너 전환이 자연스러워집니다.

35장 핸드오버와 유지보수

■가 핸드오버에 영향을 주는 두 가지 변수

(1) 클라이언트 계정에서 구축했는가, 나의 인프라에서 구축했는가

클라이언트의 깃허브, 트리거닷데브, 또는 클라우드 환경에서 직접 구축했다면 핸드오버가 간단합니다. 모든 것이 이미 클라이언트 소유입니다. 여러분의 테스트용 인증 정보를 클라이언트 것으로 교체하면 됩니다.

여러분의 인프라에서 구축했다면, 코드와 설정을 클라이언트 환경으로 이전하는 작업이 필요합니다.

(2) 프로젝트 종료인가, 추가 작업이 예정되어 있는가

프로젝트가 완전히 종료되면 핸드오버가 최종적이어야 합니다. 모든 문서, 코드, 인증 정보가 깔끔하게 정리되어 전달됩니다. 추가 작업이 예정되어 있다면 테스트 환경을 유지해 둡니다.

■나 테스트 환경과 프로덕션 환경 분리

소프트웨어 개발의 기본 원칙을 따릅니다. 테스트 환경에서 실험하고, 확인이 끝난 것만 프로덕션(Production, 실제 운영) 환경으로 옮깁니다. 클라이언트에게 이 개념을 설명합니다. "수정이 필요할 때 실제 시스템을 건드리지 않습니다. 테스트 환경에서 먼저 확인한 뒤에 반영합니다."

■다 납품물 구성: Loom 워크스루 영상, 기술 문서, 크레덴셜 정리

핸드오버 시 전달할 납품물을 정리합니다. 룸 워크스루 영상(시스템 작동 방식과 설정 방법을 화면 녹화로 설명), 기술 문서(워크플로우 구조, 사용된 도구, 설정 항목 목록), 크레덴셜 정리(어떤 API 키가 필요하고, 어디에 저장되어 있는지).

이 문서들은 여러분이 떠난 뒤에도 클라이언트 팀이 시스템을 이해하고 관리할 수 있게 해줍니다.

■라 유지보수 리테이너 설계

(1) 모니터링, 모델 업데이트, 소규모 수정 포함 범위

유지보수 리테이너에 포함되는 항목을 명확히 합니다. 시스템 모니터링, AI 모델 업데이트 시 호환성 확인, 소규모 버그 수정, 외부 API 변경 대응. 새로운 기능 추가나 대규모 리팩토링은 별도 프로젝트로 구분합니다.

(2) 리테이너 계약서에 명시할 항목

서비스 범위(포함 항목과 제외 항목), 응답 시간(긴급 장애는 몇 시간 이내, 일반 요청은 며칠 이내), 기간과 갱신 조건, 비용과 결제 조건, 종료 시 핸드오버 절차. 이 항목들을 서면으로 명확히 해두면 양측 모두 보호됩니다.

■마 보안과 데이터 프라이버시 점검

클라이언트의 데이터를 다루는 모든 워크플로우에서 보안은 필수 점검 항목입니다. API 키가 코드에 하드코딩되어 있지 않은지, .env 파일이 깃허브에 올라가지 않는지, 웹훅 엔드포인트에 인증이 걸려 있는지 확인합니다.

개인정보를 처리하는 경우, GDPR(EU 일반 데이터 보호 규정)이나 한국의 개인정보 보호법 등 관련 법률을 준수해야 합니다. 데이터 최소화(필요한 정보만 수집), 접근 권한 제한(관련자만 로그 열람 가능), 데이터 삭제 요청 대응 절차를 마련합니다.

36장 크리스천(Christian) 사례 연구

■가 대량 콜드 아웃리치에서 5일 만에 첫 클라이언트로 전환한 과정

미국 애리조나에 사는 21세 청년이 있었습니다. AI에 관심을 갖기 시작한 것은 불과 몇 달 전이었습니다. 처음에는 링크드인에서 리드를 스크래핑하고, AI로 이메일 본문을 생성하고, 하루 450통씩 콜드 이메일을 발송했습니다. 오픈율은 높았지만 아무도 사지 않았습니다. 낯선 사람이 보낸 템플릿 광고에 반응할 이유가 없었습니다.

그가 AI 자동화 커뮤니티에 합류하면서 접근법이 바뀌었습니다. "워크플로우를 팔지 마라. 성과를 팔아라." 이 한마디가 전환점이었습니다. 그는 아는 사람에게 따뜻한 대화를 시작했고, 건설업체의 프로젝트 매니저가 고객 소통에 많은 시간을 쓰고 있다는 것을 알게 되었습니다. PM 어시스턴트 챗봇을 무료 파일럿으로 제안했습니다. 5일 뒤 유료 계약으로 전환되었습니다. 월 1,500달러(한화 약 205만 원)로 시작해서, 이후 2,000달러(한화 약 274만 원)로 올랐습니다.

■나 "워크플로우를 판다"에서 "비즈니스 성과를 판다"로의 마인드셋 전환

그가 바꾼 것은 도구가 아니라 언어였습니다. "제가 만든 이 자동화를 보세요"가 아니라, "이 시스템이 당신의 사업에서 이런 결과를 만들어 줍니다." 자동화의 노드 수나 API 호출 구조를 설명하는 대신, 절약되는 시간과 줄어드는 오류를 이야기했습니다. 기술에 감탄하는 것은 개발자이고, 성과에 지갑을 여는 것은 사업가입니다.

■다 커뮤니티 게시 한 건이 두 번째 클라이언트로 이어진 경위

첫 클라이언트를 확보한 뒤, 그는 커뮤니티에 경험담을 게시했습니다. 무엇을 했는지, 어떤 결과가 나왔는지, 어떤 교훈을 얻었는지. 이 게시물을 읽은 다른 커뮤니티 회원이 연락했습니다. "저도 AI 자동화 개발자를 찾고 있었는데, 당신이 딱 맞을 것 같습니다." 3일 뒤 두 번째 클라이언트가 확정되었습니다.

콜드 이메일 450통이 만들지 못한 것을, 커뮤니티 게시물 한 건이 만들어냈습니다. 신뢰가 이미 존재하는 공간에서, 진솔한 경험 공유가 가장 강력한 마케팅이었습니다.

이것으로 제9부가 마무리됩니다. 심리적 장벽을 넘는 방법, 7일 만에 첫 클라이언트를 확보하는 프레임워크, 가치 기반으로 가격을 책정하는 PRICE 모델, 워크플로우의 품질을 보증하는 QA 프로세스, 전문적인 핸드오버와 유지보수, 그리고 실제 사례 연구까지. 기술을 수익으로 전환하는 전체 경로를 밟았습니다.

제10부에서는 이 책의 여정을 한 장의 지도로 압축하고, 학습을 멈추지 않기 위한 커뮤니티와 리소스를 안내합니다.

37장 이 책에서 배운 것의 전체 지도

■가 WAT 프레임워크에서 수익화까지의 여정 요약

한 권의 책을 덮기 전에, 지나온 길을 한번 되돌아봅니다.

출발점은 빈 폴더 하나였습니다. VS Code를 열고, 아무것도 없는 탐색기를 바라보던 순간. 거기서부터 시작해서, 여러분은 에이전틱 AI라는 산업이 어떤 속도로 팽창하고 있는지 숫자로 확인했습니다. 78억 달러에서 500억 달러를 향해 달려가는 시장. 기업의 25%가 이미 파일럿을 시작했고, 2027년에는 절반이 운영할 것이라는 전망. 이 숫자들은 여러분이 배운 기술이 단순한 취미가 아니라 실질적인 경제적 가치를 지닌다는 것을 말해줍니다.

WAT 프레임워크가 뼈대를 제공했습니다. 워크플로우라는 자연어 지침서, 에이전트라는 판단의 주체, 도구라는 실행의 손. 이 세 계층이 분업하는 구조를 이해한 것이 모든 것의 기초였습니다. 레시피와 재료와 셰프의 관계. 이 비유가 처음 등장한 2장에서부터, 22장의 모닝커피 스킬까지, WAT 프레임워크는 한 번도 무대를 떠나지 않았습니다.

환경을 설정했습니다. VS Code를 설치하고, 클로드 코드 확장을 연결하고, claude.md로 에이전트에게 프로젝트의 맥락을 주었습니다. 토큰과 컨텍스트 윈도우의 원리를 배워서, 에이전트의 작업 메모장이 어떻게 채워지고 비워지는지 이해했습니다. 모델 선택 전략으로 비용과 품질 사이의 균형점을 잡는 법을 익혔습니다.

프로젝트를 설계하고 핵심 기능을 연결했습니다. 슬래시 명령어로 에이전트를 제어하고, 폴더 아키텍처로 프로젝트를 정돈하고, RAG와 벡터 데이터베이스로 외부 지식을 에이전트의 손이 닿는 곳에 놓았습니다.

웹사이트와 앱을 만들었습니다. 참조 사이트를 클론하고, 스크린샷 루프로 에이전트가 자기 결과물을 눈으로 검증하게 했습니다. 21st.dev의 컴포넌트로 세부 요소를 다듬고, AI 피트니스 코치 웹 앱을 처음부터 끝까지 구축했습니다. 깃허브와 버셀을 연결해서 코드를 세상에 배포했습니다. 여러분이 만든 것을 스마트폰에서 접속하는 순간을 경험했습니다.

도구를 연동하고 워크플로우를 배포했습니다. MCP 서버로 에이전트에게 외부 서비스의 문을 열어주고, 스킬로 전문 지식을 캡슐화하고, GWS CLI로 구글 워크스페이스 전체를 하나의 인터페이스에서 다뤘습니다. 모달과 트리거닷데브로 워크플로우를 클라우드에 올려서, 여러분이 자고 있는 동안에도 자동으로 실행되게 했습니다.

AI 이그제큐티브 어시스턴트를 구축했습니다. 네 단계 프레임워크, 집-생명-손-성장을 따라가며, 매일 아침 하루를 계획해 주고, 이메일 우선순위를 매기고, 팀 현황을 브리핑하는 에이전트를 만들었습니다. 모닝커피 스킬과 펄스체크 스킬을 실전으로 운용하고, 스킬 크리에이터로 스킬 생성 자체를 자동화했습니다.

서브에이전트와 에이전트 팀으로 규모를 키웠습니다. 전문화된 에이전트에게 작업을 위임하고, 여러 에이전트가 병렬로 협업하는 구조를 구축했습니다. 하나의 요청이 다섯 개의 에이전트로 분산되어 동시에 처리되는 경험을 했습니다.

32가지 해킹 팁으로 일상의 작업을 가다듬었습니다. 플랜 모드에서 시작하는 습관, 컨텍스트를 60%에서 압축하는 규율, 깃 워크트리로 병렬 세션을 운영하는 기법, VPS에서 24시간 에이전트를 가동하는 설정까지. 브라우저 자동화로 에이전트가 웹을 직접 조작하게 하고, 깃과 깃허브로 코드를 안전하게 관리하는 원칙을 세웠습니다.

마지막으로, 이 모든 역량을 수익으로 전환하는 길을 밟았습니다. 임포스터 신드롬을 넘는 법, 7일 안에 첫 클라이언트를 확보하는 프레임워크, PRICE 모델로 가치 기반 가격을 책정하는 법, QA로 품질을 보증하는 법, 전문적인 핸드오버와 유지보수 리테이너를 설계하는 법. 그리고 5일 만에 첫 클라이언트를 확보한 실제 사례를 통해, 이론이 현실에서 작동한다는 것을 확인했습니다.

빈 폴더에서 시작해서, 수익을 창출하는 에이전틱 시스템을 구축하고 운영하는 전문가로 성장하는 여정. 이것이 이 책의 전체 지도입니다.

■나 학습 루프: 빌드, 테스트, 배포, 피드백, 반복

이 여정에서 반복적으로 등장한 패턴이 하나 있습니다. 빌드(Build), 테스트(Test), 배포(Deploy), 피드백(Feedback), 반복(Repeat). 이 다섯 단계의 순환이 모든 장을 관통합니다.

뉴스레터 자동화를 구축하고, 실행해 보고, HTML이 깨진 것을 발견하고, 수정해서 다시 보내고, 결과를 확인하는 과정. 경쟁사 분석 워크플로우를 만들고, PDF 보고서의 로고가 보이지 않는 것을 발견하고, 수정하고 다시 생성하는 과정. 피트니스 코치 앱을 구축하고, 게이미피케이션 포인트가 올라가지 않는 버그를 찾고, 수정하고, 다시 테스트하는 과정. 첫 클라이언트에게 파일럿을 전달하고, 피드백을 받고, 개선하고, 유료 계약으로 전환하는 과정.

형태는 다르지만 구조는 같습니다. 만들고, 확인하고, 고치고, 다시 만듭니다. 이 순환이 빠르게 돌수록 결과물의 품질이 올라갑니다. 에이전틱 시스템의 핵심 강점이 바로 이 순환의 속도입니다. 전통적인 방식으로 한 바퀴 도는 데 며칠이 걸리던 것이, 클로드 코드에서는 몇 분 안에 한 바퀴를 돕니다.

이 패턴은 책을 덮은 뒤에도 계속됩니다. 새로운 프로젝트를 시작할 때마다, 새로운 클라이언트를 만날 때마다, 새로운 기술이 등장할 때마다. 빌드-테스트-배포-피드백-반복. 이 다섯 단어가 여러분의 작업 리듬이 됩니다.

38장 AI Automation Society와 다음 단계

■가 커뮤니티 자원과 네트워킹의 가치

기술을 배우는 것과 기술을 사업으로 전환하는 것 사이에는 간극이 있습니다. 이 간극을 혼자 건너는 것은 가능하지만, 같은 길을 걷는 사람들과 함께 건너는 것이 훨씬 빠르고 덜 외롭습니다.

에이전틱 AI와 클로드 코드를 다루는 온라인 커뮤니티가 빠르게 성장하고 있습니다. 수십만 명의 회원이 워크플로우 템플릿, 스킬 파일, claude.md 예시, 문제 해결 경험을 공유합니다. 누군가가 "이 MCP 서버 연결에서 오류가 나요"라고 질문하면, 같은 문제를 겪고 해결한 사람이 답합니다. 혼자 삽질하면 두 시간 걸릴 문제가 커뮤니티에서 10분 만에 풀립니다.

커뮤니티의 가치는 기술적 도움에 그치지 않습니다. 36장의 사례에서 보았듯이, 첫 클라이언트를 확보한 경험을 커뮤니티에 공유한 게시물 하나가 두 번째 클라이언트로 이어졌습니다. 같은 목표를 가진 사람들이 모인 공간에서, 여러분의 경험담은 다른 사람에게 영감이 되고, 다른 사람의 경험담은 여러분에게 실질적 기회가 됩니다.

이 책에서 다룬 도구와 기법은 이 책을 집필하는 시점의 스냅샷입니다. 기술은 빠르게 진화합니다. 클로드 코드의 새 기능이 추가되고, MCP 서버 생태계가 확장되고, 스킬 라이브러리가 풍부해지고, 배포 플랫폼이 더 편리해집니다. 커뮤니티에 참여하면 이 변화를 실시간으로 따라갈 수 있습니다. 혼자 문서를 읽고 실험하는 것보다, 수천 명이 동시에 실험하고 결과를 공유하는 환경에서 배우는 것이 압도적으로 효율적입니다.

■나 지속적 학습: 모델 진화, 새로운 MCP 서버, 도구 업데이트에 대응하기

이 책을 덮는 순간, 여러분에게 두 가지 선택지가 있습니다.

첫 번째는 배운 것을 그대로 사용하는 것입니다. 이 책에서 익힌 WAT 프레임워크, 스킬 구축법, 배포 전략, 가격 책정 모델은 상당 기간 유효합니다. 당장 프로젝트를 시작하고, 클라이언트를 확보하고, 수익을 만들어낼 수 있습니다.

두 번째는 배운 것을 기반으로 계속 진화하는 것입니다. AI 모델은 몇 달마다 새 버전이 나옵니다. 하이쿠, 소네, 오퍼스의 성능 곡선이 달라집니다. 17장에서 배운 프런트엔드 디자인 스킬이 새 모델에서는 불필요해질 수 있습니다. 반대로, 이전 모델에서 불가능했던 작업이 새 모델에서는 가능해질 수 있습니다. 22장에서 다룬 스킬 크리에이터의 이밸 기능으로 기존 스킬의 유효성을 주기적으로 검증하면, 모델 변화에 뒤처지지 않습니다.

MCP 서버 생태계도 빠르게 넓어지고 있습니다. 이 책에서 다룬 파이어크롤, 지메일, 캘린더, 드라이브 외에도, 슬랙(Slack), 노션(Notion), 아사나(Asana), 세일즈포스(Salesforce) 등 다양한 서비스의 MCP 서버가 등장하고 있습니다. 새 MCP 서버를 연결하는 방법은 16장에서 배운 것과 동일합니다. 원리를 알면 새 도구에 적응하는 것은 반복의 문제일 뿐입니다.

배포 환경도 변화합니다. 모달과 트리거닷데브 외에도 새로운 서버리스 플랫폼이 등장할 수 있습니다. 클로드 코드 데스크톱 앱의 스케줄 태스크 기능이 진화하면, 별도 배포 플랫폼 없이도 자동 실행이 가능해질 수 있습니다. 변화를 감지하는 가장 좋은 방법은 클로드 코드 공식 문서(docs.anthropic.com)를 주기적으로 확인하고, 커뮤니티에서 공유되는 실전 경험을 따라가는 것입니다.

이 책의 마지막 문장을 이렇게 맺겠습니다.

여러분은 이제 빈 폴더에서 시작해서, 에이전틱 워크플로우를 설계하고, 구축하고, 배포하고, 수익화하는 전체 과정을 손에 쥐고 있습니다. 클로드 코드 채팅창의 커서가 깜빡이고 있습니다. 다음에 입력할 문장은 여러분의 것입니다.