"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와 함께 일하는 개발자라면 꼭 봐야 할 책입니다. _전영식 님

[ 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. 개발에 참고할 만한 프로그램