기존 저장소에 Claude Code를 넣는 첫날, 망치지 않고 첫 작업 하나를 고르는 법

이직하고 3일째 되던 날, 저는 파일이 150개쯤 되는 결제 관련 코드를 통째로 받았습니다. 문서는 거의 없었죠. 누구한테 물어봐도 “지금 잘 돌아가니까 별로 건드리고 싶지 않아요”라는 대답뿐이었습니다. 일단 Claude Code에 “이 저장소를 파악하고, 신경 쓰이는 부분은 알아서 고쳐 줘”라고 부탁해 봤습니다.

10분 뒤, Claude는 자신만만하게 “파일 20개를 정리했습니다”라고 답했습니다. 차이(diff)를 열어 보고 등골이 서늘해졌습니다. 마이그레이션용 SQL 파일을 줄 맞춤하고, .env.example을 알파벳순으로 다시 정렬하고, 게다가 결제 재시도 대기 시간을 멋대로 “최적화”해서 절반으로 줄여 놨더군요. 문법적으로는 돌아가는 코드였습니다. 하지만 그대로 운영 환경에 나갔다면, 이중 결제 문의 전화가 끊임없이 울렸을 겁니다.

문제는 Claude가 똑똑하지 않아서가 아닙니다. 첫날 넘긴 범위가 너무 넓었을 뿐입니다. 남이 짠 거대한 코드를 안전하게 맡기려면, 더 똑똑한 AI를 찾기 전에 “읽는 순서·손대지 못하게 할 곳·첫 작은 일·확인 방법”을 30분 안에 정해 두면 됩니다. 이것만으로 첫날의 사고는 거의 사라집니다. 오늘은 그 30분의 내용을 복사해서 바로 쓸 수 있는 형태로 정리합니다.

핵심 요약

• 기존 코드의 첫날에는 “전부 보고 고쳐 줘”가 가장 위험합니다. 범위가 흐릿한 채로 달리기 시작하기 때문입니다.
• 첫 30분에 만드는 건 설계서가 아니라, 첫 작업 하나를 안전하게 고르기 위한 한 장짜리 메모입니다.
• 메모에 적을 건 네 가지뿐입니다. 읽는 순서, 손대지 못하게 할 곳, 첫 작은 일, 끝났다고 판단하는 확인 명령.
• 첫 일은 “되돌리기 쉬운 곳”으로 한정합니다. 문장, 버튼 문구, 테스트 이름쯤이 딱 좋습니다.
• AI에 맡기는 건 “조사하기·초안 만들기”까지. 운영 DB·결제·삭제·배포 버튼은 사람이 누릅니다.

왜 첫날 첫 지시에서 넘어지는가

Claude Code는 빠릅니다. 빠르기 때문에, 처음 넘기는 정보가 넓으면 별로 중요하지도 않은 차이까지 전력으로 만들어 옵니다.

사람 신입이라면 “여기 건드려도 되나요?”라고 묻습니다. AI는 묻지 않습니다. 친절한 마음으로 범위를 넓힙니다. “정리해 줘”라고 하면 정말로 구석구석 정리합니다. 마이그레이션 줄 맞춤도, 결제 재시도 “최적화”도, 본인은 좋은 일이라고 믿고 합니다.

그래서 첫날 할 일은 코드를 다 읽는 것도, 그럴듯한 개선 계획을 세우는 것도 아닙니다. 경계를 긋는 것입니다. 어디까지는 알아서 해도 되고, 어디부터는 사람한테 물어봐야 하는가. 이 선을 먼저 그어 두면, Claude에 대한 요청이 “자유롭게 생각해 줘”에서 “이 범위 안에서 증거를 남겨 줘”로 바뀝니다. 선을 긋는 데 필요한 시간은 30분. 코드를 전부 이해할 필요는 없습니다.

30분 만에 만드는, 첫날 한 장 메모

종이든 메모장이든 상관없습니다. 다음 네 항목만 채웁니다. 순서에도 의미가 있습니다.

