Claude Code 첫 저장소 감사 체크리스트: 첫 편집 전 코드베이스 지도 만들기

기존 저장소에서 첫 Claude Code 세션은 편집으로 시작하면 안 됩니다. 먼저 지도를 만들어야 합니다. Claude Code는 빠르게 읽지만, 진입점, 보호 영역, 검증 명령, 비즈니스 경로를 알아야 그 속도가 안전해집니다.

이 글의 의도는 명확합니다. 초보자가 실제 코드베이스에서 Claude Code를 쓰되 통제력을 잃지 않는 것입니다. 아직 기능을 만드는 단계가 아니라 20분 안에 scope, risk, verification, revenue CTA를 보이게 만드는 단계입니다.

함께 읽을 글: claude-code-getting-started-complete, claude-code-existing-codebase-map, claude-code-harness-lite-workflow.

첫 편집 전에 이 틀이 필요한 이유

Claude Code는 작업 경계가 선명할 때 가장 강합니다. 좋은 경계는 읽어도 되는 파일, 편집해도 되는 파일, 실행하면 안 되는 작업, 그리고 작업을 끝내는 증거를 이름으로 남깁니다. 이 경계가 없으면 초보자의 작은 요청도 넓은 재작성으로 커지고, 콘텐츠 변경이 무료 PDF, Gumroad, 상담 경로를 조용히 망가뜨릴 수 있습니다.

이 패턴은 수익 작업에도 도움이 됩니다. 기술적 proof와 독자 proof를 같은 점검 안에 넣기 때문입니다. 로컬 build가 되더라도 독자를 잘못된 상품으로 보내면 아직 끝난 것이 아닙니다. scope, command, public URL, CTA를 기록하면 내일은 기억이 아니라 기록에서 개선할 수 있습니다.

실무에서 쓰는 흐름

1. README, package.json, 라우팅 진입점만 먼저 읽기
2. generated, billing, auth, migrations, .env를 보호 영역으로 표시하기
3. 첫 편집 가능 파일을 세 개 이하로 제한하기
4. 패치 전에 proof command 하나를 정하기
5. 콘텐츠나 랜딩 페이지라면 무료 PDF, Gumroad, 상담 링크도 감사하기

상황	안전한 진행	검증
Astro 콘텐츠 사이트	글을 만들기 전에 content collection, slug 규칙, heroImage, CTA 패턴을 봅니다. 본문과 유료 경로가 모두 감사 대상입니다.	build, diff, URL
React 운영 대시보드	작은 레이아웃 문제는 컴포넌트, CSS, 스크린샷 검증에만 묶습니다. auth와 billing은 보호합니다.	screenshot, test
API 저장소	라우트 경로와 테스트 명령을 먼저 읽고, migration과 secrets는 첫 작업에서 제외합니다.	log, command, handoff

첫 점검은 짧게 유지합니다. 감사가 만들어야 하는 것은 거대한 보고서가 아니라 결정입니다. 20분 뒤에도 결정이 흐리다면 편집을 시작하지 말고 추가로 읽을 파일 하나를 정합니다.

복사해서 쓰는 프롬프트와 코드

첫 편집 전에 이 저장소를 감사하세요. 아직 수정하지 마세요. 진입 파일, 보호 영역, 안전하게 편집할 파일, 최소 검증 명령, 공개 URL과 CTA 확인 항목을 반환하세요.

const audit = {
  repo: "customer-portal",
  intent: "first safe Claude Code session",
  scope: ["README.md", "package.json", "src/routes"],
  protected: [".env", "billing/", "migrations/"],
  proof: ["npm.cmd run build", "git diff --stat"],
};

export function readyForFirstEdit(report) {
  return report.scope.length > 0 &&
    report.protected.length > 0 &&
    report.proof.some((command) => command.includes("build"));
}

console.log(readyForFirstEdit(audit));

