첫 세션 15분 완주: 탐색→변경→테스트→커밋

처음 Claude Code를 켰을 때 가장 중요한 목표는 "대단한 기능 추가"가 아닙니다. 코드베이스를 이해하는 질문을 던지고, 아주 작은 변경을 안전하게 반영한 뒤, 테스트를 통과시키고, Git 커밋으로 저장하는 기본 루프를 한 번 끝까지 완주하는 것입니다. 이 15분짜리 완주 경험이 이후의 리팩터링, 버그 수정, 멀티파일 변경에서 "어디로든 돌아갈 수 있는 안전장치"가 됩니다.

이 챕터에서는 프로젝트와 언어가 무엇이든 적용되는 Quickstart 흐름을 시간 박스로 안내합니다. 화면은 CLI를 기준으로 설명하지만, 핵심은 어디서 실행하든 같습니다.

시작하기 전: 오늘 세션의 '성공 기준'부터 정한다

오늘 세션이 성공하려면 결과물이 반드시 있어야 합니다.

하나는 작은 변경 1개입니다. 예를 들어 문서 오타 수정, 로그 문구 개선, 에러 메시지 명확화, 테스트 한 케이스 추가처럼 "의미는 있지만 범위가 작은 것"이 좋습니다.

다른 하나는 검증(테스트/린트/타입체크 등) 1회 통과와 커밋 1개입니다. 이 두 가지가 끝나면, Claude Code로 개발하는 기본 루프를 이미 갖춘 겁니다.

15분 타이머: 세션 흐름(탐색→변경→테스트→커밋)

아래는 "15분에 끝내는" 템플릿입니다. 실제로는 20분이 걸려도 괜찮습니다. 중요한 건 순서를 지키는 것입니다.

0–2분: 작업 디렉터리 정리(깨끗한 상태에서 출발)

먼저 저장소 루트로 이동한 뒤 상태를 확인합니다. 예를 들어 이미 clone 받아 둔 프로젝트가 ~/work/todo-app에 있다면, cd ~/work/todo-app으로 들어가 그 위치에서 명령을 시작하면 됩니다. 저장소 루트는 보통 .git이 있는 최상위 폴더입니다.

• git status로 현재 브랜치와 미커밋 변경 사항이 없는지 확인합니다.

• 가능하면 새 브랜치에서 시작합니다. (브랜치 전략은 10장에서 다룹니다.)

여기서 핵심은 "문제가 생기면 어디로 돌아갈지"가 분명한 상태를 만드는 겁니다.

2–6분: 탐색(읽기 전용으로 큰 그림 잡기)

처음부터 파일을 열어 읽기 시작하면 길을 잃습니다. 대신 Claude에게 "전체 구조를 요약"하게 하고, 그 요약을 기반으로 다음 질문을 이어갑니다.

(선택) Plan Mode로 안전한 탐색을 고정한다

코드 읽기와 계획 수립이 목적이라면 Plan Mode가 유리합니다. Plan Mode는 읽기 전용 분석 + 계획 제안에 맞춰져 있어, 탐색 중 실수로 파일을 바꾸는 일을 줄여줍니다.¹

• 세션 시작 시: claude --permission-mode plan¹

• 세션 도중 전환: Shift+Tab으로 권한 모드를 순환해 Plan Mode로 이동¹

첫 질문(템플릿)

Claude에게 다음처럼 요청합니다.

이 저장소를 처음 본다. 5분 안에 온보딩할 수 있게 (1) 실행/빌드 방법, (2) 주요 엔트리포인트, (3) 폴더 구조와 책임, (4) 테스트 실행 명령을 추정하되, 근거로 파일 경로를 함께 제시해줘.

이때 Claude Code 문서의 "새 코드베이스 빠르게 이해하기" 워크플로처럼, 개요 → 관련 코드 찾기로 흐름을 잡는 것이 좋습니다.¹

(선택) 탐색 스킬로 "정리된 보고서"를 얻는다

처음 보는 저장소가 크면, 탐색을 자동화하는 스킬이 도움이 됩니다.

• bob:explore는 DISCOVER/ANALYZE/DOCUMENT/COMPLETE 단계로 읽기 전용 탐색을 진행하고, 결과 문서를 파일로 남기는 흐름을 제공합니다.²

• codebase-explorer는 저장소 성격(프론트엔드/백엔드 API/CLI 등)을 분류한 뒤 데이터 흐름과 취약 지점을 추적해 "작동 방식 지도"를 만들도록 설계되어 있습니다.³

오늘은 15분이 목표이므로, 큰 저장소에서만 "보고서 생성"을 옵션으로 쓰는 걸 추천합니다.

6–10분: 변경('한 번에 하나' 원칙으로 아주 작게)

탐색에서 얻은 정보로 "오늘 할 작은 변경"을 고릅니다. 포인트는 파일 1–2개, 동작 1개입니다.

변경 요청 프롬프트(템플릿)

다음 목표를 최소 변경으로 달성하자: (목표 한 줄).

1. 변경할 파일 후보를 2–3개로 좁히고