1. 읽는 순서를 좁게 정한다. 다짜고짜 전체 파일이 아니라, README와 package.json만. 이걸로 어떤 언어인지, 어떻게 실행하는지, 어떤 도구를 쓰는지 알 수 있습니다. 다음에 주요 화면이나 라우트를 2~3개. 그걸로 충분합니다.
2. 손대지 못하게 할 곳을 적는다. 결제, 로그인 인증, 환경 변수, 데이터베이스 마이그레이션. 여기는 “읽어도 좋지만 고쳐 쓰지 마”라고 명시합니다. 안 적으면 Claude는 이곳을 평범한 편집 대상으로 취급합니다.
3. 첫 작은 일을 하나 고른다. 되돌리기 쉬운 곳으로 한정합니다. 글 끝의 문구, 버튼 라벨, 알아보기 어려운 테스트 이름. 실패해도 금방 원래대로 되돌릴 수 있는 것이요.
4. 끝났다고 판단하는 확인 방법을 정한다. 빌드가 통과하는지, 차이가 예상한 범위인지, 화면이 깨지지 않았는지. 분위기가 아니라 명령의 결과로 판단합니다.

이 네 가지를 채우면 첫날의 불안 대부분이 사라집니다. 왜냐하면 “Claude가 무슨 짓을 저지를까”가 아니라 “Claude에게 어디까지 맡겼는가”를 내가 파악하고 있기 때문입니다.

AI에 맡기는 범위와, 사람이 판단하는 범위

선 긋기를 말로 적어 두면 매번 헤매지 않습니다. 제가 쓰는 구분법은 이렇습니다.

할 일	Claude에 맡긴다	사람이 판단한다
코드를 읽고 구조를 정리한다	○ 초안을 만들게 한다	최종 이해는 직접 확인
손대지 못하게 할 곳을 제안한다	○ 후보를 뽑게 한다	결제·인증은 반드시 사람이 확정
문장이나 라벨 수정	○ 맡겨도 된다	차이를 보고 승인
운영 DB에 쓰기	×	사람이 직접 실행
삭제·배포·결제 관련	×	사람이 버튼을 누른다

핵심은 위험한 작업을 처음부터 전부 “사람한테 물어보는” 쪽에 두는 것입니다. 안전하다고 확인된 작업만 나중에 자동으로 승격합니다. 반대로는 하지 않습니다. 처음에 넓게 허용했다가 사고 나고 나서 조이는 건 순서가 거꾸로입니다.

이 사고방식을 더 꼼꼼히 알고 싶다면 Claude Code 첫걸음 가이드와 Claude Code 첫 30분 체크리스트를 함께 읽으면 첫날의 움직임이 자연스럽게 이어집니다.

복사해서 바로 쓰는 요청문 템플릿

먼저, 다짜고짜 편집시키지 않는 게 요령입니다. 처음에는 “읽고, 표로 정리만 해” 정도를 부탁합니다.

이 저장소를 처음 만집니다. 아직 아무것도 편집하지 마세요.
다음 순서로 읽고, 결과를 표로 돌려주세요.

1. README와 package.json을 읽고, 쓰는 언어·실행 명령·주요 의존성을 나열한다
2. 건드리면 위험한 곳(결제·인증·환경 변수·DB 마이그레이션)을 파일 경로와 함께 열거한다
3. 되돌리기 쉬운 "첫 작은 일" 후보를 3개, 이유와 함께 제시한다
4. 각 후보에 대해 완료를 확인하는 명령(빌드·차이 확인 등)을 적는다

다시 한 번 말합니다. 이 단계에서는 한 글자도 편집하지 마세요.

표가 돌아오면, 내 눈으로 “손대지 못하게 할 곳”이 빠지지 않았는지 확인합니다. 빠졌으면 보태고, 그다음에야 비로소 작업 하나만 요청합니다.

방금 후보 중에서 ◯◯(글 끝 문구 수정)만 진행해 주세요.
결제·인증·환경 변수·마이그레이션에는 일절 손대지 말 것.
편집 후 `npm run build`를 실행하고, 차이를 `git diff --stat`로 보여 주세요.
망가졌다면 원인과 고치는 법을 한 줄로 설명한 다음 멈춰 주세요.

CLAUDE.md에 “손대지 못하게 할 곳”을 처음부터 적어 두면, 매번 이 주의 사항을 붙이지 않아도 됩니다. 적는 방법은 CLAUDE.md 모범 사례에 정리해 두었습니다.

확인을 기계에 맡기는 작은 코드

