Claude Code로 남의 코드에 들어가는 첫 1시간: 고치기 전에 지도부터 그린다

인수인계 첫날, 저는 전임자가 남긴 사내 도구 저장소를 열었습니다. README는 세 줄, 마지막 수정은 8개월 전. 일단 Claude Code에게 “이 프로젝트를 파악하고, 로그인 화면 문구를 고쳐줘”라고 부탁했더니, 5분 뒤에는 인증 관련 설정 파일과 아무도 손대지 않던 운영 배포용 스크립트까지 “겸사겸사 정리”되어 있었습니다.

다행히 git status로 알아차리고 전부 되돌렸습니다. 하지만 알아차리지 못한 채 git commit을 눌렀다면 어땠을까 생각하면 지금도 등골이 서늘합니다. 문제는 모델이 똑똑하냐가 아니었습니다. 제가 어디를 건드려도 되는지 모른 채 작업을 통째로 맡긴 것이 문제였습니다.

남의 코드에 들어가는 첫 1시간은 고치는 시간이 아니라 지도를 그리는 시간입니다. 이 글에서는 그 지도를 그리는 방법을, 처음 보는 저장소에서도 사고가 나지 않는 순서로 정리합니다.

핵심 요약

• 첫 1시간은 “고치기”가 아니라 “지도 그리기”. 건드려도 되는 곳과 건드리면 안 되는 곳을 먼저 나눈다.
• Claude Code에게 맡기는 건 “읽고 목록으로 만들기”까지. 무엇을 보호 영역으로 둘지는 사람이 정한다.
• 수정에 들어가기 전에 반드시 검증 명령(빌드나 테스트)을 하나 정해 둔다. 이것이 “고쳐졌다”의 증거가 된다.
• 첫 수정은 git 한 줄로 되돌릴 수 있는 작은 것으로 한정한다.
• 파악한 내용은 메모 한 장에 남긴다. 다음에 같은 저장소에 들어오는 사람(미래의 자신 포함)이 같은 조사를 반복하지 않도록.

왜 첫 1시간에 사고가 나는가

새 저장소에서 발이 걸리는 건 대개 코드가 어려워서가 아닙니다. 저장소의 형태가 보이지 않는 것이 원인입니다.

어느 폴더가 화면이고, 어디가 뒤쪽 로직이고, 어떤 파일이 운영 설정인지. 이걸 모르는 채로 “알아서 잘 고쳐줘”라고 부탁하면, Claude Code는 선의로 넓은 범위를 다시 씁니다. AI는 “여기는 건드리지 마”라는 말을 듣지 않는 한, 손대도 되는 곳이라고 판단하기 때문입니다.

특히 인수인계 건은 위험합니다. 전임자의 암묵적인 규칙, 네이밍 습관, 왜인지 남아 있는 주석 처리된 코드. 이런 맥락은 코드 어디에도 적혀 있지 않습니다. 사람도 첫날에 전부 알 수는 없습니다. 그래서 가장 먼저 할 일은 편집이 아니라 지도 만들기가 됩니다.

지도를 그리는 4단계

순서가 중요합니다. 읽을 범위를 정하고, 보호 영역을 정하고, 검증 명령을 정하고, 마지막에야 작게 하나 고친다. 이 순서로 갑니다.

1단계: 오늘의 목표를 한 문장으로 적는다

“이 프로젝트를 이해한다”는 너무 넓습니다. Claude Code도 사람도, 넓은 목표 앞에서는 멈출 자리를 잃어버립니다.

대신 이렇게 적습니다. “로그인 화면 문구를 딱 한 곳만 고치고, 빌드가 통과하는지 확인한다.” 한 문장으로 말할 수 있는 목표는, 끝났는지 아닌지도 한눈에 알 수 있습니다.

2단계: 읽을 범위와 건드리면 안 되는 범위를 나눈다

여기가 지도의 핵심입니다. Claude Code에게 “전부 읽어도 돼”라고 넘기기 전에, 건드리면 안 되는 곳을 먼저 말로 적습니다.

