Claude Code를 처음 쓰는 사람들이 가장 많이 하는 실수는 바로 요청하는 것이다. “로그인 기능 만들어줘”, “회원가입 페이지 만들어줘”. 운이 좋으면 원하는 결과가 나오지만, 조금만 복잡해지면 금방 방향을 잃는다.
AI가 아무리 똑똑해도, 요청하는 사람이 맥락을 잘 전달해야 좋은 결과가 나온다. 건축 전문가가 AI에게 “지하 2층, 지상 15층, 내진 설계 포함”이라고 요청하는 것과 “좋은 건물 지어줘”의 차이다
Anthropic 공식 문서에서 권장하는 Claude Code 개발 워크플로우를 소개한다.
기본 워크플로우 탐색
탐색 → 계획 → 코딩 → 커밋
탐색 (정보 수집)
↓
계획 (문제 분석)
↓
코딩 (검증하며 구현)
↓
커밋 (코드 보관)
이 흐름은 AI 도구가 생기기 전에도 개발자들이 해오던 방식이다. 요구사항을 분석하고, 필요한 정보를 모으고, 계획을 세운 다음 개발한다. Claude Code를 쓴다고 해서 이 순서가 바뀌지는 않는다
1단계 – 탐색
Claude에게 관련 파일, 이미지, URL을 먼저 읽게 한다. 아직 코드는 작성하지 말라고 명시적으로 말하는 것이 중요하다
"src/auth/ 폴더를 읽어줘. 아직 코드 수정은 하지 마." "이 문서를 읽고 구조를 파악해줘. 구현은 나중에."
복잡한 작업일수록 이 단계를 서브에이전트에게 맡기는 것이 효과적이다. 메인 세션의 컨텍스트를 아끼면서 필요한 정보만 정확하게 수집할 수 있다
2단계 – 계획
탐색이 끝났으면 계획을 세운다. 이때 think 키워드를 사용하면 Claude가 더 깊이 생각하고 대안을 검토한다
| 키워드 | 사고 깊이 |
think | 기본 |
think hard | 심화 |
think harder | 매우 심화 |
ultrathink | 최대 (현재는 기본값으로 통합) |
계획이 마음에 들면 문서나 GitHub 이슈로 저장해둔다. 3단계 구현이 잘못됐을 때 이 지점으로 되돌아올 수 있다
3단계 – 코딩
계획에 따라 구현을 요청한다. 이때 핵심은 검증하면서 진행하는 것이다
❌ "로그인 기능 만들어줘" ✅ "로그인 기능 만들어줘. 각 단계마다 멈춰서 이 부분이 제대로 작동하는지, 빠뜨린 건 없는지 확인하면서 진행해줘."
구현하면서 검증하지 않으면, 다 만들고 나서 처음부터 다시 하는 상황이 생긴다
4단계 – 커밋
구현이 완료되면 커밋으로 마무리한다. 이 시점에 README나 CHANGELOG 업데이트도 함께 요청하면 좋다
UI 개발은 별도 워크플로우로
UI 작업은 텍스트 설명보다 이미지가 훨씬 정확한 맥락을 전달한다. 다음 흐름으로 진행한다
디자인 이미지 제공 → 구현 요청 → 스크린샷 확인 → 수정 → 반복
Puppeteer MCP나 Playwright MCP를 연결해두면 Claude가 직접 화면을 찍어 확인할 수 있다. 없다면 스크린샷을 직접 복사해서 붙여넣으면 된다
첫 번째 결과가 마음에 안 들어도 괜찮다. 2~3번 반복하면 결과물이 눈에 띄게 좋아진다. Claude도 자신이 만든 결과를 직접 보고 수정할 수 있어야 더 잘한다
사용자 메모리 설정
모든 프로젝트에 공통으로 적용할 규칙은 ~./claude/CLAUDE.md에 한 번만 써두면 된다. 매번 설명하지 않아도 된다
## 언어 및 커뮤니케이션 규칙 - 기본 응답 언어: 한국어 - 코드 주석: 한국어로 작성 - 커밋 메시지: 한국어로 작성 - 변수명/함수명: 영어 (코드 표준 준수)
이 파일은 처음부터 완벽하게 만들 필요가 없다. Claude와 작업하면서 불편한 점이 생길 때마다 조금씩 추가해 나가면 된다
핵심은 1,2 단계다
많은 사람들이 탐색과 계획 없이 바로 코딩으로 뛰어든다. 간단한 작업은 그래도 되지만, 조금이라도 복잡해지면 원하는 결과가 나오지 않는다.
탐색과 계획에 시간을 쓰는 것이 결국 더 빠르다. 처음부터 방향이 잡히면 되돌아가는 일이 줄어들기 때문이다