책소개
"""AI가 코드를 짜주는 시대, 개발자는 무엇을 해야 하는가""
20년 차 개발자의 경험을 집대성한 에이전틱 코딩 워크플로 가이드
클로드 코드, 커서, 코덱스 등 AI 에이전트 코딩 도구가 폭발적으로 성장하면서 개발 현장은 빠르게 바뀌고 있다. 그러나 `어떻게 쓰는지`가 아니라 `어떻게 잘 쓰는지`를 체계적으로 정리한 실무서는 여전히 드물다. 이 책은 1년 이상 클로드 코드를 실무에 직접 적용하며 시행착오를 겪어온 저자들이, 그 경험을 바탕으로 AI와 함께 일하는 방법론을 처음으로 정리한 실전서다.
버튼 설명서가 아닌, 협업 방법론을 배운다. AI 도구는 업데이트될 때마다 UI와 기능이 달라진다. 이 책은 특정 버전의 기능을 하나하나 설명하는 매뉴얼이 아닌 `작업을 어떻게 쪼갤 것인가`, `AI 출력을 어떻게 검증할 것인가`, `개발자로서 주도권을 어떻게 유지할 것인가` 이 세 가지 질문을 중심으로 AI와 협업하는 방법론 자체를 다룬다. 여기서 배운 원칙은 클로드 코드가 아닌 다른 도구를 쓸 때도 그대로 통한다.
실전 프로젝트 두 개로 완성하는 풀스택 역량을 기른다. 이론만으론 부족하다. 기초편(풀스택 TODO 앱)과 실전편(AWS Bedrock 기반 AI 챗봇 앱)이라는 두 개의 완성형 프로젝트를 직접 따라가며 클로드 코드의 실제 워크플로를 익힌다. React + TypeScript 프런트엔드, Node.js 백엔드, PostgreSQL 데이터베이스 그리고 Claude API의 Tool Use와 스트리밍 응답까지 기획, 명세 작성, 구현, 테스트, 배포의 전 과정을 AI와 함께 단계별로 따라갈 수 있다.
TDD와 SDD로 AI 출력을 믿을 수 있는 코드로 만든다. 할루시네이션 대응, 회귀 방지, 대규모 코드베이스 다루기 등 실무에서 반드시 부딪히는 문제들을 TDD(테스트 주도 개발)와 SDD(명세 주도 개발) 방법론으로 풀어낸다. Spec Kit을 활용한 워크플로 자동화까지 더해, AI의 비결정적 출력을 안전하고 검증된 코드로 바꾸는 실전 전략을 배울 수 있다.
CLAUDE.md, Hook, MCP... 클로드 코드를 내 것으로 만드는 고급 설정을 배운다. 클로드 코드를 잘 쓰려면 기본 기능 외에도 프로젝트 전용 설정 파일(CLAUDE.md), 워크플로 자동화를 위한 Hook, 외부 서비스와 연결하는 MCP 서버 설정을 제대로 이해해야 한다. 이 책은 그 설정들을 단편적으로 소개하는 것이 아니라, 실제 프로젝트 흐름 안에서 자연스럽게 녹여 알려준다.
이 책의 대상 독자
●AI 코딩 도구를 써봤지만 결과물의 수준을 믿지 못하는 개발자
●클로드 코드를 좀 더 체계적으로 실무에 적용하고 싶은 중급 개발자
●AI 시대에 개발자로서의 경쟁력을 고민하는 분
●풀스택 AI 앱을 처음부터 끝까지 직접 만들어보고 싶은 분
미리 읽은 베타리더들의 한 마디
●AI 에이전트에 관한 기존 책들이 대부분 바이브 코딩과 에이전트 기초만 다뤘다면 이 책은 수준 높은 심화 활용 기법을 상세히 파고듭니다. _노경태 님
●무엇보다 Spec Kit 기반의 SDD 예제는 복잡한 프로젝트를 구조화하고 통제하는 방법에 대한 명확한 단초를 제공합니다. _윤석진 님
●TODO, 챗봇 앱을 처음부터 끝까지 AI 에이전트를 활용해 개발하는 부분은 마치 시니어 개발자가 바로 옆에서 알려주는 느낌이 들었습니다. `딸깍`이 난무하는 시대에 이렇게 자세하고 친절한 책은 처음입니다. _정윤성 님
●모든 단계가 실제 동작하는 코드로 뒷받침되며, 이론과 실습이 이렇게 단단하게 맞물린 책을 만나는 건 어려운 일입니다. AI와 함께 일하는 개발자라면 꼭 봐야 할 책입니다. _전영식 님"
저자소개
20년 차 개발자이다. 카카오에서 셀장, 파트장, 리더를 거쳐 AI 에이전트가 나온 이후로는 실무에 복귀해서 현재는 평범한 서버 개발자로 근무하고 있다. 제약회사 전산실에서 첫 직장생활을 시작하여 WAS 기술 벤더에서 근무한 뒤, 꽤 오랜 시간 SI 업계에 몸담았다. 커머스, 통신, 전자 등 큰 프로젝트에서 서비스 도메인 개발을 맡으며 공통 프레임워크 개발 담당 및 애플리케이션 아키텍트로 일했다. 2012년에는 스터디 그룹을 꾸려 만든 오픈소스 프로덕트로 공개SW 개발자대회에 입상하였고 이후 쿠팡에서 4년가량 주문/배송 시스템의 MSA 분리 개발, 여행 예약 서비스 개발 업무 등을 수행한 후 LF를 거쳐 카카오로 이직하였다. 2024년에는 한빛미디어를 통해 『개발자 기술 면접 노트』라는 책을 출간했으며, 현재는 사이드 프로젝트로 노트 앱(QNote)과 홈서버 자동 구축 솔루션인 Brewnet 등 다양한 아이디어를 AI 도구를 통해 구현하는 데 재미를 느끼고 있다.
목차
[ 1부 | 시작하기 전에 ]
CHAPTER 1 AI 시대의 개발자 패러다임
1.1 개발자의 역할 변화
1.2 AI 코딩 어시스턴트란 무엇인가
__AI 코딩 도구의 진화
__AI 코딩 어시스턴트의 정의
__LLM 기반의 작동 원리
__AI 에이전트 도구의 등장
1.3 클로드 코드 소개
1.4 더 많은 실험이 가능해진 시대
CHAPTER 2 클로드 코드 설치와 환경 구성
2.1 클로드 코드 개발 환경 설정하기
__맥에서 클로드 코드 설치하기
__윈도우에서 클로드 코드 설치하기
__클로드 코드 실행해보기
__VSCode 설치하기
2.2 첫 번째 대화: Hello, World
__클로드 코드 인터페이스와 편집 모드의 이해
2.3 클로드 모델 계열 이해하기
__Opus, Sonnet, Haiku 비교
__용도별 모델 선택 가이드
__Extended Thinking 모드
__클로드 코드에서 Thinking 모드 변화 및 사용법
2.4 기본 명령어(슬래시 커맨드)와 사용법 익히기
__꼭 알아야 할 필수 명령어
__자주 쓰는 단축키
__프롬프트 내 특수 문법
__대화 모드 vs 단일 명령 모드
__커스텀 슬래시 명령어 만들기
__실전 명령어 조합 예시
2.5 CLAUDE.md로 프로젝트 설정하기
__CLAUDE.md 파일의 역할
__효과적인 CLAUDE.md 작성법
__코딩 컨벤션과 프로젝트 규칙 전달하기
__AGENTS.md: 모든 에이전트를 위한 표준 문서
2.6 Agent Skill 이해하기
__Agent Skill이란 무엇인가
__Skill이 수행할 수 있는 작업 유형
__사용 가능한 Skill 확인하기
__클로드 코드 Skill 저장소 소개
__Skill의 활성화와 비활성화
2.7 Hook으로 워크플로 자동화하기
__Hook이란 무엇인가
__작업 완료 시 소리 알림 설정하기
__Hook 활용 아이디어
__PreCompact Hook으로 작업 흐름 이어가기
__Hook 사용 시 주의사항
CHAPTER 3 AI와 함께하는 개발 방법론
3.1 왜 설계가 중요한가
3.2 작은 단위로 쪼개기의 힘
__한 번에 하나의 작업만 요청하기
__작업 분해의 기준과 단위
3.3 명확한 지시의 기술
__컨텍스트 제한의 원칙
__완료 조건을 명시하는 방법
3.4 매 단계 리뷰하기: 주의 깊은 수정의 원칙
__리뷰해야 할 것들
__단계별 리뷰 습관 만들기
__리뷰 워크플로와 되돌리기
3.5 AI에게 없는 것 - 개발자의 판단력(Taste)
3.6 증강코딩과 TDD - AI 시대의 개발 방식
__증강코딩 : AI 시대의 새로운 개발 방식
__AI 출력의 비결정적 특성과 TDD
__AI가 TDD 사이클을 무시할 때 대응법
__AI가 만드는 회귀 방지하기
__테스트가 진짜 안전망이 되려면
3.7 클로드 코드에서 MCP 설정하기
__MCP 서버 연결과 설정
__개발에 필수적인 MCP 서버
__Skill, Hook, MCP 확장 기능 사용의 원칙
[ 2부 | 기초편_풀스택 TODO 앱 개발 ]
CHAPTER 4 프로젝트 소개와 요건 정의
4.1 TODO 앱으로 배우는 풀스택 개발
__프런트엔드: React + TypeScript
__백엔드: Node.js + Express/Next.js API Routes
__데이터베이스 선택
4.2 요구사항 정의하기
__기능 요구사항 정의
__비기능 요구사항 정의
__사용자 스토리 정의
4.3 클로드 코드와 함께 요건 문서 작성하기
__프로젝트 구조 및 실제 개발 계획 수립하기
__PRD, TRD, REQUIREMENTS.md 작성
4.4 명세서 설계와 TDD 방식으로 개발 시작하기
__데이터 설계
__API 설계
__컴포넌트 및 UseCase 설계
__테스트 케이스 정의
__TDD 방식의 개발 흐름
__PostgreSQL 설치
__TDD로 개발 시작하기
4.5 SDD와 Spec Kit
__SDD란 무엇인가
__왜 AI와 SDD가 잘 맞는가
__TDD와 SDD의 결합
__Spec Kit으로 SDD 워크플로 자동화하기
__수동 워크플로 vs Spec Kit: 언제 무엇을 쓸 것인가
__실무 활용 팁
CHAPTER 5 백엔드 구현 - 명세를 코드로 만들기
5.1 개발 환경 준비
__ Next.js 프로젝트 생성 및 의존성 설치
__ Jest 테스트 환경 구성
__ Drizzle ORM과 PostgreSQL 연결
5.2 SDD 워크플로로 API 구현하기
__Spec Kit 초기화와 Constitution 설정
__필수 안전 장치(가드레일) 추가
__/speckit 명령어를 이용한 계획 수립과 구현 프로세스
5.3 테스트로 명세 검증하기
5.4 API 검증과 마무리
__명세(API_SPEC.md) 대비 구현 검증
__수동 테스트로 최종 확인
__변경사항 기록 Skill 연동하기
CHAPTER 6 프런트엔드 개발 - 컴포넌트 단위로 구축하기
6.1 개발 환경과 구현 전략
6.2 컴포넌트 테스트 환경 구성
6.3 UI 컴포넌트 설계와 구현
__기본 컴포넌트 TDD로 구현하기
__레이아웃 구현하기
__티켓폼과 모달 구현하기
6.4 API 연동과 상태 관리
6.5 컨테이너 조립과 페이지 통합
6.6 디자인 시스템을 이용한 UI와 스타일 개선
__디자인 시스템 일관성 유지
__디자인 시스템을 CLAUDE.md에 반영하기
__프런트 개발 플러그인을 활용한 UI 개선
6.7 프런트엔드 테스트 실행과 검증
CHAPTER 7 빌드와 배포
7.1 개발/스테이징/운영 서버 관리 전략
7.2 Vercel을 이용한 배포
__배포 전 준비사항
__Vercel 계정 생성과 프로젝트 연결
__첫 배포 실행
7.3 Railway를 이용한 백엔드 배포
7.4 도메인 연결하기
[ 3부 | 실전편_AI 챗봇 앱 개발 ]
CHAPTER 8 프로젝트 기획과 설계
8.1 AI 챗봇 프로젝트 개요
__무엇을 만들 것인가
__이 프로젝트를 선택한 이유
8.2 AWS Bedrock과 모델 선택
__AWS Bedrock이란
__Converse API를 선택한 이유
__비용 추정과 최적화 전략
8.3 프로젝트 범위 결정
8.4 시스템 아키텍처 설계
8.5 API 설계
__엔드포인트 목록
__요청/응답 형식 개요
__SSE 이벤트 타입 정의
8.6 프런트엔드 UI 설계
__화면 레이아웃
__주요 컴포넌트 정의
8.7 CLAUDE.md 작성
__프로젝트 컨텍스트 정리
__코딩 컨벤션 정의
__제외 사항 명시
8.8 TDD + 클로드 코드 워크플로
__역할 분담 및 실제 워크플로
__프롬프트 패턴
__명세의 두 가지 형태
CHAPTER 9 AWS Bedrock 연동
9.1 AWS 계정과 IAM 설정
__AWS 계정 생성
__IAM 사용자 생성
__Bedrock 액세스 권한 설정
9.2 프로젝트 초기화
__Node.js 프로젝트 생성과 AWS SDK 설치
__테스트 환경 구성
__CLAUDE.md 작성
9.3 Bedrock 클라이언트 구현
__테스트 작성: 클라이언트 생성
__테스트 작성: 기본 메시지 전송
__클로드 코드에 구현 요청
__검증과 리팩터링
9.4 스트리밍 응답 처리
__테스트 작성: 스트리밍 이벤트
__클로드 코드에 구현 요청
__이벤트 타입별 핸들링
__토큰 사용량 추적
9.5 에러 핸들링
__테스트 작성: 에러 시나리오
__클로드 코드에 구현 요청
__에러 타입별 처리
CHAPTER 10 채팅 API 구현
10.1 Express 서버 설정
__프로젝트 구조
__미들웨어 설정
__라우터 구성
10.2 세션 관리
__테스트 작성: 세션 CRUD
__구현: SessionManager
10.3 대화 히스토리 관리
__테스트 작성: 메시지 저장/조회
__구현: MessageHistory
__컨텍스트 크기 관리
10.4 시스템 프롬프트 설계
__프롬프트 구조
__페르소나 정의
10.5 채팅 API 엔드포인트
__테스트 작성: POST /api/chat
__구현: SSE 스트리밍 응답
__테스트 작성: 세션 API
__구현: 세션 CRUD 엔드포인트
__테스트 작성: 세션 메시지 API
__테스트 작성: 미들웨어
__SSE 스트리밍 동작 확인
10.6 통합 테스트
__E2E 테스트 작성
__에러 시나리오 테스트
__리팩터링: 테스트가 만드는 안전망
CHAPTER 11 Tool Use 구현
11.1 Tool Use 개념
11.2 도구 정의와 스키마
__도구 스키마 구조
__JSON 스키마 작성법
__도구 설명 작성 가이드
11.3 시간 조회 도구 구현
11.4 계산기 도구 구현
11.5 날씨 API 연동
__외부 API 선택
__도구 설계
__테스트 작성(Mock 활용)
__구현
__에러 처리
__통합 테스트: 실제 API 호출 검증
11.6 다중 도구 처리
__병렬 도구 호출 이해
__테스트 작성: 다중 도구
__구현: 도구 오케스트레이터
__BedrockService에 Tool Use 통합
__Tool Use 통합 테스트
11.7 Tool Use 설계 고려사항
__입력 검증
__타임아웃 처리
__실패 시 폴백 전략
__유틸리티 테스트 실행
CHAPTER 12 챗봇 프런트엔드 개발
12.1 React 프로젝트 설정
__기술 스택: Vite + React + TypeScript
__Tailwind CSS 설정
__프로젝트 구조
12.2 채팅 UI 컴포넌트
__컴포넌트 설계
__테스트 작성: MessageList
__구현: MessageList
__테스트 작성: MessageInput
__구현: MessageInput
12.3 스트리밍 응답 표시
__SSE 클라이언트 설계
__테스트 작성: SSE 서비스
__구현: SSE 클라이언트
__테스트 작성: useChat Hook
__구현: useChat Hook
12.4 Tool Use 결과 표시
__테스트 작성: ToolResult 컴포넌트
__구현: ToolResult 컴포넌트
12.5 마크다운 렌더링
__MarkdownRenderer 컴포넌트 구현
__MessageList에 MarkdownRenderer 연결
__MessageList에 ToolResult 연결
__리팩터링: MessageItem 추출
__보안 고려사항(XSS 방지)
__구현: sanitize 유틸리티
12.6 에러 처리와 로딩 상태
__에러 바운더리
__사용자 친화적 에러 메시지
__로딩 스피너와 로딩 오버레이
12.7 반응형 디자인
__브레이크포인트 전략
__에러 처리와 세션 연결
12.8 App 컴포넌트 통합
__세션 관리 Hook
__App 컴포넌트
12.9 풀스택 통합
__클라이언트 지정 ID -- 백엔드 확장
__세션 백엔드 동기화 -- useSession 확장
__메시지 로딩 -- useChat 확장
__Bedrock Tool Use 스트리밍 -- bedrock.test.ts 확장
__시각적 확인
12.10 디자인 개선: shadcn/ui 적용
__shadcn/ui 설치
__컴포넌트별 적용
__다크 모드 구현
__전체 검증
12.11 프런트엔드 설계 고려사항
__상태 관리 전략
__성능 최적화
[ 부록 ]
A. 반복 실행과 자율 코딩: Loop
B. 어디서든 세션 이어가기: Remote Control
C. 브라우저 자동화: Claude in Chrome
D. 에이전트 스킬 프레임워크: Superpowers
E. 텔레그램으로 클로드 코드 원격 접속하기
F. Brewnet으로 홈서버 구축하기
G. 개발에 참고할 만한 프로그램
