Claude Code 실전 가이드 - 이렇게 지시하면 잘 해준다
Claude Code란?
Claude Code는 Anthropic에서 만든 터미널 AI 코딩 에이전트다. 프로젝트 폴더에서 실행하면 코드베이스를 읽고, 지시에 따라 파일을 생성/수정한다.
# 설치
npm install -g @anthropic-ai/claude-code
# 프로젝트 폴더에서 실행
cd my-project
claude
실행하면 프롬프트가 뜨고, 자연어로 지시하면 된다.
잘 되는 지시 vs 안 되는 지시
안 되는 지시 (모호함)
로그인 기능 만들어줘
이렇게 하면 Claude Code가 나름대로 만들긴 하는데, 내가 원하는 것과 다를 확률이 높다. 어떤 프레임워크? 세션 기반? JWT? OAuth? 모호하면 AI가 임의로 결정한다.
잘 되는 지시 (구체적)
# 로그인 기능 추가
## 프로젝트 루트
~/projects/my-app
## 기술 스택
- Next.js 14 App Router
- PostgreSQL (Prisma)
- 세션 기반 인증 (iron-session)
## 요구사항
1. /login 페이지 추가
2. 이메일 + 비밀번호 로그인
3. 비밀번호는 bcrypt로 해싱
4. 로그인 성공 시 /dashboard로 리다이렉트
5. 세션 유효기간 7일
## 참고 파일
- prisma/schema.prisma (User 모델 있음)
- src/app/layout.tsx (레이아웃)
## 완료 조건
- npm run build 성공
- 로그인/로그아웃 동작 확인
이 정도로 구체적으로 쓰면 원하는 결과가 나올 확률이 높다.
지시서 템플릿
새 기능 추가
# [기능명] 구현
## 프로젝트 루트
[프로젝트 경로]
## 배경
[왜 이 기능이 필요한지]
## 요구사항
1. [구체적인 요구사항 1]
2. [구체적인 요구사항 2]
3. ...
## 기술 스택
- [사용할 프레임워크/라이브러리]
## 참고 파일
- [참고해야 할 기존 파일들]
## 완료 조건
- [빌드 성공 여부]
- [테스트 통과 여부]
- [동작 확인 방법]
버그 수정
# [버그명] 수정
## 프로젝트 루트
[프로젝트 경로]
## 현상
[현재 어떻게 동작하는지]
## 기대 동작
[어떻게 동작해야 하는지]
## 재현 방법
1. [재현 단계 1]
2. [재현 단계 2]
## 관련 파일
- [버그가 있을 것 같은 파일]
## 완료 조건
- 버그 재현 안 됨
- 기존 기능 정상 동작
리팩토링
# [대상] 리팩토링
## 프로젝트 루트
[프로젝트 경로]
## 현재 문제
[왜 리팩토링이 필요한지]
## 리팩토링 방향
[어떻게 바꾸고 싶은지]
## 범위
- [변경할 파일/함수 목록]
## 주의사항
- [건드리면 안 되는 것]
- [호환성 유지 필요한 것]
## 완료 조건
- 기존 테스트 통과
- 빌드 성공
지시서에 꼭 포함할 것
1. 프로젝트 루트
## 프로젝트 루트
~/projects/my-app
Claude Code가 올바른 위치에서 작업하도록 명시한다.
2. 참고 문서/파일
## 참고 파일
- docs/api-spec.md (API 명세)
- src/types/user.ts (User 타입 정의)
기존 코드 스타일, 타입 정의 등을 알려주면 일관성 있게 작업한다.
3. 완료 조건
## 완료 조건
- npm run build 성공
- npm run test 통과
- 화면에서 동작 확인
무엇이 "완료"인지 명확히 해야 한다. 안 그러면 중간에 멈추거나 과하게 작업한다.
4. 영향도 분석
## 영향받는 파일
- 수정 대상: src/components/Header.tsx
- 영향 가능: src/pages/index.tsx (Header 사용)
수정이 다른 곳에 영향을 줄 수 있음을 알려주면, 관련 파일도 함께 수정한다.
기획서를 잘 써두면 편하다
CraftBay 프로젝트에서는 proposals/ 폴더에 기획서를 마크다운으로 작성해둔다.
proposals/
├── life-exp.md
├── zodiac-guesser.md
└── ip-search.md
그리고 Claude Code에는 이렇게 지시한다:
기획서(proposals/zodiac-guesser.md)를 읽고 구현해줘.
기술 스택은 Next.js 14, Tailwind CSS, PostgreSQL.
기획서에 요구사항이 잘 정리되어 있으면, 지시가 간단해진다.
실패했을 때 대처법
빌드 에러가 날 때
빌드 에러 나는데 수정해줘
에러 메시지를 안 줘도, Claude Code가 직접 빌드해보고 에러를 확인한다.
의도와 다르게 동작할 때
/login에서 로그인하면 /dashboard가 아니라 /로 가는데,
/dashboard로 가게 수정해줘
"어디서 뭐가 어떻게 잘못됐는지" 구체적으로 설명한다.
중간에 막혔을 때
지금까지 한 거 커밋하고, 진행 상황 정리해줘
일단 중간 저장하고, 상황을 파악한 뒤 다시 지시한다.
완전히 잘못된 방향으로 갔을 때
지금까지 한 거 전부 되돌리고, 다시 시작하자.
이번에는 [다른 접근 방식]으로 해줘.
git으로 되돌리고 새로 시작하는 게 빠를 때가 있다.
잘 안 되는 경우
복잡한 상태 관리
여러 컴포넌트에 걸친 복잡한 상태 관리는 잘 못한다. 이럴 땐 설계를 먼저 함께 논의하고, 단계별로 지시하는 게 낫다.
외부 API 연동
문서화가 잘 안 된 외부 API는 어렵다. API 문서 URL을 주거나, 예시 요청/응답을 직접 보여주면 낫다.
레거시 코드
오래된 복잡한 코드베이스에서는 실수가 많다. 작은 단위로 쪼개서 지시하고, 매번 테스트하는 게 좋다.
결론: 말 잘 듣는 주니어 개발자
Claude Code는 말 잘 듣는 주니어 개발자다.
- 지시한 대로 빠르게 작업한다
- 구체적으로 알려주면 잘 한다
- 모호하면 임의로 판단한다 (종종 틀린다)
- 큰 그림은 시니어(나)가 잡아야 한다
"일 잘 시키는 능력"이 중요해졌다. 요구사항을 명확하게 정리하고, 단계별로 확인하고, 결과를 검토하는 것. 예전에 주니어 개발자와 협업하던 방식이랑 비슷하다.
다음 글에서는 이 과정을 자동화한 ClaudeQ 시스템을 소개하겠다.