Claude Code로 기존 저장소 첫 편집을 안전하게 끝내는 도입 절차

막 인수받은 사내 저장소에서, 저는 첫날부터 사고를 쳤습니다.

“일단 전체를 훑어보고, 거슬리는 부분 좀 고쳐놔”라고 Claude Code에 부탁했더니 30분 뒤에 23개 파일이 바뀌어 있었습니다. 고친 내용 자체는 나쁘지 않았어요. 그런데 운영 배포 설정과, 아무도 손대면 안 되는 결제 관련 파일까지 “겸사겸사” 정리되어 있더군요. 변경분이 너무 커서 어디가 진짜 필요한 수정인지 저조차 알 수 없었습니다. 결국 전부 버리고 처음부터 다시 했습니다.

똑똑한 AI가 사고를 내는 건 능력의 문제가 아닙니다. 들어가기 전에 “어디까지 만져도 되는지”를 아무도 정해두지 않았을 뿐입니다. 오늘은 그 첫날을, 되돌릴 수 있고, 확인할 수 있고, 끝까지 마무리되는 형태로 다시 설계해 보겠습니다.

핵심 요약

• 남의 코드에 처음 들어가는 날은, 먼저 “읽어도 되는 곳, 손대면 안 되는 곳, 끝나면 돌릴 검증 명령”을 한 페이지에 정리한다.
• Claude Code에 처음부터 대규모 개편을 맡기지 않는다. 되돌릴 수 있는 작은 편집 1건(테스트 이름 정리, 주석 추가 등)부터 시작한다.
• “완료했습니다”라는 보고 전에, 반드시 검증 명령을 1개 돌리고 그 결과를 남긴다.
• 삭제, 운영 DB, 결제, force push는 첫날에는 전부 “사람이 확인”으로 고정하고, 안전하다고 확인된 것만 나중에 자동화한다.
• 변경분이 부풀기 시작하면, 지시문을 손보기 전에 먼저 “만질 수 있는 파일을 줄인다”.

왜 첫날에 범위를 정하는가

새 저장소는 지도가 없는 낯선 도시입니다. 어느 파일이 심장부이고, 어느 것을 만지면 무너지는지 처음엔 아무도 보이지 않습니다.

여기서 Claude Code에 “전체를 보고 고쳐줘”라고 부탁하면, AI는 친절한 마음으로 넓게 손을 댑니다. AI가 나쁜 게 아닙니다. 범위를 건네지 않은 사람 쪽에 원인이 있습니다. 첫 출근한 아르바이트생에게 “가게, 알아서 좋게 해놔”라고 말해놓고 계산대 설정까지 바뀌면, 그건 지시한 쪽의 문제죠.

그래서 가장 먼저 할 일은 영리한 프롬프트를 쓰는 게 아니라, 지도 한 장을 그리는 것입니다. 읽어도 되는 선반, 열면 안 되는 서랍, 퇴근 전에 확인할 문단속. 이 세 가지를 종이에 적기만 해도 첫날의 사고는 거의 사라집니다.

먼저 정하는 3가지 경계

순서가 중요합니다. 위에서부터 고정해 나갑니다.

정할 것	구체적인 예	왜 먼저 정하는가
읽어도 되는 곳	src/, docs/, 테스트 파일	전부 읽히면 무관한 변경을 제안하기 쉽다
손대면 안 되는 곳	.env, 결제, 인증, DB 마이그레이션, 운영 배포 설정	여기를 망가뜨리면 되돌릴 수 없다
끝나면 돌릴 검증	npm run build, 테스트 1개	”동작한다는 증거”를 매번 남기기 위해

이 세 가지를 적은 종이(텍스트여도 좋습니다)를, 저는 작업 폴더의 ONBOARDING.md에 둡니다. Claude Code에 가장 먼저 읽히는 것도 이 파일입니다. 지도를 공유한 뒤에 거리를 걷게 한다, 라는 순서입니다.

AI에 맡길 범위와 사람이 판단할 범위

여기를 섞으면 사고가 납니다. 선을 분명히 긋겠습니다.

Claude Code에 맡겨도 되는 일

• 저장소 전체를 훑어 구조를 요약한다
• “이 기능은 어느 파일에 있는지”를 찾는다
• 테스트 이름 정리, 주석 추가, 타입 보완 등 되돌릴 수 있는 작은 개선의 초안
• 검증 명령을 실행하고, 실패 로그를 읽어 원인을 짚어본다

사람이 반드시 판단할 일

• 손대면 안 되는 영역에 들어가는 변경을 허용할지 말지
• 파일 삭제, 운영 DB 조작, 결제 처리, force push
• 큰 설계 변경을 머지해도 되는지에 대한 최종 판단
• 변경분이 예상보다 넓어졌을 때 멈출지 말지

제 기준은 단순합니다. “틀려도 git으로 되돌릴 수 있는 것”은 AI에 맡긴다. “되돌릴 수 없는 것”은 사람이 버튼을 누른다. 이 한 줄만 지키면 첫날부터 크게 무너지는 일은 없습니다.