“제대로 준비한 다음 넘긴다”를 사람의 기억에 의존하면, 바쁜 날에는 반드시 빠집니다. 그래서 한 장 메모가 최소한 갖춰졌는지를 기계가 판정하게 합니다. 다음 코드는 Node.js에서 그대로 돌아갑니다.

// 첫날 한 장 메모가 "Claude에 넘길 수 있는 상태"인지 기계로 점검한다
const repoMap = {
  goal: "되돌리기 쉬운 첫 작업 하나를 고른다",
  readFirst: ["README.md", "package.json", "src/routes/"],
  protectedAreas: [".env", "billing/", "migrations/", "wrangler.toml"],
  firstTask: "글 끝 문구를 고친다(결제 코드에는 손대지 않음)",
  proofCommands: ["npm run build", "git diff --stat"],
};

function isReady(map) {
  const reasons = [];
  if (map.readFirst.length < 2) reasons.push("읽는 순서가 너무 좁음/미설정");
  if (map.protectedAreas.length === 0) reasons.push("손대지 못하게 할 곳이 비어 있음");
  if (!map.proofCommands.some((c) => c.includes("build"))) {
    reasons.push("빌드 확인 명령이 없음");
  }
  if (!map.firstTask) reasons.push("첫 작업이 미선정");
  return { ready: reasons.length === 0, reasons };
}

const result = isReady(repoMap);
console.log(result.ready ? "넘겨도 OK" : "아직 넘기지 마: " + result.reasons.join(", "));

실행하면 이렇게 나옵니다.

node check-repo-map.mjs
# => 넘겨도 OK

시험 삼아 protectedAreas를 빈 배열로 바꿔 실행하면 “아직 넘기지 마: 손대지 못하게 할 곳이 비어 있음”이라고 나옵니다. 딱 이 정도지만, “손대지 못하게 할 곳을 적는 걸 깜빡한 채 전자동으로 달리게 한다”는 가장 흔한 사고를 넘기기 전에 멈출 수 있습니다. 이 메모는 CLAUDE.md나 이슈에 그대로 붙여 두면, 내일의 나도 동료도 같은 판단을 재사용할 수 있습니다.

실제로 효과를 본 세 장면

1. 블로그 운영에서, 돈 버는 글의 링크를 지킨다 인기 글 끝의 유입 동선만 고치고 싶을 때, Claude에 “문구를 개선해 줘”라고 부탁하면 그만 상품 링크 URL까지 손댑니다. 그래서 “문구는 고쳐도 되지만, 링크 URL은 한 글자도 바꾸지 마. 변경 후 빌드와 차이를 보여 줘”라고 범위를 닫습니다. 이걸로 매출과 직결되는 링크를 망치지 않고 문장만 다듬을 수 있습니다.

2. SaaS에서, 청구 처리에 다가가지 못하게 한다 설정 화면의 설명문이 알아보기 어려울 때, 개선 대상은 어디까지나 표시 텍스트뿐입니다. 청구나 요금제 변경 로직은 손대지 못하게 합니다. 메모의 “손대지 못하게 할 곳”에 billing/을 넣어 두면, Claude가 친절한 마음에 재시도 처리에 손대는 걸 막을 수 있습니다.

3. 사내 도구에서, 출력 열 이름만 고친다 CSV 출력의 열 이름이 알아보기 어렵다는 의뢰. 고치는 건 열 이름 문자열뿐이고, 집계 로직은 별개입니다. “열 이름 표시 문자열만. 계산식에는 손대지 마. 샘플 데이터로 출력을 보여 줘”라고 부탁하면 확인도 순식간에 끝납니다.

세 장면에 공통된 건 Claude의 능력 부족이 아니라, 경계가 얇으면 사고가 난다는 한 가지입니다. 경계를 또렷하게 적을수록 AI는 안전하고 빠르게 움직입니다.

자주 저지르는 함정과 고치는 법

함정 1: 처음부터 전체 파일을 읽힌다. 중요도 낮은 줄 맞춤에 시간과 토큰을 쓰느라, 정작 중요한 변경이 얇아집니다. 고치는 법은 읽을 대상을 README와 package.json 더하기 주요 라우트 2~3개로 좁히는 것. 전체 파악은 작업 하나 끝낸 다음 조금씩 넓힙니다.

