Claude Code 첫 작업 런북: 안전한 프롬프트, diff 검토, handoff

첫 작업이 Claude Code에 대한 신뢰를 결정한다

Claude Code를 설치한 직후에는 “이 기능을 전부 만들어 줘”, “전체 리팩터링을 해 줘”, “이 repo를 다 고쳐 줘”라고 말하고 싶어집니다. 하지만 많은 첫 세션은 여기서 흔들립니다. Claude Code가 쓸모없어서가 아니라, 범위, 검증 방법, 권한, 프로젝트 맥락이 아직 합의되지 않았기 때문입니다.

이 런북은 실제 repository에서 진행하는 첫 실무 작업을 위한 절차입니다. 런북은 같은 상황에서 반복해서 쓰는 작업 체크리스트입니다. 여기서 첫 작업은 “기능 구현”이 아니라 작은 흐름입니다. 잘 요청하고, 계획을 확인하고, 제한된 변경 하나를 만들고, diff를 읽고, handoff note를 남깁니다.

기본 사용이 아직 낯설다면 Claude Code 시작 가이드부터 보세요. 프로젝트 규칙을 남길 때는 Claude Code용 CLAUDE.md 템플릿과 함께 쓰면 좋습니다. 공식 문서는 Claude Code overview, memory와 CLAUDE.md, permission modes, common workflows, CLI reference를 기준으로 확인합니다.

flowchart LR
  A["repository 읽기"] --> B["안전한 후보 3개 제안"]
  B --> C["작업 1개 선택"]
  C --> D["계획 먼저 검토"]
  D --> E["최소 diff 작성"]
  E --> F["test와 diff 검증"]
  F --> G["handoff note 작성"]

좋은 첫 작업의 조건

첫 작업은 결과물의 크기로 평가하지 않습니다. 이 흐름을 계속 믿고 쓸 수 있는지 확인하는 작업입니다. 좋은 첫 작업에는 다섯 가지 조건이 있습니다.

조건	쉬운 뜻	좋은 예
로컬에서 끝남	production, 고객 데이터, 외부 전송을 건드리지 않음	README command 확인, assertion 1개 추가
범위가 작음	파일과 종료 지점이 보임	컴포넌트 1개, test 1개, 문서 1개
검증 가능	command, 화면, diff로 성공을 확인	npm.cmd run test, git diff --check
되돌리기 쉬움	결과가 나쁘면 빨리 버릴 수 있음	generated export가 아닌 일반 source
설명 가능	사람이 변경 이유를 따라갈 수 있음	이유, 리스크, 미확인점이 기록됨

“인증을 전부 다시 만들어 줘”, “전체 코드를 현대화해 줘”, “CI 고치고 배포까지 해 줘”는 첫 작업으로 좋지 않습니다. 부족한 맥락, 권한 확인, 약한 test, 읽기 어려운 diff가 한 번에 섞입니다.

안전한 첫 작업 메뉴

팀 onboarding에서는 먼저 이 메뉴에서 고르는 편이 안전합니다.

작업	도움이 되는 이유	성공 조건
repository 지도 만들기	수정 전 이해도를 확인	entry point, command, 위험 영역이 식별됨
실패 test 1개 요약	debug 단위를 확인	실패 지점, 가설, 다음 최소 행동이 명확함
오래된 README command 수정	낮은 위험의 실제 수정을 시도	command가 실행되고 diff가 작음
기존 test에 assertion 1개 추가	의도와 test 감각을 확인	assertion이 명확한 동작을 보호함
UI 문구 1개 수정	파일 탐색과 최소 수정을 확인	대상 컴포넌트만 변경됨
lint warning 1개 수정	변경 범위 통제를 확인	warning 1개가 줄고 동작은 그대로임
최소 CLAUDE.md 작성	다음 세션 품질을 높임	command, 경계, review 방식이 짧게 정리됨

핵심은 “작지만 실제로 도움이 되는 작업”입니다. onboarding, bug 진단, 문서 정리, test 강화, review 품질 중 하나와 연결되어야 합니다.

바로 복사해 쓸 프롬프트

처음에는 수정이 아니라 읽기와 제안을 요청합니다.

이 repository를 읽고 아직 수정하지 마세요.

다음을 반환하세요.
1. 주요 entry point
2. 자주 쓰는 build/test/lint command
3. 위험한 directory 또는 generated file
4. 30분 첫 세션에 안전한 작업 후보 3개
5. 각 후보의 검증 방법과 rollback 방법