제가 매번 보호 영역에 넣는 건 인증, 결제, 환경 변수 파일(.env), 운영 배포 스크립트입니다. 이것들은 잘못 건드리면 피해가 크고, 게다가 되돌리기 어렵습니다. 그래서 처음에는 “읽는 건 괜찮지만 쓰지는 마”라고 명시합니다.

3단계: 검증 명령을 먼저 정한다

“고쳤습니다”라는 말을 들어도, 무엇을 근거로 고쳐졌다고 할 수 있을까요. 그걸 먼저 정해 둡니다.

많은 프로젝트에서는 빌드 명령이나 테스트 명령이 검증이 됩니다. npm run build가 통과한다, npm test가 초록색이 된다. 이 한 줄을 수정에 들어가기 전에 정해 두면, Claude Code의 “다 됐어요”를 곧이곧대로 믿지 않고 기계의 합격/불합격으로 판단할 수 있습니다.

4단계: 되돌릴 수 있는 작은 수정 딱 하나

지도가 완성되면, 첫 수정은 욕심내지 않는 게 핵심입니다. 문구 수정, 주석 추가, 명백한 오타 고치기처럼 git checkout 한 번으로 되돌릴 수 있는 것을 하나 고릅니다.

“겸사겸사 저것도”를 참습니다. 큰 diff는 아무도 리뷰할 수 없고, 사고가 났을 때 되돌리기도 힘들어집니다.

Claude Code에게 맡길 범위와, 사람이 정할 범위

지도 만들기에서 무엇을 맡기고 무엇을 직접 쥘 것인가. 여기를 섞으면 서두의 사고가 납니다.

작업	담당	이유
파일 목록이나 폴더 구조 파악	Claude Code	기계적인 읽기는 빠르고 정확하다
”이 기능은 어디 있지?” 조사	Claude Code	검색과 요약이 강하다
무엇을 보호 영역으로 둘지	사람	피해 규모는 맥락에 달려 있다. AI는 모른다
검증 명령의 최종 결정	사람	프로젝트 고유 사정을 아는 건 사람
운영·결제·인증 변경	사람	되돌리기 어려운 작업은 사람이 승인한다

원칙은 단순합니다. 읽는 것·목록으로 만드는 것은 맡긴다. 되돌리기 어려운 판단은 사람이 쥔다. 안전하다고 확인된 작업만, 나중에 Claude Code에게 한 단계씩 승격시켜 갑니다.

권한의 세세한 설계는 다른 글에 정리했습니다. 처음에 무엇을 막을지 고민된다면 권한 가이드를 보세요.

복사해서 쓰는 지도 만들기 프롬프트

첫 1시간에 제가 실제로 던지는 프롬프트입니다. 그대로 붙여 넣고, 저장소 이름만 자기 것으로 바꾸세요.

이 저장소를 처음 다룹니다. 아직 아무것도 편집하지 마세요.
아래를 순서대로 조사해서, 결과를 글머리 기호로 보고해 주세요.

1. 최상위 폴더 구성과 각각의 역할(추측이어도 좋지만 추측이라고 명시)
2. 빌드·테스트·실행에 쓰는 명령(package.json이나 README에서)
3. 인증·결제·환경 변수·운영 배포에 관련된 파일의 위치
4. "로그인 화면 문구"가 어느 파일에 있는지

보고 후, 3의 파일들은 이번에 "읽기만·편집 금지"로 합니다.
편집해도 되는 건 4에서 찾은 파일 하나뿐입니다.

핵심은, 첫 줄에서 “아직 편집하지 마”라고 못을 박는 것입니다. 이게 없으면 조사하는 김에 고치기 시작하는 AI가 있습니다.

복사해서 동작하는 검증 스크립트

지도가 완성되면, 수정 전후로 같은 체크를 돌릴 수 있게 해 두면 안심입니다. 다음 스크립트는 변경 전후로 빌드가 통과하는지, diff가 너무 넓어지지 않았는지를 확인합니다. Node.js로 동작합니다.