2. 예상 리스크(부작용)와 검증 방법을 먼저 제시한 뒤

3. 변경을 적용해줘. 변경 후에는 테스트 명령을 실행하고 결과를 요약해줘.

여기서 "검증 방법"을 선행시키면, 변경이 커지는 걸 막고 되돌리기도 쉬워집니다.

10–13분: 테스트(성공/실패 모두 '정보'로 만든다)

Claude가 제시한 테스트 명령이 실제로 맞는지 확인하고 실행합니다. 프로젝트마다 다르지만, 보통은 다음 중 하나입니다.

• npm test, pnpm test, yarn test

• pytest, uv run pytest

• go test ./...

• cargo test

테스트가 실패하면 그 자체가 "오늘 세션의 성과"가 될 수 있습니다. 중요한 건 실패를 붙잡고 30분을 태우는 게 아니라, 실패 원인을 한 문장으로 요약하고 변경 범위를 줄이는 방향으로 한 번만 더 시도하는 겁니다.

13–15분: 커밋('작은 스냅샷'으로 세션을 닫는다)

마지막은 Git 커밋입니다. 여기서부터가 진짜 "안전장치"입니다.

1) 스테이징: 무엇을 커밋에 담을지 선택한다

Git은 변경을 바로 커밋하지 않고, 스테이징 → 커밋의 2단계로 스냅샷을 만듭니다.⁴

가능하면 "오늘 목표와 무관한 포맷팅 변경" 같은 것은 빼고, 목표를 설명할 수 있는 최소 변경만 스테이징합니다.

• CLI라면 git add -p로 일부만 스테이징하는 습관이 큰 도움이 됩니다.⁴

• VS Code를 쓴다면 라인/블록 단위 스테이징이 지원됩니다.⁵

2) 커밋 메시지: 나중에 되돌릴 수 있게 쓴다

커밋 메시지는 "무엇을 했는지"보다 "왜 이게 필요했는지"를 남기는 도구입니다. 팀에서 규칙이 없다면 Conventional Commits 형식이 무난합니다.

Conventional Commits의 기본은 다음 형태입니다.⁶

• <type>(optional scope): <description>

예시:

• fix: handle empty config file

• docs: clarify local setup steps

• test: add case for invalid token

3) 커밋 명령

• 새 파일이 포함되면 git add -A 후 git commit -m "..."이 안전합니다.

• git commit -a는 추적 중인 파일만 자동 스테이징하며 새 파일에는 적용되지 않습니다.⁴

이제 git log --oneline -5로 방금 만든 스냅샷이 남았는지 확인합니다.

'한 번 제대로 끝내보기'가 왜 안전장치가 되는가

Claude Code와 같은 에이전트 코딩에서는, 작은 실수들이 눈덩이처럼 불어 "어디서부터 잘못됐는지 모르는 상태"가 되기 쉽습니다. 그래서 첫 세션에서 익혀야 하는 습관은 딱 두 가지입니다.

첫째, 탐색과 변경을 분리하는 것입니다. Plan Mode 같은 읽기 전용 흐름은 코드베이스를 성급히 건드리지 않게 해 줍니다.¹

둘째, 검증을 통과한 최소 변경을 커밋으로 고정하는 것입니다. 커밋은 '세이브 포인트'이고, 스테이징은 그 세이브에 포함될 내용을 통제하는 장치입니다.⁴⁵

이 두 가지가 갖춰지면, 이후 복잡한 작업은 "한 번에 성공"이 아니라 "작게 실패하고 빨리 돌아오기"로 바뀝니다.

(선택) 다음 단계로 가기 전, 오늘 루프를 더 단단하게 만드는 2가지

1) 세션 종료 체크리스트를 습관으로 만든다

세션을 닫기 전에 다음만 확인해도, 다음 날의 자신을 구할 때가 많습니다.

• git status가 깨끗한가

• 테스트(또는 최소 검증)가 마지막 커밋에서 통과했는가

• 커밋 메시지만 봐도 변경 의도가 이해되는가

2) "원자적(Atomic) 변경"을 연습한다

커밋이 커질수록 Claude도 사람도 디버깅이 어려워집니다. 반대로 커밋이 작고 논리적이면, 되돌리기와 리뷰가 쉬워집니다. Git 가이드도 "논리적 단위로 자주 커밋하라"는 원칙을 강조합니다.⁴

원자적 변경을 강하게 훈련하는 아이디어로는 TCR(test && commit || revert) 같은 방식도 있습니다. 테스트가 통과하면 커밋하고, 실패하면 변경을 되돌리는 흐름이라 "작게, 안전하게"라는 감각을 빠르게 익히는 데 도움이 됩니다.⁷

참고

¹Common workflows - Claude Code Docs

²bob:explore: Read-only codebase exploration workflow | skills.rest

³GitHub - quicksilversurfer/codebase-explorer

⁴Git Guides - git commit · GitHub

⁵Staging and committing changes - Visual Studio Code Docs

⁶Conventional Commits 1.0.0

⁷How to test && commit || revert | by Lars Barlindhaug | Medium