함정 2: 손대지 못하게 할 곳을 안 적는다. Claude는 결제·인증·배포 설정을 평범한 편집 대상으로 취급합니다. 고치는 법은 파일 경로와 함께 보호 목록을 적고, CLAUDE.md에 상주시키는 것. 말로 한 주의는 잊혀도, 적은 건 남습니다.

함정 3: 확인 명령을 정하지 않고 “됐습니다”를 믿는다. 완료 보고가 맞는지 매번 사람이 추측하게 됩니다. 고치는 법은 요청문에 처음부터 “빌드하고 차이를 보여 줘”를 넣는 것. HTTP 200이나 그럴듯한 답은 성공의 증거가 아닙니다. 실제로 돌린 결과만 믿습니다.

자주 묻는 질문

Q. 기존 코드의 전체 그림을 이해한 뒤에 맡기는 게 안전하지 않나요? 이상적으로는 그렇지만, 첫날에 전체 이해는 끝나지 않습니다. 끝나기를 기다리면 아무것도 진행되지 않으니, 먼저 “손대지 못하게 할 곳”을 닫고 되돌리기 쉬운 작업 하나부터 시작합니다. 이해는 작업하면서 넓히는 편이 빠릅니다.

Q. 첫 작업은 얼마나 작게 해야 하나요? 파일 하나, 문구 하나, 명령 하나로 끝나는 크기가 기준입니다. 크게 부탁하면 Claude는 친절하게 범위를 넓힙니다. 빌드와 스크린샷을 확인한 다음 넘어가면, 속도를 떨어뜨리지 않으면서 되돌리는 시간을 줄일 수 있습니다.

Q. 손대지 못하게 할 곳은 어디에 적는 게 좋나요? CLAUDE.md에 적는 게 가장 오래갑니다. 매번 프롬프트에 붙이는 방식은 바쁜 날에 붙이는 걸 깜빡합니다. 프로젝트 규칙으로 한곳에 두면 새 작업에서도 자동으로 적용됩니다.

Q. “건드리지 마”라고 했는데 Claude가 건드려 버렸어요. 대개는 보호 대상이 파일명 수준에 그치고, 디렉터리 전체를 지정하지 못한 경우입니다. billing.js만이 아니라 billing/처럼 범위로 적습니다. 그래도 넘어선다면, 요청문 첫머리에 “편집 전에 대상 파일을 선언한 다음 진행해”라는 단계를 한 번 끼우면 멈추기 쉬워집니다.

Q. 이 메모는 매번 새로 만드나요? 저장소마다 한 번 만들면 그다음부터는 돌려 씁니다. CLAUDE.md와 이슈에 붙여 두면 내일의 나도 동료도 같은 판단을 이어받습니다. 새 보호 대상이 발견되면 덧붙이기만 하면 됩니다.

실제로 시험해 본 결과

서두의 결제 코드 사건 이후, 저는 다른 기존 저장소에서 같은 절차를 시험했습니다. 먼저 편집을 일절 시키지 않고 위 요청문으로 표만 뽑게 했더니, billing/과 migrations/를 보호 대상 후보로 제대로 올려 왔습니다. 다만 환경 변수 파일은 빠져 있어서, 직접 .env를 보탰습니다. 이 지점을 사람이 본다는 전제로 진행하는 게 중요하다고 다시 한 번 느꼈습니다.

첫 작업은 글 끝 문구 수정 하나로 좁히고, npm run build와 git diff --stat까지 확인하고 완료했습니다. 차이는 7줄뿐이었고, 결제 코드에는 한 글자도 손대지 않았습니다. 점검용 코드도 실제로 돌려서, protectedAreas를 비우면 “아직 넘기지 마”라고 멈추는 것을 확인했습니다. 더 똑똑한 AI를 찾기보다, 넘어져도 금방 되돌릴 수 있는 작은 범위를 먼저 정한다. 이게 남의 코드를 맡기는 첫날에 가장 효과적이었습니다.

회사의 기존 코드에 Claude Code를 어떻게 넣을지 팀에서 틀을 정하고 싶은 단계라면, 연수·상담에서 실제 저장소를 보면서 경계 긋는 법을 함께 정리할 수 있습니다. 비기술자 동료에게 먼저 감을 잡게 하고 싶다면 비개발자를 위한 Claude Code도 함께 건네면 좋습니다. 공식 전제 조건은 Anthropic Claude Code getting started도 확인해 두면 안심됩니다.