클로드 코드 하나로

기획·개발·운영을 한 번에 끝낸다

AI 에이전틱 코딩의 실전 워크플로를 처음부터 끝까지 담은 최초의 클로드 코드 전문서. AI 코딩 도구는 이제 스스로 작업을 정의하고, 설계하고, 테스트까지 반복하는 '에이전트'로 진화했다. 이 책은 그 변화의 중심에 있는 클로드 코드를 실무에서 제대로 활용하는 법을 알려준다. 설치와 환경 설정부터 풀스택 TODO 앱 구현, AWS Bedrock과 연동한 AI 챗봇 개발까지, 실제 프로젝트를 함께 만들어가며 AI와 협업하는 개발자의 역할과 방법론을 체득할 수 있다.

단순한 툴 사용법을 넘어 “AI 시대에 개발자로서 어떻게 일할 것인가”라는 본질적인 질문에 답한다. 작업을 어떻게 분해하고, 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. 개발에 참고할 만한 프로그램