첫 프로젝트 시작하기

🎯 학습 목표

이 강을 마치면 기존 프로젝트 폴더에서 클로드 코드를 처음 실행하고, 코드베이스 전체를 파악한 뒤 첫 번째 수정을 안전하게 요청하는 흐름을 익힐 수 있습니다. 또한 프로젝트 이해를 돕는 /init 명령과 기본 슬래시 커맨드들도 함께 알게 됩니다.

💡 왜 프로젝트 폴더 안에서 시작해야 하는가

이 섹션에서는 클로드 코드를 실행하는 위치가 왜 중요한지 살펴보겠습니다. 클로드 코드는 실행된 현재 폴더를 작업 기준점(working directory)으로 삼아 그 하위의 파일들을 탐색하고 수정합니다. 필요한 파일을 미리 손으로 첨부할 필요 없이, 요청 내용에 따라 클로드 코드가 알아서 관련 파일을 찾아 읽습니다. 이 점이 일반 채팅형 AI 서비스와의 가장 큰 차이입니다. 일반 채팅에서는 코드를 매번 직접 복사해서 붙여넣어야 하지만, 클로드 코드는 터미널 안에서 파일 시스템에 직접 접근하기 때문에 이런 번거로운 과정이 필요 없습니다. 그래서 프로젝트와 전혀 관계없는 폴더에서 실행하면, 정작 작업하려는 코드에 접근하지 못하는 상황이 생길 수 있습니다.

따라서 첫 실행은 반드시 작업할 프로젝트의 루트 폴더에서 시작해야 합니다. 만약 다른 위치에서 실행했다면, 도구를 종료하고 cd로 프로젝트 폴더로 이동한 뒤 다시 실행하는 것이 안전합니다. 특히 여러 개의 하위 프로젝트가 모여 있는 모노레포 구조라면, 어느 폴더를 기준으로 실행하느냐에 따라 탐색 범위가 크게 달라지므로 더욱 신경 써야 합니다.

💬 첫 실행부터 코드베이스 파악까지

이 섹션에서는 첫 실행 이후의 표준적인 흐름을 정리하겠습니다.

단계	내용
1. 폴더 이동	cd my-project로 프로젝트 루트로 이동
2. 실행	claude 명령으로 시작
3. 전체 구조 파악	코드베이스 개요를 요청하는 질문
4. 첫 수정 요청	작고 명확한 범위의 수정부터 시작

1강에서 다룬 것처럼 클로드 코드는 프로젝트 폴더에 CLAUDE.md 파일이 있으면 시작할 때 자동으로 읽어들여, 기술 스택이나 코딩 규칙 같은 맥락을 미리 파악합니다. 아직 이 파일이 없는 새 프로젝트라면, 잠시 후 다룰 /init 명령으로 손쉽게 만들 수 있습니다.

여러 프로젝트를 오가며 작업하는 경우라면, 각 프로젝트 폴더에서 처음 claude를 실행할 때마다 이 흐름을 습관처럼 반복하는 것이 좋습니다. 프로젝트마다 기술 스택과 코드 스타일이 다르므로, "이 프로젝트는 이렇게 되어 있구나"를 매번 새로 확인하는 과정이 결국 더 정확한 결과로 이어집니다.

💻 실전 사례 — 코드베이스 개요 파악하고 첫 수정 요청하기

이 섹션에서는 실제로 어떤 질문부터 시작하면 좋은지 살펴보겠습니다.

[1단계 — 전체 구조 파악]
이 프로젝트가 어떤 기술 스택으로 만들어졌는지, 폴더 구조가
어떻게 되어 있는지 설명해줘.

[2단계 — 핵심 파일 확인]
사용자 로그인 관련 로직은 어느 파일에 있어?

[3단계 — 작은 범위의 첫 수정]
로그인 페이지의 에러 메시지 문구를 "이메일 또는 비밀번호가
올바르지 않습니다"로 바꿔줘.

처음부터 "로그인 기능을 완전히 새로 만들어줘" 같은 큰 요청을 하기보다, 위 예시처럼 구조 파악 → 관련 파일 확인 → 작은 수정 순서로 시작하는 것이 안전합니다. 이 과정에서 클로드 코드가 프로젝트를 어떻게 이해하고 있는지, 응답 속도와 스타일은 어떤지 감을 잡을 수 있고, 작은 수정이 잘 반영되는 것을 확인한 뒤 점점 더 큰 작업으로 넘어갈 수 있습니다.

1단계에서 얻은 구조 설명을 바탕으로, 궁금한 부분을 계속 이어서 물어볼 수도 있습니다.