// verify-edit.mjs
// 수정 전후로 빌드가 통과하는지, diff가 예상보다 크지 않은지 확인한다
import { execSync } from "node:child_process";

// 한 줄로 되돌릴 수 있는 범위인지, 변경 파일 수의 상한을 정해 둔다
const MAX_CHANGED_FILES = 3;

function run(cmd) {
  return execSync(cmd, { encoding: "utf8" }).trim();
}

try {
  // 변경된 파일의 수를 센다
  const changed = run("git diff --name-only")
    .split("\n")
    .filter(Boolean);

  console.log(`변경 파일 수: ${changed.length}`);
  changed.forEach((f) => console.log(`  - ${f}`));

  if (changed.length > MAX_CHANGED_FILES) {
    console.error(
      `diff가 너무 넓습니다 (${changed.length} > ${MAX_CHANGED_FILES}).`,
    );
    console.error("일단 git checkout으로 되돌리고, 수정을 작게 나누세요.");
    process.exit(1);
  }

  // 보호 영역에 손이 들어가지 않았는지 확인한다
  const protectedHits = changed.filter((f) =>
    /(^|\/)\.env|auth|billing|deploy/i.test(f),
  );
  if (protectedHits.length > 0) {
    console.error("보호 영역에 변경이 들어왔습니다:");
    protectedHits.forEach((f) => console.error(`  - ${f}`));
    process.exit(1);
  }

  // 빌드가 통과하는지 확인한다 (프로젝트에 맞게 교체)
  console.log("빌드를 확인합니다...");
  run("npm run build");
  console.log("빌드 OK. 수정은 안전 범위 안에 들어 있습니다.");
} catch (err) {
  console.error("검증에 실패했습니다:", err.message);
  process.exit(1);
}

node verify-edit.mjs로 실행합니다. 변경 파일이 너무 많거나, 보호 영역에 손이 들어갔으면 그 자리에서 멈춥니다. 서두의 “인증 파일까지 정리된” 사고는, 이 스크립트를 통과시켰다면 미리 막혔을 것입니다.

효과가 있는 장면 세 가지

구체적으로 어떤 저장소에서 쓸 수 있는지, 제가 시험해 본 세 가지 패턴을 들겠습니다.

1. 인수인계받은 사내 도구 문서가 없는 코드베이스에 들어갈 때. 먼저 폴더 구성과 실행 명령을 목록화하게 하고, 인증과 설정 파일을 보호 영역으로 고정합니다. 첫 수정은 관리 화면의 라벨 변경처럼, 눈으로 결과가 보이는 것으로 합니다.

2. 공개 저장소에 첫 기여 남의 오픈소스에 처음 Pull Request를 낼 때. 테스트 명령을 먼저 특정하게 하고, npm test가 초록색인 채로 작은 수정을 하나 냅니다. 넓은 개선 제안보다, 되돌릴 수 있는 한 파일 수정이 더 잘 받아들여집니다.

3. 오래된 프로젝트 재시작 반년 방치한 코드를 재개할 때. “어디까지 동작하는지”를 Claude Code에게 조사하게 하고, 망가진 입구를 지도화합니다. 고치는 건 가장 되돌리기 쉬운 한 곳부터 합니다.

함정과 고치는 법

함정 1: 한 번에 전부 고치려 한다 “겸사겸사 리팩터링도”로 diff가 50개 파일로 부풀면, 아무도 리뷰할 수 없습니다. 고치는 법은, 위의 검증 스크립트로 변경 파일 수에 상한을 두는 것. 넘으면 일단 되돌리고 분할합니다.

함정 2: 빌드 성공만으로 완료로 친다 로컬에서 빌드가 통과해도, 화면이 의도대로라는 보장은 없습니다. 문구 수정이라면, 실제로 그 화면을 열어 글자를 눈으로 확인하는 데까지가 한 세트입니다.

