Claude Code로 기존 코드베이스 지도 만들기: 45분 안에 읽고 고치고 검증하기

왜 이 흐름이 필요한가

Claude Code는 빈 프로젝트보다 기존 코드베이스에서 더 큰 가치를 냅니다. 하지만 첫 세션이 가장 위험합니다. 처음부터 전체 리팩터링을 맡기면 리뷰하기 어려운 diff가 생깁니다. 먼저 필요한 것은 완벽한 이해가 아니라, 앱의 시작점, 건드려도 되는 파일, 위험한 영역, 오늘 검증할 수 있는 작은 수정의 지도입니다.

함께 보면 좋은 글은 Claude Code 시작 가이드, harness engineering, 권한 가이드.

실무에서 쓰는 절차

45분 루프는 상태 확인, 파일 지도 작성, 경계가 좁은 수정 선택, 하나의 검증 명령 실행, handoff 메모 작성입니다. 콘텐츠 사이트라면 무료 PDF, Gumroad 상품, 상담 CTA까지 지도에 포함해야 합니다.

복사해서 쓸 수 있는 최소 세트

git status --short
rg --files | Select-Object -First 80
rg "TODO|FIXME|console\.log|throw new Error" -n site src scripts
cd site
npm.cmd run build

# CLAUDE.md

## Existing-codebase map
- entry points: site/src/pages, site/src/layouts, site/src/lib
- safe first task: update one CTA or one article
- risky areas: auth, billing, deploy scripts, secrets

## Definition of done
- small diff
- one proof command
- public URL or local preview checked
- next step written down

Read this repository as an existing codebase.
Return:
1. the three most important entry points
2. the safest first patch under 45 minutes
3. files that should not be touched today
4. the proof command
5. the handoff note format

세 가지 실제 사용 사례

• 한 글의 하단 CTA만 개선하고 무료 PDF 경로가 살아 있는지 확인합니다.
• CLAUDE.md에 안전한 명령, 금지 영역, 완료 조건을 추가합니다.
• 인기 글에서 상품 페이지로 내부 링크 하나를 추가하고 공개 URL에서 h1과 CTA를 확인합니다.

실패 사례와 피하는 방법

대표적인 실패는 ‘프로젝트 전체를 리팩터링해줘’로 시작하는 것입니다. Claude Code는 그럴듯한 변경을 만들 수 있지만 범위가 커지면 신뢰하기 어렵습니다. 하나의 파일, 하나의 경로, 하나의 증거 명령으로 시작하세요.

무료 PDF, Gumroad, 도입 상담 경로

처음에는 무료 치트시트로 명령을 확인하세요. CLAUDE.md, hooks, permissions, 팀 guardrail이 필요하면 Setup Guide가 빠릅니다. 도입 순서나 수익 경로를 같이 설계해야 하면 상담이 맞습니다.

• 무료 Claude Code 치트시트
• Claude Code Prompt Templates
• Claude Code Setup Guide
• 상품 목록
• 도입 상담

먼저 무료 치트시트로 기본 명령을 확인하고, 반복 업무가 생기면 Gumroad 교재를 사용하세요. 팀 도입이나 매출 경로 설계가 필요하면 상담으로 넘어가면 됩니다.

이 글에서 확인한 것

이 글은 PowerShell 명령, CLAUDE.md 조각, CTA 검증 항목을 분리했습니다. 실제 저장소에 바로 붙여 넣고 작은 검증까지 이어지도록 구성했습니다.