[이어지는 질문]
방금 설명한 폴더 구조에서, API 요청 로직은 보통 어디에
작성되어 있어? 예시 파일 하나만 보여줘.

이렇게 이전 답변을 기반으로 후속 질문을 이어가면, 매번 새로운 설명을 요청하지 않고도 점점 더 구체적인 이해에 도달할 수 있습니다. 이 원리는 프롬프트 엔지니어링에서 다루는 멀티턴 대화 설계와도 맞닿아 있으며, 4강 "컨텍스트 최대한 활용하기"에서 더 깊이 다룰 예정입니다.

⚠️ 자주 하는 실수 / 주의점

실수 1 — 프로젝트 루트가 아닌 하위 폴더나 상위 폴더에서 실행하는 것. 잘못된 위치에서 실행하면 관련 없는 파일까지 탐색 범위에 들어오거나, 반대로 필요한 파일에 접근하지 못할 수 있습니다. 항상 프로젝트의 최상위 루트에서 시작하는 것이 기본입니다.

실수 2 — 코드베이스 파악 없이 곧바로 큰 작업을 요청하는 것. 처음 보는 프로젝트에 대해 충분한 맥락 없이 "이 기능 통째로 만들어줘"라고 요청하면, 기존 코드 스타일이나 구조와 어긋나는 결과가 나올 수 있습니다. 먼저 구조를 물어보고 시작하는 습관이 훨씬 안정적입니다. 몇 분만 투자해 구조를 파악해두면, 이후 요청들이 훨씬 정확하고 일관된 결과로 돌아온다는 것을 체감할 수 있습니다.

실수 3 — 첫 결과를 검증 없이 그대로 커밋하는 것. 첫 수정이 잘 되었더라도, 실제로 실행해보거나 관련 테스트를 돌려 정상 동작을 확인한 뒤 다음 단계로 넘어가는 것이 안전합니다. 이 습관은 프로젝트가 커질수록 더욱 중요해지며, 처음에는 번거롭게 느껴져도 나중에 예상치 못한 문제를 되돌리는 시간을 훨씬 크게 절약해줍니다. 특히 여러 파일에 걸쳐 있는 변경이라면, 커밋하기 전에 git diff로 실제 변경 내용을 한 번 훑어보는 습관도 함께 들이는 것이 좋습니다.

🚀 CLAUDE.md 자동 생성과 기본 명령어

새 프로젝트라 아직 CLAUDE.md가 없다면, /init 명령을 실행해보시기 바랍니다. 이 명령은 프로젝트 구조를 스캔해 빌드·테스트 명령어, 아키텍처 패턴, 코드 컨벤션 등을 정리한 CLAUDE.md 초안을 자동으로 생성해줍니다. 생성된 내용은 그대로 쓰기보다, 실제 프로젝트 사정에 맞게 한 번 검토하고 다듬는 것이 좋습니다. 최근에는 /init이 단순히 파일 구조만 스캔하는 데 그치지 않고, 반복되는 작업이나 팀이 선호하는 작업 방식에 대해 몇 가지를 직접 물어본 뒤 그 답변까지 반영해 훨씬 완성도 높은 CLAUDE.md를 만들어주는 방향으로 개선되었습니다. 이 외에도 /help로 사용 가능한 명령어 목록을 확인할 수 있고, /resume으로 이전에 나눴던 대화를 이어갈 수 있습니다. 이런 기본 명령어들은 15강 "CLAUDE.md 마스터 가이드"와 16강 "슬래시 커맨드 전체 정복"에서 훨씬 자세히 다룹니다. 지금 단계에서는 모든 명령어를 외우기보다, /help를 습관적으로 눌러보며 필요할 때마다 하나씩 익혀가는 정도로 충분합니다.

📝 핵심 요약

• 클로드 코드는 실행된 폴더를 기준으로 파일을 탐색하므로, 반드시 프로젝트 루트에서 시작해야 합니다.
• 첫 작업은 구조 파악 → 관련 파일 확인 → 작은 수정 순서로 진행하는 것이 안전합니다.
• 충분한 맥락 파악 없이 큰 작업을 곧바로 요청하는 것은 피해야 합니다.
• /init 명령으로 CLAUDE.md를 자동 생성하고, /help·/resume 같은 기본 명령어도 함께 익혀두면 좋습니다.

다음 강에서는 클로드 코드에게 원하는 결과를 정확히 얻어내는 효과적인 프롬프트 작성법을 다루겠습니다.

📚 참고 자료

• Quickstart — Claude Code 공식 문서
• Commands — Claude Code 공식 문서