함정 3: 보호 영역을 말로만 전한다 “인증은 건드리지 마”라고 프롬프트로 말해도, 긴 작업 도중에 잊힐 수 있습니다. 고치는 법은, 검증 스크립트로 보호 영역 변경을 기계적으로 튕겨내는 것. 사람의 기억이 아니라 명령으로 지킵니다.

함정 4: 조사한 지도를 남기지 않는다 모처럼 1시간을 들여 파악해도, 메모를 남기지 않으면 다음에 또 같은 조사를 합니다. 폴더 구성, 검증 명령, 보호 영역을 메모 한 장에 적어 두면 미래의 자신이 살아납니다.

그 지도 메모는 프로젝트의 규칙으로 CLAUDE.md에 적어 두면 더 효과가 있습니다. 쓰는 법은 CLAUDE.md 베스트 프랙티스에 정리했습니다.

자주 묻는 질문

Q. 첫 1시간, 정말 아무것도 안 고쳐도 되나요? A. 고쳐도 괜찮지만, 고치는 건 “되돌릴 수 있는 작은 한 곳”만으로 합니다. 나머지 시간은 지도 만들기에 쓰는 편이, 결과적으로 사고가 줄고 더 빠릅니다.

Q. Claude Code에게 “전부 읽어도 돼”라고 넘기는 건 위험한가요? A. 읽기만 한다면 위험하지 않습니다. 위험한 건 “쓰기” 권한입니다. 읽기는 넓게, 쓰기는 좁게. 이게 기본 분배입니다.

Q. 검증 명령을 모르는 프로젝트는 어떻게 하나요? A. 먼저 Claude Code에게 package.json이나 README에서 후보를 뽑게 합니다. 그래도 모르겠으면, 일단 git status로 diff가 나오지 않는 것만을 최소한의 검증으로 삼습니다.

Q. PowerShell에서도 같은 걸 할 수 있나요? A. 할 수 있습니다. git diff --name-only의 결과를 세어 상한과 비교하는 로직은 PowerShell에서도 그대로 쓸 수 있습니다. 검증 스크립트는 쓰는 환경에 맞게 바꿔 쓰세요.

Q. 이 절차는 초보자도 돌릴 수 있나요? A. 돌릴 수 있습니다. 오히려 초보자일수록 효과가 큽니다. 코드를 완전히 이해하지 못해도, “건드려도 되는 곳”을 먼저 정하면 큰 사고는 막을 수 있습니다. 기초부터 다지고 싶은 사람은 입문 가이드를 먼저 읽으면 수월합니다.

실제로 시험해 본 결과

이 절차는 서두의 사고 이후에 제가 제 용도로 만든 것입니다. 시험해 보고 가장 효과가 컸던 건, 검증 스크립트에 “변경 파일 수 상한”과 “보호 영역 자동 체크”를 넣은 것이었습니다.

실제로 인수인계받은 저장소에서 세 번쯤 돌렸더니, 한 번은 변경 파일 수가 상한을 넘어 멈췄습니다. 안을 보니 Claude Code가 문구 수정하는 김에 공통 컴포넌트까지 다시 쓰고 있었고, 만약 통과시켰다면 영향 범위를 읽을 수 없는 diff가 되어 있었을 겁니다. 멈춰 준 덕분에, 수정을 둘로 나눠서 낼 수 있었습니다.

“똑똑한 AI에게 맡기면 괜찮아”가 아니라, “넘어져도 되돌릴 수 있는 범위에서 맡긴다.” 지도를 먼저 그리는 것만으로 첫 1시간의 손맛이 완전히 달라졌습니다. 엔지니어가 아닌 사람이 팀에서 이 분배를 공유하고 싶다면, 비엔지니어를 위한 입구도 도움이 됩니다.

Claude Code의 공식 사용법은 Anthropic 공식 문서에서도 확인할 수 있습니다. 손에 익은 운영 규칙을 굳혀서 팀에서 재현 가능한 형태로 만들고 싶은 사람은, 연수·상담에서 구체적인 저장소를 함께 지도화해 갑니다.