복붙해서 쓰는 프롬프트 템플릿

첫 편집에 들어가기 전에, 저는 이걸 던집니다. 곧바로 쓰게 하지 않고 먼저 계획을 돌려받는 게 요령입니다.

이것은 처음 만지는 기존 저장소입니다. 다음 규칙을 지켜주세요.

[읽어도 됨] src/ 와 docs/ 와 테스트 파일만
[만지지 마] .env / 인증 / 결제 / DB 마이그레이션 / 운영 배포 설정
[이번 목표] 되돌릴 수 있는 작은 개선 딱 1개 (예: 테스트 이름 정리)
[검증] 변경 후 반드시 `npm run build` 를 돌리고 결과를 붙여주세요

아직 코드는 변경하지 마세요.
먼저 "어느 파일을 어떻게 고칠지"의 계획과, 위 규칙을
당신 자신의 말로 다시 풀어 쓴 것을 돌려주세요.

돌아온 계획이 이쪽의 제약을 제대로 다시 풀어 썼다면 합격입니다. 범위를 넓히려 하고 있다면 그 자리에서 멈춥니다. 계획이 좋으면 “그럼 그대로, build까지 실행해줘”로 진행합니다.

경계를 코드로 들고 있기

종이에 적은 규칙은 잊어버립니다. 그래서 저는 도입 계획을 기계가 읽을 수 있는 형태로도 남겨 둡니다. 아래 스크립트는 그대로 동작합니다. 자기 저장소용으로 내용을 바꿔서 쓰세요.

#!/usr/bin/env bash
# 기존 저장소 도입 계획을 하나의 JSON으로 정리한다
set -euo pipefail

cat > onboarding-plan.json <<'JSON'
{
  "goal": "기존 저장소에서 첫 편집 1건을 안전하게 끝낸다",
  "readOnlyCommands": [
    "git status --short",
    "git ls-files | head -50",
    "grep -rn \"TODO\\|FIXME\" src | head -20"
  ],
  "protectedAreas": [".env", "billing", "auth", "db/migrations", "deploy/prod"],
  "firstTask": "되돌릴 수 있는 문서 또는 테스트의 작은 개선 1개",
  "proofCommand": "npm run build",
  "rollback": "git diff -- path/to/changed-file && git checkout -- path/to/changed-file"
}
JSON

echo "=== 도입 계획 ==="
cat onboarding-plan.json

echo ""
echo "=== 현재 변경분 (비어 있으면 미편집) ==="
git status --short

이 스크립트는 화려하지 않습니다. 가치는 작업에 들어가기 전에 “금지 영역”과 “증거 명령”을 파일에 고정할 수 있다는 데 있습니다. protectedAreas를 자기 저장소의 위험한 곳으로 바꿔 쓰기만 하면 첫날의 지도가 완성됩니다.

검증 명령도 1개 준비해 두면 든든합니다. Node.js 프로젝트라면 이런 최소 체크로 “망가지지 않았는지”를 기계적으로 확인할 수 있습니다.

// check.mjs : 빌드가 통과하는지만 확인하는 최소 스크립트
import { execSync } from "node:child_process";

try {
  // 자기 프로젝트의 검증 명령으로 바꿔주세요
  execSync("npm run build", { stdio: "inherit" });
  console.log("검증 OK: 빌드가 통과했습니다. 변경분을 리뷰하세요.");
} catch (e) {
  console.error("검증 NG: 빌드가 깨졌습니다. 머지하지 말고 원인을 확인합니다.");
  process.exit(1);
}

node check.mjs가 초록이면 변경분을 리뷰로 넘기고, 빨강이면 멈춘다. 이 한 줄짜리 장치가 있는 것만으로 “동작하고 있을 거야”라는 막연한 믿음으로 머지하는 사고가 사라집니다.

현장 3곳에서의 사용법

비슷한 상황이 있다면, 절차를 새로 만들지 말고 이름만 자기 현장으로 바꿔 쓰세요.

1. 콘텐츠 사이트 인수인계 기사 데이터 위치, 이미지 폴더, 빌드 명령, 상품 페이지를 먼저 읽혀 파악시킨다. 첫 편집은 “깨진 링크 수정 1건”만. 빌드가 통과하면 리뷰에 올린다. 본문 대량 수정은 안전하다고 확인된 뒤에.

2. SaaS 코드베이스 인증, 결제, DB 마이그레이션을 금지 영역에 명시한다. 첫 작업은 “테스트 설명문을 알기 쉽게 다듬기” 정도로 좁히고, 사람이 승인한 뒤에 진행한다. 여기를 느슨하게 하면 결제 로직에 “친절한 개선”이 들어가 간담이 서늘해집니다.

3. 오래된 레거시 저장소 “전체를 현대화해줘”는 금기어입니다. 변경분이 읽을 수 없는 크기가 됩니다. 대신 함수 이름의 오타 수정이나 테스트 이름 정리처럼, 빌드로 검증 가능한 작은 한 걸음부터. 한 번 성공하면 같은 방식으로 다음 한 걸음을 내딛습니다.