후보가 나오면 하나만 고르고 계획을 요구합니다.

후보 2만 진행합니다. 아직 수정하지 마세요.
먼저 건드릴 파일, 변경 이유, 예상 diff, 검증 command, 리스크를 쓰세요.
범위가 넓어질 것 같으면 더 작은 대안을 제시하세요.

그 다음에만 수정을 허용합니다.

승인한 계획대로 최소 diff로 수정하세요.
요청 밖의 파일은 건드리지 마세요.
수정 후 실행한 검증 command, 실패했거나 생략한 check, 남은 리스크를 요약하세요.

commit 전 review는 별도 prompt로 분리합니다.

commit 전 review를 해 주세요.

1. git diff를 읽고 요청 밖의 변경이 있는지 확인
2. test 부족 또는 검증 부족 확인
3. 보안, 데이터 손실, 설정 변경 리스크 확인
4. commit에 포함되면 안 되는 파일 확인
5. 아직 사람이 판단해야 할 점 확인

결론은 "commit 가능", "수정 후 진행", "중단" 중 하나만 쓰세요.

30분 실행 흐름

처음 5분은 Claude Code에 넘기기 전 현재 상태를 고정합니다. Windows PowerShell에서는 다음을 그대로 씁니다.

Get-Location
git status --short
git branch --show-current
rg --files | Select-Object -First 40

macOS나 Linux에서는 다음을 씁니다.

pwd
git status --short
git branch --show-current
rg --files | head -n 40

worktree가 이미 지저분하다면 어떤 변경이 사람의 작업이며 건드리면 안 되는지 먼저 말합니다. 그렇지 않으면 마지막 diff가 Claude Code의 변경인지 기존 변경인지 판단하기 어렵습니다.

다음 10분은 작업 하나를 고르는 데 씁니다. 오래된 README command, test assertion 1개, 실패 test 1개 요약이 좋은 선택입니다. 첫 세션에서 새 기능은 아직 이릅니다.

20분쯤에는 더 많은 수정이 아니라 증거를 우선합니다. 설명 가능한 올바른 변경 1개가 검증 안 된 변경 3개보다 낫습니다.

git diff --stat
git diff --check
git diff
git status --short

마지막 5분은 handoff note를 남깁니다. handoff note는 다음 사람 또는 다음 Claude Code 세션을 위한 짧은 인계 메모입니다. 긴 대화에서는 처음 정한 경계가 흐려질 수 있으므로, 다음 세션이 깨끗하게 시작하려면 메모가 필요합니다.

구체적인 유스케이스 4가지

유스케이스 1: 새 개발자 onboarding

첫날부터 큰 issue를 주지 마세요. Claude Code에게 repo 지도, 주요 command, 위험 directory, 먼저 읽을 파일을 정리하게 합니다.

프롬프트: “새 개발자를 위한 onboarding note를 작성하세요. 사실과 추측을 분리하고, 가능하면 command output을 포함하세요.” 성공 조건은 README만으로 알기 어려운 실제 맥락이 들어가는 것입니다. generated file, local setting, CI와 local 차이 같은 정보가 유용합니다.

유스케이스 2: 보이는 bug의 재현 메모

bug가 “가끔 깨진다”라면 바로 수정부터 시키지 마세요. 조건, 기대 결과, 실제 결과, 관련 파일, 부족한 log를 정리하게 합니다. Claude Code bug report 템플릿과 함께 쓰기 좋습니다.

성공은 patch가 아닙니다. 사람이 확인할 수 있는 메모입니다. 재현되지 않는다면 그 사실과 추가로 필요한 log나 데이터를 적어야 합니다.

유스케이스 3: 문서 또는 UI 문구 수정

marketing site, admin tool, 내부 dashboard는 첫 세션에 잘 맞습니다. 문구 변경은 눈에 보이고 되돌리기 쉽기 때문입니다. 단, 한 CTA, 한 setting 설명, 한 문단처럼 좁혀야 합니다.

성공 조건은 대상 파일만 바뀌고, 의미가 유지되고, 로컬에서 결과를 확인할 수 있는 것입니다. 다국어 site라면 한 언어만 바꾸고 다른 언어를 방치하지 않았는지도 확인합니다.

유스케이스 4: 작은 test 개선

프로젝트에 test가 있다면 새 기능보다 assertion 1개 추가가 안전합니다. 경계값, error message 기대값, empty list case 같은 단위가 좋습니다.

