Claude Code 처음 설치부터 첫 커밋까지: 인디 메이커를 위한 30분 온보딩 가이드

30분 온보딩의 목표

Claude Code를 처음 켤 때 목표는 거창한 기능을 완성하는 것이 아닙니다. 오늘은 “내 프로젝트 폴더에서 AI와 대화하고, 작은 변경을 만들고, 내가 검토한 뒤 커밋한다”까지가 충분합니다. 1인 개발자는 도구를 많이 익히는 것보다 반복 가능한 작업 흐름을 하나 만드는 편이 더 중요합니다.

추천 흐름은 단순합니다.

• 터미널에서 설치 가능 상태 확인
• 계정 로그인 또는 인증 확인
• 기존 프로젝트 폴더 열기
• 아주 작은 기능 또는 문구 수정 요청
• 변경 파일을 직접 확인
• 테스트 또는 실행 확인
• 커밋 메시지 작성 후 커밋

1. 설치 전에 터미널부터 점검하기

먼저 터미널에서 Node.js, 패키지 매니저, Git이 동작하는지 확인합니다. Claude Code 설치 방식은 환경에 따라 달라질 수 있으니, 실제 설치 명령은 공식 문서를 기준으로 확인하는 편이 안전합니다. 핵심은 “설치 명령을 외우는 것”이 아니라 “내 로컬에서 명령형 개발 도구를 실행할 준비가 됐는지”입니다.

체크리스트:

• node -v 또는 프로젝트가 요구하는 런타임 버전 확인
• git --version으로 Git 설치 확인
• 현재 폴더가 실제 작업할 프로젝트인지 확인
• 회사·개인 계정이 섞여 있다면 인증 계정 확인
• 설치 후 새 터미널을 열어 명령이 잡히는지 확인

처음 막히는 지점은 대체로 권한, PATH, 오래된 런타임입니다. 에러 메시지를 그대로 복사해 AI에게 묻기 전에, 어느 명령에서 실패했는지 한 줄로 정리하면 해결 속도가 빨라집니다.

2. 첫 프로젝트 연결은 작은 폴더에서 시작하기

처음부터 큰 프로덕션 저장소를 열면 맥락이 많아져서 판단이 흐려질 수 있습니다. 가능하면 작은 사이드 프로젝트나 복제한 브랜치에서 시작하세요. 터미널에서 프로젝트 루트로 이동한 뒤 Claude Code를 실행하고, 먼저 “이 프로젝트 구조를 읽고 주요 폴더를 요약해줘”처럼 탐색 요청을 합니다.

좋은 첫 질문 예시는 다음과 같습니다.

• “이 프로젝트에서 페이지 라우팅은 어디에 있나요?”
• “설정 파일과 실행 스크립트를 찾아 요약해줘.”
• “수정 전에 관련 파일만 먼저 알려줘.”

여기서 중요한 습관은 바로 수정시키지 않는 것입니다. 먼저 읽게 하고, 수정 후보 파일을 설명하게 한 다음, 작은 범위로 작업을 맡기면 예상 밖 변경을 줄일 수 있습니다.

3. 첫 작업은 ‘기능’보다 ‘작은 변화’로 잡기

첫 커밋용 작업은 10분 안에 사람이 검토할 수 있어야 합니다. 예를 들어 버튼 문구 개선, 빈 상태 메시지 추가, README의 실행 방법 정리, 간단한 폼 검증 문구 수정처럼 영향 범위가 좁은 작업이 좋습니다.

요청은 이렇게 쓰면 실용적입니다.

“홈 화면의 빈 상태 문구를 초보 사용자가 이해하기 쉽게 바꿔줘. 관련 파일을 먼저 찾고, 변경 전 계획을 짧게 말한 뒤 수정해줘.”

수정이 끝나면 git diff로 반드시 확인합니다. AI가 만든 변경이라도 최종 책임은 개발자에게 있습니다. 특히 다음 항목은 직접 봐야 합니다.

• 요청과 무관한 파일이 바뀌었는가
• 문구가 서비스 톤과 맞는가
• 타입, import, 포맷이 깨지지 않았는가
• 환경변수나 비밀값이 노출되지 않았는가

4. 실행 확인 후 커밋하기

변경이 작아도 실행 확인은 건너뛰지 않는 편이 좋습니다. 프로젝트에 맞는 명령이 있다면 lint, test, typecheck, 로컬 실행 중 최소 하나는 돌립니다. 명령이 오래 걸리는 프로젝트라면 수정 범위에 맞는 가벼운 검증부터 시작해도 됩니다.

커밋 전 체크리스트:

• git status로 변경 파일 확인
• git diff로 실제 변경 확인
• 가능한 검증 명령 실행
• 실패했다면 실패 로그를 요약해 원인 파악
• 커밋 메시지는 작업 단위가 드러나게 작성

커밋 메시지는 화려할 필요가 없습니다. Improve empty state copy, Add basic form validation message, Document local setup steps처럼 무엇을 바꿨는지 보이면 충분합니다. 한국어 팀이라면 빈 상태 문구 개선처럼 짧은 한국어도 괜찮습니다.

처음 3일 동안 만들면 좋은 습관

Claude Code는 코드를 대신 쓰는 도구이기도 하지만, 더 유용하게는 작업을 작게 쪼개는 파트너가 될 수 있습니다. 처음 3일은 빠른 결과보다 안전한 루틴을 만드는 데 집중하세요.

추천 루틴:

• 작업 전: “관련 파일을 먼저 찾아줘”
• 수정 전: “변경 계획을 3줄로 말해줘”
• 수정 후: “내가 검토할 포인트를 알려줘”
• 커밋 전: “커밋 메시지 후보 3개를 제안해줘”

1인 빌더에게 좋은 AI 워크플로우는 속도를 올리면서도 통제감을 잃지 않는 방식입니다. 설치 첫날의 성공 기준은 대단한 자동화가 아니라, 작은 변경을 만들고 직접 확인한 뒤 커밋하는 감각을 얻는 것입니다. 그 감각이 생기면 다음부터는 기능 구현, 리팩터링, 테스트 보강으로 자연스럽게 확장할 수 있습니다.