어느 예에도 “멈출 지점”이 있습니다. 멈출 지점이 있기에 작업이 무한히 넓어지지 않습니다.

실패 사례와 그 고치는 법

솔직하게 적겠습니다. 처음 몇 번은 전부 사고를 쳤습니다.

금지 영역을 적지 않고 부탁했다 → 리뷰할 수 없는 크기의 변경분이 되어 전부 버려야 했습니다. 고치는 법은 단순합니다. 지시문을 다듬기 전에 먼저 “읽어도 되는 파일을 줄인다”. 범위가 좁을수록 AI가 폭주할 수 있는 폭도 좁아집니다.

변경이 전부 끝난 뒤에 빌드했다 → 어느 편집에서 깨졌는지 알 수 없게 됐습니다. 지금은 파일 1개를 고칠 때마다 검증을 돌립니다. 깨진 순간이 기록에 남으니 원인이 바로 보입니다.

확인을 내 눈에만 의존했다 → 바쁜 날엔 반드시 놓칩니다. 말 그대로 “기계로 알 수 있는 것”은 기계에 맡긴다. 빌드 성공 여부, 테스트 결과, 링크 깨짐. 사람의 눈은 기계가 잡지 못하는 설계 판단에만 씁니다. 이걸로 한밤중 리뷰가 확 줄었습니다.

함정을 기사에 남기는 이유는, 성공 사례만 봐서는 독자가 자기가 위험한 상태인 걸 알아차리지 못하기 때문입니다. 어느 지시가 너무 넓어졌는지, 어느 검증이 빠졌는지를 짧게 남겨 두면, 다음의 나는 같은 구덩이를 밟지 않습니다.

자주 묻는 질문

Q. 첫 편집 1건은 무엇을 고르면 좋나요? A. “틀려도 git checkout으로 되돌릴 수 있는 것”을 고르세요. 테스트 이름 정리, 주석 추가, 오타 수정 정도가 안전합니다. 새 기능이나 설정 변경은 첫날에는 맞지 않습니다.

Q. 금지 영역은 어디까지 자세히 적어야 하나요? A. “망가지면 되돌릴 수 없는 곳”만으로 충분합니다. .env, 인증, 결제, 운영 배포 설정, DB 마이그레이션. 처음엔 이 5가지만 잡으면 치명적인 사고는 거의 막을 수 있습니다.

Q. Claude Code에 계획을 돌려받는 수고를 줄일 수 없나요? A. 줄이지 않기를 권합니다. 계획을 다시 풀어 쓰게 하는 그 한 수고로 범위의 어긋남을 편집 전에 발견할 수 있습니다. 코드가 쓰인 뒤에 깨닫는 것보다 훨씬 싼 비용입니다.

Q. 검증 명령은 빌드만으로 충분한가요? A. 첫날은 빌드 1개로 충분합니다. 익숙해지면 관련된 테스트 1개를 더한다. 처음부터 전체 테스트를 돌리려 하면 무거워서 이어지지 않습니다. 작게 시작하고 성공 로그가 쌓인 뒤에 늘립니다.

Q. 팀에 도입할 때 주의할 점은? A. ONBOARDING.md 같은 공유 파일에 경계를 적고, 모두가 같은 지도를 쓰는 것입니다. 사람마다 금지 영역이 제각각이면 리뷰 기준도 흔들립니다.

관련 글

생각의 토대는 엔지니어가 아닌 사람이 Claude Code를 쓰는 법과 Claude Code 첫걸음 가이드가 참고가 됩니다. 프로젝트 규칙을 기억시키는 작법은 CLAUDE.md 베스트 프랙티스에, 더 깊이 들어간 지시 방법은 프롬프트 설계 실전에 정리했습니다. 권한 관련 세부는 Anthropic 공식 문서도 함께 확인하세요.

실제로 시험해 본 결과

서두의 “23개 파일 사고” 이후, 저는 도입 순서를 바꿨습니다. 영리한 프롬프트를 찾는 걸 그만두고, 먼저 onboarding-plan.json으로 금지 영역과 검증 명령을 고정한다. 이것만으로 결제나 운영 설정에 손이 닿는 사고는 0이 됐습니다.

첫 편집 1건을 “테스트 이름 정리”로 좁힌 날은 변경분이 8줄로 끝났고, 빌드도 단번에 통과했습니다. 리뷰에 2분도 걸리지 않습니다. 반대로 범위를 정하지 않고 부탁한 다른 날은 또 변경분이 부풀어 전부 버렸습니다. 차이는 모델의 영리함이 아니라, 들어가기 전에 지도를 그렸는지 여부였습니다.

남의 코드를 안전하게 만지는 방식을 자기 팀의 실제 사례로 다지고 싶은 분은, 업무에 맞춘 도입 진행법을 연수·상담에서 함께 설계하고 있습니다. 우선 오늘, 자기 저장소의 금지 영역을 5개 적어 보는 것부터 시작해 보세요.