Claude Code Repo Map 첫 패스: 기존 코드베이스를 안전하게 읽는 방법

낯선 저장소에서 바로 구현을 요청하면 Claude Code는 너무 넓게 읽거나 중요한 경계를 놓칠 수 있습니다. 첫 결과물은 기능이 아니라 진입점, 명령, 위험 영역, 작은 검증 작업을 담은 repo map이어야 합니다.

왜 이 패턴이 필요한가

repo map은 컨텍스트 절약용 메모가 아닙니다. 리뷰어와 다음 담당자가 같은 전제로 대화하게 만드는 운영 문서입니다. 설치를 마친 초보자는 다음에 무엇을 맡길지에서 막히므로, 이 지점이 무료 PDF, Setup Guide, 상담으로 이어지는 자연스러운 전환점이 됩니다.

함께 읽기: 함께 읽기 1, 함께 읽기 2, 함께 읽기 3.

실무 흐름

첫 프롬프트에서는 편집을 금지합니다. README, package 정보, 라우트, 테스트, 배포 설정만 읽게 하고, 실행 전 안전한 명령과 위험한 영역을 분리합니다. 그 다음 파일 수가 적고 빠른 검증이 있으며 인증이나 결제를 건드리지 않는 작업을 고릅니다.

복사해서 쓰는 최소 세트

Read this repository for orientation only.
Do not edit files yet.
Return:
1. the main app entry points
2. the commands that appear safe to run
3. the files that define content, routes, and tests
4. three small first tasks ranked by verification cost
5. one risk that should block a larger change

repo_map:
  entry_points:
    - package.json
    - src/main.ts
  safe_commands:
    - npm run build
    - npm test
  first_task_rule:
    max_files: 3
    proof_required: true
    avoid_auth_and_billing: true

export function rankFirstTask(task) {
  const risk = task.touchesAuth || task.touchesBilling ? 10 : 0;
  const scope = task.filesChanged * 2;
  const proof = task.hasFastProof ? -3 : 4;
  return risk + scope + proof;
}

실제 예시

Astro 콘텐츠 사이트라면 src/content, src/pages, BlogPostLayout, build 명령을 먼저 지도화합니다.
SaaS라면 auth, billing, migration을 위험 영역으로 표시하고 README 수정이나 테스트 추가부터 시작합니다.
팀 도입에서는 repo map 요약을 CLAUDE.md에 남겨 다음 사람이 같은 전제에서 시작하게 합니다.

운영 체크리스트

이 패턴은 한 번 읽고 끝내는 글이 아니라 Claude Code 작업 때마다 짧게 반복할 운영 장치입니다. 글, 상품 페이지, 상담 경로를 고치는 날에는 아래 항목을 작은 통제표처럼 사용하세요.

작업 전 목표를 한 문장으로 쓰고 범위 밖 파일이나 기능을 적습니다.
Claude Code가 읽어야 할 파일과 피해야 할 파일을 분리합니다.
구현 뒤 최소 하나의 증거 명령을 남깁니다. 콘텐츠는 build뿐 아니라 공개 URL을 봅니다.
무료 PDF, Gumroad, 상담 링크가 본문과 글 하단 CTA에서 일치하는지 확인합니다.
다국어 글은 title, h1, 본문 시작, CTA가 같은 언어인지 확인합니다.
무관한 dirty file을 stage하지 않습니다. 필요하면 commit 전에 diff를 다시 나눕니다.
다음 세션이 바로 이어갈 수 있도록 남은 위험과 볼 지표를 짧게 기록합니다.

어떤 상품이나 상담으로 연결할 것인가

독자가 아직 명령에 익숙하지 않다면 첫 출구는 무료 치트시트입니다. 같은 workflow가 매주 반복된다면 Prompt Templates로 리뷰, 디버깅, 글 수정 지시를 표준화합니다. 막히는 지점이 permissions, CLAUDE.md, hooks, MCP, CI/CD라면 Setup Guide가 맞습니다. 팀 책임, 공개 검증, 수익 경로를 함께 설계해야 한다면 상담으로 연결합니다.

handoff에 남길 것

Claude Code 작업은 patch가 그럴듯해 보인다고 끝나지 않습니다. 다음 사람이 세션을 다시 보지 않고도 판단을 이해할 수 있어야 운영 자산이 됩니다. handoff에는 변경 범위, 그 범위를 택한 이유, 실행한 증거 명령, 공개 URL, CTA 목적지, 남은 위험을 적습니다. 콘텐츠 작업이라면 heroImage, 내부 링크, 외부 링크, 언어 확인, 무료 PDF, Gumroad, 상담 경로가 본문에 남아 있는지도 적습니다. 제품 근처 페이지라면 어떤 독자가 무료 자료로 충분한지, 어떤 독자가 교재를 살지, 어떤 독자가 상담이 필요한지도 구분합니다.

다음에 볼 숫자

PV만으로 성공을 판단하지 않습니다. 공개 후에는 색인 상태, 국가별 유입, 글 하단 CTA 근처 클릭, Gumroad 클릭, 상담 폼 방문을 봅니다. 기존 인기 글을 고쳤다면 수정 전후의 이탈률과 다음 페이지 이동을 비교합니다. 다음 Claude Code 세션에 이 숫자를 먼저 주면 단순 글 생성이 아니라 수익 경로 개선으로 판단할 수 있습니다.

실패 사례

처음부터 기능 구현을 요청하면 경계가 흐린 상태로 여러 모듈에 수정이 번집니다.
안전한 명령을 정하지 않으면 build, test, DB 확인, deploy 중 무엇이 증거인지 흐려집니다.
지도를 남기지 않으면 다음 세션이 같은 탐색을 반복하며 시간과 토큰을 씁니다.

무료 PDF, Gumroad, 상담 경로

먼저 무료 PDF로 명령 습관을 잡고, 반복되는 작업은 Gumroad 교재로 표준화합니다. 팀 도입, 권한 설계, 수익 경로가 함께 걸리면 상담으로 넘어가는 편이 안전합니다.

검증 메모

본문은 기존 codebase map, context management, first task runbook과 연결되어 있으며 무료 PDF, Gumroad 교재, 상담 CTA를 함께 제공합니다.