포토/동영상 (1)
|
안녕하세요? 정리하는 개발자 워니즈입니다. 필자도 요즘은 터미널에 AI 에이전트를 띄워놓고 하루를 시작합니다. 그런데 일을 맡길수록 이상한 지점에서 막힙니다. 코드를 못 짜서가 아니라, 시키지도 않은 파일까지 건드려놓고 “완료했습니다”라고 보고하기 때문입니다. 이번 시간에는 그 문제를 정면으로 다루는 클로드 코드 에이전틱 코딩을 읽고 서평을 하도록 하겠습니다. 이 책은 한빛미디어에서 2026년 8월 31일에 나온 244쪽짜리 실전 가이드입니다. 지은이 이행철 님은 두 번의 CTO와 두 번의 창업을 거친 분이고, 지금은 에이전틱 AI 중심으로 소프트웨어를 만들고 계십니다. 제목만 보면 클로드 코드 사용법 책 같은데, 실제로 읽어보면 절반 이상이 AI에게 일을 맡기는 방법에 관한 이야기입니다. 이 글에서 알 수 있는 것
바이브 코딩과 에이전틱 코딩은 무엇이 다를까요?두 방식의 차이는 개발을 누가 주도하느냐에 있습니다. 바이브 코딩은 “이 기능 추가해줘”라고 요청하고 결과를 확인해 다시 요청하는 방식이라 사람이 계속 운전대를 잡고 있습니다. 에이전틱 코딩은 사람이 무엇을 만들지와 완료 기준만 정해주고, 구현 방법을 찾고 코드를 쓰고 테스트하고 고치는 과정은 AI가 스스로 반복합니다. 책은 이 차이를 건축에 빗대어 설명합니다. 벽 색을 하나씩 지시하는 쪽이 바이브 코딩이고, 어떤 건물을 원하는지 말하면 설계와 시공을 맡기는 쪽이 에이전틱 코딩입니다.
같은 도구를 쓰더라도 지시 방식이 다르면 결과가 갈립니다. 바이브 코딩 쪽 흐름은 조코딩의 바이브 코딩 1인 창업 서평에서 다룬 적이 있습니다. 그러면 본격적으로 각 단원별 내용을 정리하고 서평하도록 하겠습니다. 『클로드 코드 에이전틱 코딩』 목차PART 1 클로드 코드 기초 다지기
PART 2 에이전틱 코딩으로 실제 제품 개발하기
PART 3 클로드 코드 능력 확장하기, 스킬과 서브에이전트와 에이전트 팀즈
PART 4 자동으로 지키고 자동으로 실행하기, 훅
PART 5 실전에서 달라지는 것, 더 많이 맡기되 고삐를 쥐는 법
『클로드 코드 에이전틱 코딩』 챕터별 간단 서평PART 1 클로드 코드 기초 다지기CHAPTER 1 클로드 코드 설치에서 코드 작성까지설치 명령 한 줄에서 시작해 대화, 계획, 실행, 검증이라는 기본 루프를 한 바퀴 돌아보는 장입니다. 설명을 다 이해하지 않아도 되니 일단 완주하라고 못을 박아둔 점이 좋았습니다. Plan 모드에서 계획을 먼저 세우고 승인한 다음에 파일을 건드리게 하는 습관을 이 장에서 들이게 됩니다. 이 장에서 배운 것: 체크포인트는 클로드 코드가 직접 편집한 파일만 추적하므로 한 줄 요약: 계획과 실행을 분리하는 것이 에이전틱 코딩의 첫 번째 습관입니다. CHAPTER 2 원하는 것만 만들게 하는 프롬프트 설계“아바타 업로드만 붙여줘”라고 했는데 스토리지 유틸리티가 새로 생기고 관계없는 폼 컴포넌트까지 리팩터링되는 경험, 다들 있으실 겁니다. 이 장은 그 현상을 버그가 아니라 구조로 설명합니다. 시스템 프롬프트 안에 야심찬 작업을 허용하라는 지침과 과도한 엔지니어링을 막으라는 지침이 함께 들어 있고, 그 긴장이 범위 확장으로 나타난다는 것입니다. 해법은 범위 고정 프롬프트이고 작업 목적, 구현 범위, 구현 제외 범위, 제약 조건, 완료 기준 다섯 항목으로 정리됩니다. 이 장에서 배운 것: 제외 범위는 “안 만들 것”을 적는 칸이 아니라 “말 안 하면 AI가 알아서 만들어버릴 것”을 적는 칸입니다. 한 줄 요약: 경계가 명확할수록 AI는 그 안에서 더 집중합니다. CHAPTER 3 프로젝트 생성하기, 빈 폴더에서 실행 성공까지빌드가 성공하고 테스트가 통과하고 개발 서버가 뜨는 상태를 그린 빌드라고 부르고, 여기까지 도달하는 것을 이 장의 목표로 잡습니다. CLI 제너레이터가 있는 프레임워크라면 폴더 구조를 일일이 지정하지 말고 제너레이터를 쓰게 하라는 조언이 실용적이었습니다. 시크릿 관리를 프로젝트 생성 직후에 배치한 구성도 마음에 들었습니다. 이 장에서 배운 것: 한 줄 요약: 기능을 쌓기 전에 “여기까지는 확실히 작동한다”는 증거를 먼저 만듭니다. CHAPTER 4 클로드 코드에게 프로젝트 지침 주기, CLAUDE.md『클로드 코드 에이전틱 코딩』에서 가장 밑줄을 많이 그은 장입니다. 이 장에서 배운 것: CLAUDE.md의 규칙은 강제가 아니라 권고이고, 세션이 길어지거나 작업이 복잡해질수록 준수율이 떨어집니다. 한 줄 요약: CLAUDE.md에는 코드를 읽어서 알 수 없는 것만 남깁니다. CHAPTER 5 프롬프트 뒤에서 일어나는 일, 클로드 코드 작동 방식 이해하기모델과 하네스를 나누어 설명하는 장입니다. 판단은 모델이 하고 도구 실행과 컨텍스트 관리와 실행 환경 관리는 하네스가 맡습니다. 이 구분이 왜 필요한지는 문제가 생겼을 때 드러납니다. 엉뚱한 파일을 고치고 있으면 프롬프트를 손봐야 하고, 명령 자체가 에러를 내면 환경을 봐야 하고, 초반 지시를 점점 안 따르면 컨텍스트를 의심해야 합니다. 이 장에서 배운 것: 세션 시작 시점에 이미 시스템 프롬프트, CLAUDE.md, 자동 메모리, 스킬과 서브에이전트의 이름과 설명, MCP 도구 목록이 컨텍스트를 차지하고 있습니다. 한 줄 요약: 증상을 모델 문제와 환경 문제와 컨텍스트 문제로 나누면 대응이 달라집니다. PART 2 에이전틱 코딩으로 실제 제품 개발하기CHAPTER 6 버티컬 슬라이스, 전체를 작은 단위로 나누어 만들어가기『클로드 코드 에이전틱 코딩』의 중심 개념입니다. 데이터베이스부터 만들고 API를 얹고 화면을 붙이는 레이어별 순서 대신, 화면에서 데이터까지 관통하는 작은 기능 하나를 끝까지 완성합니다. 클로드 코드가 프롬프트 하나에 수십 개 파일을 바꿔놓는 도구라는 점을 생각하면 이 방식이 왜 궁합이 맞는지 바로 이해가 됩니다. 이 장에서 배운 것: 좋은 슬라이스의 기준은 “더 나눌 수 있느냐”가 아니라 “그 슬라이스만으로 검증이 되느냐”입니다. 회원가입만으로는 확인이 안 되면 로그인까지 한 슬라이스로 묶습니다. 한 줄 요약: 검증 가능한 최소 기능 단위가 슬라이스의 크기를 정합니다. CHAPTER 7 무엇을 만들지 정하고 작업 계획 세우기, SPEC.md와 PLAN.mdSPEC과 PLAN을 만드는 방식이 왜 달라야 하는지 설명하는 대목이 좋았습니다. SPEC의 정보는 사람 머릿속에 있으니 클로드 코드가 질문하고 내가 답하는 인터뷰로 뽑아내고, PLAN은 확정된 SPEC과 코드베이스를 읽으면 나오는 것이니 클로드 코드가 제안하고 사람이 검토합니다. 팀 할 일 관리 앱을 예제로 인터뷰부터 슬라이스 의존성 그래프까지 실제 산출물을 보여줍니다. 이 장에서 배운 것: PLAN을 쓸 때는 새 세션에서 시작하고, 구체적인 파일 경로와 구현 방법은 넣지 말라고 명시해야 합니다. 그래야 실제 구현 시점의 코드베이스를 보고 판단하게 됩니다. 한 줄 요약: 사람만 아는 것은 인터뷰로 받고, 코드를 읽으면 아는 것은 제안받아 검토합니다. CHAPTER 8 슬라이스를 실행 가능한 지시서로 만들기, SLICE.mdPLAN에 적힌 “회원가입/로그인” 한 줄로는 구현을 시킬 수 없다는 데서 출발합니다. 작업 목표, 전제 조건, 구현 범위, 구현 제외 범위, 변경 파일 범위, 기술적 선택, 디자인 참조, 완료 기준까지 지시서의 뼈대를 하나씩 채웁니다. 디자인 참조를 텍스트, 스크린샷, 피그마 MCP, AI 디자인 도구 네 가지로 나눠 설명한 점도 현실적이었습니다. 이 장에서 배운 것: “페이지가 빠르게 로드된다”는 완료 기준이 아니고 “페이지가 3초 이내에 로드된다”가 완료 기준입니다. 검증 방법이 구체적이지 않으면 테스트하지 않고도 완료했다고 보고합니다. 한 줄 요약: 완료 기준은 엔드 유저 관점에서, AI가 스스로 실행해 판정할 수 있게 씁니다. CHAPTER 9 슬라이스 구현과 검증지시서를 넘기고 구현을 지켜보는 장입니다. 문제가 생겼을 때 바로 고치라고 하지 말고 “원인을 찾아서 알려줘, 아직 수정하지 마”라고 먼저 끊으라는 조언이 유용했습니다. 수정을 반복해도 안 풀리면 커밋 시점으로 되돌리고 새 세션에서 다시 시작하되, 그 전에 SLICE.md에 모호한 부분이 없는지 점검하라고 합니다. 이 장에서 배운 것: 실패한 시도가 대화에 쌓이면 판단 품질이 같이 떨어지므로, 교정을 반복하는 것보다 되돌리고 새로 시작하는 쪽이 빠를 때가 있습니다. 한 줄 요약: AI가 완료를 보고해도 최종 검증 책임은 지시한 사람에게 있습니다. PART 3 클로드 코드 능력 확장하기CHAPTER 10 새로운 워크플로 추가하기, 스킬매번 똑같이 타이핑하던 긴 지시사항을 SKILL.md 한 장으로 접어두는 방법입니다. 마켓플레이스에서 플러그인을 설치하는 절차, 직접 만드는 절차, 그리고 description을 다듬어 자동 호출률을 올리는 요령까지 이어집니다. 본문에 이 장에서 배운 것: 되돌리기 어려운 스킬은 프런트매터에 한 줄 요약: 스킬은 프롬프트 저장소가 아니라 스크립트까지 묶은 작업 절차서입니다. CHAPTER 11 별도 공간에서 일하는 전문가 만들기, 서브에이전트테스트 로그 수백 줄이 메인 컨텍스트를 채우는 장면에서 시작합니다. 서브에이전트는 자기 컨텍스트에서 일하고 결과만 돌려주므로 그 오염을 막아줍니다. 이 장에서 배운 것: 서브에이전트를 쓰지 말아야 할 경우가 세 가지로 정리돼 있습니다. 사용자와 왕래가 잦은 작업, 이전 토론 맥락이 필요한 작업, 중간 산출물이 메인 컨텍스트에 남아야 하는 작업입니다. 한 줄 요약: 컨텍스트를 나누면 깨끗해지지만 맥락도 같이 끊긴다는 점을 계산에 넣어야 합니다. CHAPTER 12 제품 개발에 스킬과 서브에이전트 활용하기2부의 개발 흐름에 3부의 도구를 얹는 장이고, 개인적으로 『클로드 코드 에이전틱 코딩』에서 가장 좋았습니다. 학습되지 않은 도메인에서는 무엇을 물어야 할지조차 모른다는 한계를 스킬의 이 장에서 배운 것: 코드를 짠 주체가 자기 코드를 검증하면 확증 편향이 생깁니다. 검증자에게는 한 줄 요약: 역할을 나누는 진짜 이유는 속도가 아니라 판정의 독립성입니다. CHAPTER 13 협업하며 일하는 팀 만들기, 에이전트 팀즈서브에이전트끼리는 대화하지 못한다는 한계에서 출발합니다. 에이전트 팀즈는 여러 세션을 띄워 팀 리더와 팀원을 만들고, 공유 태스크 리스트와 메일박스로 서로 소통하게 합니다. 실험적 기능이라 설정으로 켜야 하고 tmux를 붙이면 팀원별 패널을 한 화면에서 볼 수 있습니다. 이 장에서 배운 것: 팀원들은 같은 파일 시스템을 씁니다. 파일 오너십을 팀원별로 지정하지 않으면 한쪽 변경이 조용히 사라질 수 있고, 토큰 사용량도 단일 세션보다 크게 늡니다. 한 줄 요약: 팀원 사이에 오갈 말이 없는 작업이라면 서브에이전트가 더 경제적입니다. PART 4 자동으로 지키고 자동으로 실행하기CHAPTER 14 자동으로 실행되는 명령 걸기, 훅『클로드 코드 에이전틱 코딩』의 문장 중 가장 오래 남은 한 줄이 여기 있습니다. CLAUDE.md는 부탁이고, 훅은 강제입니다. 이벤트와 매처와 핸들러 세 요소를 나눠 설명하고, 알림 훅을 하나 만들어본 다음 보호 파일 차단 훅과 포매터 자동 실행 훅으로 넘어갑니다. 훅이 안 먹을 때 원인을 찾는 절차까지 붙어 있어 실습 중에 막혀도 빠져나올 수 있습니다. 이 장에서 배운 것: 차단은 한 줄 요약: 예외 없이 지켜져야 하는 규칙은 문서가 아니라 시스템에 맡깁니다. PART 5 실전에서 달라지는 것CHAPTER 15 클로드 코드를 세상과 연결하기, MCP피그마, 데이터베이스, Playwright, 슬랙 네 가지를 개발 관점에서 소개하고 슬랙 MCP를 직접 연결해봅니다. 8장과 9장에서 이미 써본 도구들을 여기서 개념으로 다시 묶어주는 구성이라 이해가 수월했습니다. 이 장에서 배운 것: 데이터베이스 MCP는 읽기 전용 계정으로 붙이라고 권합니다. 연결 자체가 새로운 공격 경로가 될 수 있으니 신뢰할 수 있는 서버만 고르라는 단서도 붙어 있습니다. 한 줄 요약: MCP 연결은 기능 추가인 동시에 권한 확대입니다. CHAPTER 16 클로드 코드를 날카롭게 유지하기, 컨텍스트와 세션 관리
이 장에서 배운 것: 자동 압축의 문제는 무엇을 남길지 AI가 정한다는 점입니다. 한 줄 요약: CHAPTER 17 클로드 코드에게 안전하게 맡기기, 권한과 경계와 보안권한 규칙의 우선순위가 Deny, Ask, Allow 순이라는 것부터 정리하고 권한 모드 네 가지를 상황별로 갈라줍니다. 이어서 파일 도구의 수정 범위, 셸 명령을 가두는 샌드박스, 완전 격리를 위한 컨테이너까지 범위를 넓힙니다. 마지막은 프롬프트 인젝션입니다. README에 숨겨둔 주석 한 줄로 개인 키를 출력시키는 시나리오가 구체적이라 읽으면서 서늘했습니다. 이 장에서 배운 것: 샌드박스를 켜도 읽기는 컴퓨터 전체가 허용이라 한 줄 요약: 되돌릴 수 없는 작업과 프로덕션 비밀 키는 애초에 손이 닿지 않게 둡니다. 『클로드 코드 에이전틱 코딩』 서평이 책은 누구에게 맞을까요?『클로드 코드 에이전틱 코딩』은 클로드 코드를 열어는 봤는데 결과물이 뒤죽박죽이 되어 덮어둔 분께 가장 잘 맞습니다. 도구 설명서가 아니라 작업 지시 방법을 다루는 책이라, 이미 몇 달 써온 분도 2부부터 읽으면 얻어갈 것이 있습니다. 프로그래밍 경험이 없어도 따라올 수 있게 썼다고 밝히고 있고 실제로 용어마다 풀어 설명하지만, 변수와 함수 정도는 알고 계셔야 실습이 편합니다. 반대로 알고리즘이나 아키텍처 설계를 기대하고 집으면 결이 다릅니다. 이 책의 좋았던 점
그리고 필자의 결론필자는 『클로드 코드 에이전틱 코딩』을 기능 설명서가 아니라 완료 기준에 관한 책으로 읽었습니다. 17개 장을 관통하는 문장 하나를 고르라면 “검증 방법이 구체적이지 않으면 실제로는 테스트하지 않았으면서도 완료했다고 보고할 수 있다”입니다. 범위 고정 프롬프트도, SLICE의 완료 기준도, 검증 서브에이전트도, 훅도 결국 같은 문제를 다른 층에서 푸는 장치입니다. 그래서 읽고 나서 실제로 바꾼 것은 문서 한 칸이었습니다. 작업 지시서의 완료 기준을 “로그인이 정상 동작한다” 같은 문장에서 명령과 기대 출력이 붙은 체크리스트로 바꿨습니다. 이게 바뀌니 재작업이 눈에 띄게 줄었습니다. 반대로 에이전트 팀즈는 도입하지 않기로 했습니다. 팀원들이 같은 파일 시스템을 공유해 충돌이 나고 토큰이 크게 늘어나는데, 지금 하는 일은 팀원끼리 오갈 말이 거의 없는 작업이라 서브에이전트로 충분하다고 판단했습니다. 안 한 것에도 이유가 있어야 결론이라고 생각합니다. 한 가지 더 남는 생각도 있습니다. 『클로드 코드 에이전틱 코딩』은 규칙을 강제하는 수단으로 훅을 권하는데, 훅은 한 번 걸어두면 반드시 실행되는 만큼 잘못 걸어두면 반드시 방해합니다. 무엇을 강제로 올릴지 고르는 감각은 결국 몇 번 데어보면서 생기는 것 같습니다. 그 판단을 도와줄 재료는 『클로드 코드 에이전틱 코딩』 안에 충분히 들어 있습니다. AI 도구를 다룬 다른 서평도 함께 보시면 흐름이 이어집니다. 나만의 MCP 서버 만들기 with 커서 AI 서평에서는 MCP를 처음 붙여보는 과정을, AI 에이전트 마스터 클래스 서평에서는 에이전트 구조 자체를 다뤘습니다. 여러 에이전트를 붙여 일을 시키는 쪽은 클로드 에이전트 협업의 기술 서평이 더 가깝습니다. 본 포스팅은 “한빛미디어 ＜나는 리뷰어다＞ 활동을 위해서 책을 제공받아 작성된 서평입니다“ |