이 코드는 일부러 작게 만들었습니다. 운영 아이디어를 scope가 있는지, 보호 영역이 있는지, proof command가 있는지 확인 가능한 객체로 바꾸기 위한 것입니다. 글 발행, 앱 개발, 디버깅, 팀 인수인계에 맞게 바꿀 수 있습니다.

실제 예시 세 가지

Astro 콘텐츠 사이트

글을 만들기 전에 content collection, slug 규칙, heroImage, CTA 패턴을 봅니다. 본문과 유료 경로가 모두 감사 대상입니다.

핵심은 proof입니다. 하나의 명령, 하나의 보이는 페이지, 또는 독자에게 도달했음을 보여주는 메모를 남깁니다.

React 운영 대시보드

작은 레이아웃 문제는 컴포넌트, CSS, 스크린샷 검증에만 묶습니다. auth와 billing은 보호합니다.

핵심은 proof입니다. 하나의 명령, 하나의 보이는 페이지, 또는 독자에게 도달했음을 보여주는 메모를 남깁니다.

API 저장소

라우트 경로와 테스트 명령을 먼저 읽고, migration과 secrets는 첫 작업에서 제외합니다.

핵심은 proof입니다. 하나의 명령, 하나의 보이는 페이지, 또는 독자에게 도달했음을 보여주는 메모를 남깁니다.

피해야 할 실패 사례

• 처음부터 전부 고치라고 하면 감사와 구현이 섞입니다.
• 로컬 build가 성공해도 공개 URL이나 CTA가 틀리면 완료가 아닙니다.
• 보호 영역을 쓰지 않으면 유용한 수정이 장애로 바뀔 수 있습니다.

또 다른 실패는 로컬라이즈 drift입니다. 영어 글은 올바른 상품 경로를 설명하지만 다른 언어에는 오래된 CTA가 남을 수 있습니다. 그래서 공개 확인은 frontmatter lang만 보지 않고 각 언어의 h1, 본문 시작, CTA 문구를 봐야 합니다.

무료 PDF, Gumroad, 상담으로 이어지는 방법

명령어 감각이 아직 부족한 독자라면 무료 치트시트가 먼저입니다. 설치, 권한, CLAUDE.md, hooks, MCP, CI/CD가 막힌다면 Setup Guide가 맞습니다. 리뷰, 디버깅, 리팩터링 프롬프트를 반복해서 쓰는 독자에게는 50 Prompt Templates를 연결합니다. 팀 도입이나 수익 경로 설계가 필요하면 consultation으로 보내세요. 전체 상품 비교는 products에서 할 수 있습니다.

모든 독자를 바로 유료 상품으로 보내지 마세요. 초보자는 먼저 마찰이 낮은 PDF가 필요합니다. 같은 프롬프트를 반복하는 중급자는 템플릿에 가깝고, permissions, CLAUDE.md, hooks, MCP, CI/CD에서 막힌 독자는 Setup Guide에 가깝습니다. 팀과 운영 설계 문제는 consultation에 가깝습니다.

게시 전후에 확인할 것

검증은 HTTP 200으로 끝나지 않습니다. h1, 본문 첫 부분, heroImage, 내부 링크, Gumroad 링크, 상담 경로가 같은 독자 의도에 맞는지 확인해야 합니다.

다국어 발행에서는 일본어, 영어, 중국어, 한국어, 스페인어, 프랑스어, 독일어, 포르투갈어, 힌디어, 인도네시아어를 따로 확인합니다. slug가 같아도 본문이 오래되었을 수 있습니다. 모바일 폭 스크린샷은 첫 문단과 CTA를 함께 보여 주기 때문에 더 빨리 잡아냅니다.

다음에 볼 숫자

다음에 볼 숫자는 이 slug의 PDF 시작, Gumroad 클릭, products 방문, training 방문, 검색 유입, 국가 비율, 기사에서 CTA로 가는 클릭률입니다. PV가 늘었는데 Gumroad 클릭이 그대로라면 상품 매칭을 강화해야 합니다. 기술 글에서 상담 방문이 늘면 독자는 일반 튜토리얼이 아니라 workflow design을 원할 가능성이 큽니다.