한 바퀴를 끝까지 돌려보기 | 수동 검증 사이클
Todo 앱의 요구사항·Plan Mode·구현·체크리스트 한 사이클을 완주하며, 수동 검증이 사람의 몫으로 남는다는 한계를 체험합니다
Overview
Plan Mode 와 요구사항 작성을 한 사이클로 묶어 Todo 앱을 처음부터 끝까지 만들어 봅니다. Shadcn 디자인을 입히고, CLAUDE.md·요구사항 문서를 준비해 Plan Mode 로 계획을 세운 뒤, 브라우저 체크리스트로 결과를 확인합니다.
학습 목표
- Shadcn preset 으로 디자인 토큰을 적용하고, CLAUDE.md 에 담을 내용을 골라 작성할 수 있습니다
- 요구사항 문서와 Plan Mode 를 엮어 Todo 앱을 구현할 수 있습니다
시작하기 전 확인사항
- 실습 브랜치로 전환합니다. 이 브랜치에는 Next.js + TypeScript + Tailwind CSS 프로젝트가 빈 상태로 준비돼 있습니다.
git checkout ch04-03Step 1: Shadcn 디자인 입히기
Shadcn은 디자인 토큰(색상, 테마, 폰트, 아이콘, 모서리 반경)을 웹에서 시각적으로 설정한 뒤, 그 설정을 preset이라는 짧은 코드로 내보냅니다. preset을 프로젝트에 적용하면 이후 설치하는 Shadcn 컴포넌트가 모두 선택한 스타일로 렌더링됩니다.
브라우저에서 ui.shadcn.com/create에 접속합니다.
왼쪽 사이드바에서 Style, Base Color, Font 등을 자유롭게 고릅니다. 오른쪽 미리보기에서 선택한 스타일이 즉시 적용된 컴포넌트를 확인할 수 있습니다. 사이드바 하단의 --preset 버튼 (예: --preset a0)을 누르면 현재 설정의 preset ID가 클립보드에 복사됩니다.
터미널에서 복사한 preset ID 로 프로젝트에 적용합니다.
bunx shadcn@latest apply --preset {preset_id}apply 는 기존 base 설정을 유지하면서 테마·색상·CSS 변수·폰트·아이콘만 바꾸고, 이미 설치된 컴포넌트도 새 디자인 토큰으로 재설치합니다. ch04-03 브랜치에는 Next.js 와 shadcn 이 이미 초기화돼 있으므로, 이 한 줄로 디자인 토큰만 교체하면 됩니다.
이 명령은 Claude Code 에 맡기지 마세요
shadcn apply 는 실행 도중 옵션을 선택하라고 묻습니다. Claude Code 의 명령 실행은 대화형 입력을 처리하지 못해 프롬프트에서 멈춥니다. 옵션 선택이 필요한 명령(shadcn, npm init, gh auth login 등)은 터미널에서 직접 실행하는 것이 안전합니다.
Step 2: CLAUDE.md 작성하기
CLAUDE.md 의 매뉴얼 기준에서 "돌아다녀서 알 수 없는 것만 적는다"는 원칙을 세웠습니다. 이번 프로젝트의 매뉴얼을 이 원칙대로 작성합니다.
프로젝트 루트에 CLAUDE.md 를 만들고 다음과 같이 작성합니다.
# Todo App
## Architecture
Server Components 우선, 클라이언트 상태는 최소화.
## Workflow
- 패키지 매니저: bun
- 커밋 메시지: Conventional Commits (feat:, fix:, refactor:)
## Plan Mode
- 계획 끝에 미해결 질문을 포함하세요
## Rules
- 모든 대화에서 한글만 사용Next.js·TypeScript·Tailwind 같은 기술 스택과 bun run dev 같은 실행 명령은 적지 않습니다. 모델이 package.json 과 설정 파일에서 그 정보를 직접 읽을 수 있기 때문입니다.
Step 3: 요구사항 문서 작성하기
Lesson 02 의 두 섹션(기능 목록과 범위 제한)을 그대로 파일로 옮깁니다.
프로젝트 루트에 todo-requirements.md 를 만듭니다.
# Todo 앱 요구사항
## 프로젝트 정보
- 프레임워크: Next.js (App Router)
- UI: Shadcn
- 상태 저장: localStorage
- 스타일: Tailwind CSS
## 기능 목록
1. 사용자가 텍스트를 입력하고 Enter 를 누르면, 새 Todo 가 목록 맨 위에 추가된다
2. 사용자가 Todo 항목의 체크박스를 클릭하면, 완료 상태로 표시된다
3. 사용자가 Todo 항목의 삭제 버튼을 클릭하면, 해당 항목이 제거된다
4. 사용자가 Todo 항목을 더블클릭하면, 인라인 편집이 가능하다
5. 페이지 새로고침 후에도 Todo 목록이 유지된다 (localStorage)
## 범위 제한
- 인증/로그인 없음
- 서버 저장 없음 (localStorage 만)
- 드래그 앤 드롭 없음
- 카테고리/태그 없음요구사항을 파일로 두면 다음 대화에서 @ 로 다시 참조할 수 있고, 내용이 늘어나도 같은 파일 한 곳만 고치면 됩니다.
Step 4: Plan Mode로 계획 수립하기
Shift+Tab 을 두 번 눌러 Plan Mode에 들어간 뒤, 요구사항 파일을 참조하며 계획을 요청합니다.
@todo-requirements.md 이 요구사항대로 Todo 앱을 만들어줘@ 로 파일을 참조하면 AI가 파일 내용을 Context에 바로 불러옵니다. 요구사항이 짧다면 메시지에 붙여넣어도 되지만, 파일로 관리해 두면 수정과 재사용이 편합니다.
Plan Mode에서 AI는 코드를 쓰지 않고 프로젝트를 탐색한 뒤 구현 계획을 제시합니다. 돌아온 계획에서는 네 가지를 확인합니다.
- 파일 구조: 어떤 파일을 어디에 만드는지
- 컴포넌트 분리: 하나의 큰 파일 vs 기능별 분리
- 상태 관리 방식: useState, useReducer, 외부 라이브러리 중 어느 것
- 범위 준수: 요구사항에 없는 기능이 계획에 끼어 있지 않은지
계획 중간에 AI가 질문할 수 있습니다
"Todo의 최대 글자 수에 제한이 있나요?", "완료된 항목을 아래로 보낼까요?" 같은 질문이 오면, 요구사항의 빈틈을 AI가 먼저 발견한 것입니다. 답해 주면 됩니다. 질문이 온다는 것은 요구사항이 잘 작성되었다는 신호이기도 합니다. 모호한 요구사항에는 질문 대신 추측이 옵니다.
의도와 다른 부분은 수정을 요청하고, 만족스러운 계획이 나오면 승인합니다. 승인하면 AI가 Plan Mode를 빠져나와 파일을 만들고 Shadcn 컴포넌트를 추가하며 코드를 씁니다.
Step 5: 브라우저에서 검증하기
구현이 끝났다는 메시지가 뜨면 개발 서버를 띄웁니다.
bun run dev서버는 AI 에게 백그라운드로 실행시키세요
터미널에서 직접 bun run dev 를 띄우면 그 터미널이 묶여 다른 작업을 하기 불편합니다. Claude Code 에게 "개발 서버를 백그라운드로 띄우고, 로그가 나올 때 알려줘" 라고 요청하면 백그라운드 프로세스로 실행하고 Monitor 로 로그를 지켜봅니다. 에러가 발생하면 그대로 읽고 원인을 찾아 줍니다.
브라우저에서 http://localhost:3000 을 엽니다. UI가 뜬다고 해서 모든 기능이 제대로 동작한다는 뜻은 아닙니다. 요구사항에 적은 동작을 하나씩 직접 확인합니다.
| # | 시나리오 | 예상 결과 |
|---|---|---|
| 1 | 입력 필드에 "장보기" 입력 후 Enter | 목록 맨 위에 추가됨 |
| 2 | 빈 입력 상태에서 Enter | 추가되지 않음 |
| 3 | 체크박스 클릭 | 완료 표시 (취소선) |
| 4 | 삭제 버튼 클릭 | 해당 항목 제거 |
| 5 | 페이지 새로고침 | 기존 목록 유지 |
통과하지 못한 항목이 있으면 AI에게 수정을 요청합니다. "삭제 버튼을 클릭해도 항목이 사라지지 않아. 클릭하면 목록에서 제거되어야 해"처럼 현재 동작 + 기대 동작을 함께 알려주면 AI가 더 빠르게 고칩니다.
브라우저 에러는 Claude Code에게 바로 넘기세요
브라우저 콘솔에서 에러를 발견했을 때, 에러 메시지를 복사해 Claude 웹(claude.ai)에 붙여넣지 마세요. Claude Code는 로컬 파일에 직접 접근할 수 있어서, 코드를 읽고 원인을 찾고 수정까지 한 번에 처리합니다. "브라우저에서 에러가 났어"만 말해도 됩니다.
체크리스트가 닫힌 뒤 남는 일
다섯 시나리오를 모두 통과했습니다. Todo 앱이 요구사항대로 동작합니다. 이제 필터링 기능을 추가한다고 해봅시다. "전체 / 진행중 / 완료" 탭을 추가하면, 필터링 코드가 기존 동작에 영향을 줬을 수 있으므로 위 체크리스트를 처음부터 다시 확인해야 합니다. 기능이 하나 추가될 때마다 체크리스트 전체가 한 바퀴씩 반복됩니다.
지금은 5 개지만, 기능이 10개, 30개로 늘어나도 시나리오마다 사람이 브라우저에서 하나씩 확인해야 합니다. 작성은 AI가 가져갔지만, 검증은 여전히 사람의 몫입니다. 병목이 "구현"에서 "검증"으로 옮겨 간 자리입니다.
Part 2는 이 새 병목을 푸는 여정입니다. 사람이 손으로 돌리던 체크리스트를 AI가 스스로 돌릴 수 있는 구조로 바꿔, 검증까지 자동화하는 방법을 배웁니다.
핵심 포인트 정리
- CLAUDE.md·요구사항 두 장이 계획의 재료가 됩니다: 모델이 코드에서 찾을 수 없는 결정·워크플로우·제약만 CLAUDE.md에, "무엇을 만들고 무엇을 안 만들지"를 요구사항에 담습니다
- 요구사항 → Plan Mode → 계획 검토 → 구현 → 검증 순으로 한 바퀴를 돌립니다: AI가 추측 대신 계획에 따라 코드를 씁니다
- 완료 메시지 ≠ 동작 보장: AI가 "완료"라고 말해도 실제 동작 확인은 사람의 몫입니다
- 검증은 반복 작업으로 쌓입니다: 기능이 늘수록 체크리스트도 길어지고, 기능 하나 추가할 때마다 전체를 다시 돌려야 합니다. Part 2는 이 반복을 줄이는 방법을 다룹니다
FAQ
-
Q: AI가 만든 코드에 버그가 있으면 어떻게 하나요?
- A: 체크리스트에서 실패한 항목을 AI에게 그대로 설명합니다. "입력 필드에 공백만 넣고 Enter를 누르면 Todo가 추가돼. 빈 입력은 추가되지 않아야 해"처럼 현재 동작과 기대 동작을 함께 주면 됩니다.
-
Q: 모든 기능을 한 번에 구현해도 되나요?
- A: 가능은 하지만, 한 번에 많은 코드를 생성하면 문제가 생겼을 때 원인을 찾기 어렵습니다. Chapter 3의 Task Sizing 원칙처럼, 수정 → 테스트 → 커밋 한 사이클이 한 Context 안에 담기는 것이 이상적입니다.
이어서 배울 내용
Todo 앱 한 바퀴를 직접 돌리고, 마지막에 수동 체크리스트의 한계까지 눈으로 확인했습니다. Part 1에서 지나온 네 챕터(LLM 기초, Claude Code 인터페이스, Context 관리, Plan Mode 사이클)를 다음 레슨에서 한 장으로 정리합니다.
- Part 1 네 챕터의 큰 테마 복습
- Part 2가 풀 문제의 예고