빠른 흐름
npm install -g @anthropic-ai/claude-code
cd /path/to/project
claude시작 흐름
프로젝트 루트에서 시작해야 하는 이유
Claude Code는 terminal-first 도구입니다. 설치 후 반드시 프로젝트 루트에서 claude를 실행해야 합니다. 루트에서 실행해야 파일 시스템 접근과 컨텍스트 파악이 올바르게 이루어지기 때문입니다. 엉뚱한 디렉터리에서 시작하면 Claude Code가 코드베이스 구조를 잘못 읽거나 파일 수정 범위가 의도와 달라질 수 있습니다.
큰 작업보다 작은 확인부터 시작해야 하는 이유
처음부터 대규모 리팩터링을 시키는 것보다 코드베이스 개요 파악과 작은 수정부터 시작하는 편이 좋습니다. "이 프로젝트 구조 설명해줘", "이 버그 원인 찾아줘", "테스트 깨진 이유 보여줘" 같은 탐색 요청이 첫 세션에 잘 맞습니다. 이 과정에서 Claude Code가 어떻게 파일을 읽고 판단하는지를 확인하면, 이후 더 큰 작업을 맡길 때 변경 범위를 조정하기 쉬워집니다.
> give me an overview of this codebase
> find the files that handle authentication
> fix the failing test in user-service
> commit the changes with a descriptive message요청에 변경 범위와 검증 기준을 함께 줘야 하는 이유
Claude Code의 강점은 단순 답변이 아니라 action입니다. 파일 수정, 명령 실행, Git 관련 작업까지 이어질 수 있기 때문에, 요청을 할 때 변경 범위와 검증 기준을 같이 주는 편이 좋습니다. "user-service의 테스트만 고쳐줘, 다른 파일은 건드리지 마"처럼 범위를 명확히 하면 의도치 않은 파일 변경을 줄일 수 있습니다.
약한 요청
-> "로그인 버그 고쳐줘"
강한 요청
-> "login-service 테스트를 재현하고
auth/ 아래만 수정하고
테스트 통과 결과까지 보여 줘"approvals와 검증 단계를 세션 운영의 일부로 보는 이유
quickstart의 핵심은 설치보다 세션 운영 감각입니다. 작은 요청으로 신뢰를 쌓고, approvals와 검증 단계를 거치며 범위를 넓히는 흐름이 가장 안정적입니다. 한 번에 너무 많은 변경을 허용하면 어떤 부분이 의도한 변경인지 추적하기 어려워지고 롤백도 복잡해집니다.
언제 이 흐름이 맞나
| 상황 | 적합한 선택 |
|---|---|
| 처음 설치 후 | 프로젝트 루트에서 claude 실행 |
| 첫 세션 작업 | 코드 개요 파악과 작은 수정부터 시작 |
| 수정 범위 제어 | 변경 범위와 검증 기준을 요청에 포함 |
| 세션 중 계정 변경 | interactive session에서 /login 사용 |
| 범위 확장 시 | 작은 신뢰 구축 후 단계적으로 넓히기 |
| 기존 컨텍스트를 버리고 완전히 다시 시작 | 새 디렉터리에서 새 세션 |
주의할 점
Claude Code는 바로 큰 리팩터링부터 맡기기보다, 먼저 코드베이스 설명과 작은 수정으로 세션 감각을 맞추는 편이 좋습니다. 요청 범위와 검증 기준을 함께 주면 훨씬 안정적으로 동작합니다. action 기반 도구이므로 승인 없이 파일이 수정될 수 있다는 점을 항상 염두에 두세요.
❌ ~/Desktop 에서 claude 실행
❌ "전체 인증 구조 갈아엎어"
❌ 검증 기준 없음이 패턴은 잘못된 루트에서 파일을 읽거나, 변경 범위가 불필요하게 커지고, 완료 여부도 모호해지기 쉽습니다.
참고 링크
2 sources