test가 통과하는 것만으로는 부족합니다. Claude Code가 그 assertion이 어떤 동작을 보호하는지 설명해야 합니다. 설명할 수 없는 assertion은 나중에 유지보수 noise가 됩니다.

commit 전 diff review

Claude Code가 파일을 수정한 뒤에는 사람의 review로 돌아옵니다. 첫 작업에서는 자동 commit과 push를 피합니다. permission modes는 편의성과 감독의 균형이므로, 처음에는 일반 review 또는 plan mode로 시작하세요. bypass permissions 같은 강한 모드는 격리 환경이 아니면 피하는 편이 안전합니다.

commit 전 checklist

[ ] 요청한 파일만 변경됨
[ ] generated file, secret, local setting이 섞이지 않음
[ ] test 또는 대체 검증 결과가 기록됨
[ ] 실패하거나 생략한 check가 공개됨
[ ] 설명할 수 없는 diff가 없음
[ ] handoff note에 다음 TODO가 있음

먼저 git diff --stat으로 변경 범위를 봅니다. git diff --check로 whitespace와 patch hygiene을 봅니다. 마지막으로 diff 본문을 읽고 갑작스러운 refactor, 이름 변경, test 없는 동작 변경이 없는지 확인합니다.

자주 생기는 실패

첫 번째 실패는 범위가 너무 큰 것입니다. “login을 고쳐 줘”가 아니라 “login error message를 test 1개로 확인해 줘”라고 말합니다. 자율성은 작은 작업에서 신뢰가 생긴 뒤에 줘도 충분합니다.

두 번째 실패는 증거 없이 “완료”를 받아들이는 것입니다. test가 없다면 대체 증거를 먼저 정합니다. render된 page, type check, git diff --check, log 비교, README command 실행 중 하나는 남겨야 합니다.

세 번째 실패는 permission prompt를 대충 승인하는 것입니다. prompt가 나오면 어떤 command인지, 어떤 path를 만지는지, network나 삭제가 포함되는지 확인합니다. prompt가 너무 많다면 모든 권한을 풀기보다 좁은 command만 허용합니다.

네 번째 실패는 context loss입니다. 긴 대화에서는 처음 정한 경계가 흐려집니다. 작업 경계, 실행한 command, 남은 리스크를 handoff note에 남기세요. 영구 규칙인 CLAUDE.md와 이번 세션만의 메모를 섞지 않는 것도 중요합니다.

다섯 번째 실패는 commit되지 않은 기존 작업을 망가뜨리는 것입니다. 공유 repo에서는 다른 개발자나 다른 agent가 이미 변경했을 수 있습니다. git status --short로 시작하고 관련 없는 변경은 건드리지 말라고 명시하세요.

Handoff note 템플릿

첫 작업 끝에 그대로 붙여 넣습니다.

## Handoff note

- Task:
- Changed files:
- Verification run:
- Verification not run:
- Important diff points:
- Remaining risks:
- Do not touch next time:
- Suggested next smallest task:

이 메모는 commit message보다 넓은 정보입니다. commit 전에는 PR 설명 초안이 되고, commit하지 않는 경우에는 다음 세션의 시작점이 됩니다.

다음 단계와 유료 경로

첫 작업이 성공했다면 반복 가능성을 만드세요. 혼자 쓰는 경우 반복되는 규칙은 CLAUDE.md 템플릿으로 옮깁니다. approvals와 sandbox가 아직 헷갈린다면 Claude Code approval and sandbox guide를 읽어 보세요.

바로 쓸 수 있는 template, checklist, onboarding 자료가 필요하면 /products/를 확인하세요. 팀 rollout, repository 맞춤 onboarding, permission design, review workflow까지 정리하려면 /training/을 이용하면 됩니다. 안전한 첫 작업 하나는 이 글로 충분합니다. 팀 전체로 넓히려면 규칙, 증거, 교육을 먼저 갖추는 편이 안정적입니다.

Masa가 실제로 시험했을 때 가장 안정적인 패턴은 repo를 먼저 읽고, 한 파일만 수정하고, git diff를 함께 보고, handoff note를 남기는 방식이었습니다. 큰 요청으로 시작한 세션은 절약한 시간보다 review 비용이 더 컸습니다. 30분짜리 작은 작업을 성공시킨 세션은 두 번째 작업의 범위를 정하고 팀원에게 설명하기가 훨씬 쉬웠습니다.