Claude Code 팁

레거시·남이 짠 코드 빠르게 파악하기: Claude Code로 처음 보는 코드베이스 탐색하는 법

인수인계받은 프로젝트와 오픈소스를 빠르게 이해하는 Claude Code 질문 순서와 핵심 흐름 추적 프롬프트를 정리했습니다.

4분 읽기조코헌트 운영팀
목차

1. 첫 10분은 설명이 아니라 지도를 만든다

처음 보는 코드베이스에서 곧바로 특정 파일을 고치면 중요한 전제를 놓치기 쉽습니다. 먼저 Claude Code에게 전체 지도를 그리게 하세요. 조코헌트에는 지금까지 414개 프로덕트와 302명의 메이커가 참여했습니다. 프로젝트마다 구조와 기술 선택이 다른 환경에서는 ‘내가 익숙한 방식’으로 추측하기보다, 현재 코드가 실제로 어떻게 연결되는지 확인하는 편이 안전합니다.

먼저 확인할 범위

다음 질문을 한 번에 던지기보다, 읽기 전용 탐색을 요청하고 답변에 근거 파일과 줄 번호를 포함하게 하세요.

이 저장소를 처음 인수인계받은 개발자에게 설명한다고 생각하고 탐색해줘. 1) 실행 진입점 2) 주요 디렉터리의 책임 3) 데이터가 저장되고 조회되는 위치 4) 외부 서비스 연동 5) 테스트와 배포 관련 파일을 찾아라. 추측하지 말고 각 설명마다 근거 파일 경로를 붙여라.

이 단계의 목적은 모든 파일을 읽는 것이 아니라, 다음 질문을 어디에 해야 할지 아는 것입니다.

답변 형식도 고정하기

“전체 구조를 설명해줘”보다 결과 형식을 지정하면 훨씬 유용합니다. 예를 들어 “디렉터리 | 역할 | 핵심 파일 | 확인이 필요한 점” 표로 정리해달라고 요청하세요. 모호한 부분은 확인 필요로 표시하게 하면 AI가 빈칸을 그럴듯하게 채우는 위험도 줄어듭니다.

2. 기능이 아니라 사용자 흐름을 따라간다

파일 목록을 이해했다고 실제 동작을 이해한 것은 아닙니다. 로그인, 결제, 글 작성처럼 사용자가 시작하고 끝나는 흐름 하나를 골라 입구부터 출구까지 추적하세요.

진입점에서 저장까지

다음처럼 범위를 좁혀 질문합니다.

사용자가 회원가입을 완료하는 흐름을 추적해줘. 화면 또는 API 진입점부터 시작해서 검증, 인증 상태 생성, 데이터베이스 쓰기, 응답 반환까지 순서대로 정리해라. 각 단계의 파일과 함수명을 적고, 분기 조건과 실패 응답도 함께 표시해라. 코드를 수정하지 마라.

여기서 중요한 것은 함수 설명이 아니라 호출 순서입니다. 화면에서 호출하는 API, API가 부르는 서비스, 서비스가 사용하는 저장소를 하나의 선으로 연결해야 합니다. 이 방식은 새 기능을 추가할 때 어디를 건드려야 하는지 알려줍니다.

정상 흐름과 예외 흐름을 분리한다

같은 기능도 성공 경로만 보면 운영 중 장애를 놓치기 쉽습니다. “인증 토큰이 없을 때”, “중복 데이터일 때”, “외부 API가 실패할 때”를 각각 물어보세요. 답변에 실제 코드가 없으면 “해당 처리가 없다는 근거를 찾아라”라고 다시 요청하면 됩니다.

3. 의존성은 목록보다 변경 영향으로 본다

package.json이나 설정 파일을 읽는 것만으로는 어떤 라이브러리가 중요한지 알기 어렵습니다. 자주 수정될 파일을 기준으로 역방향 의존성을 확인하세요.

User 데이터 구조를 바꾸면 영향받는 파일을 찾아라. 타입 정의, 데이터베이스 스키마, API, 화면, 테스트, 마이그레이션을 분류하고, 직접 참조와 간접 영향을 구분해 표로 정리해라. 확인하지 못한 영역은 추측하지 말고 누락으로 표시해라.

이 질문은 리팩터링 전 영향 범위를 정리할 때 특히 유용합니다. “이 파일을 설명해줘”가 아니라 “이 변경이 어디까지 퍼지는가”를 묻는 것이 핵심입니다. 실제 수정 전에는 관련 테스트와 마이그레이션 파일을 직접 열어 답변을 대조하세요. 코드 리뷰 루틴은 Claude Code에 코드 리뷰 시키기에서 다룬 방식과 이어집니다.

4. 탐색 세션을 검증 루프로 끝낸다

AI의 설명은 출발점이지 사실 확인을 대신하지 않습니다. 탐색이 끝나면 중요한 주장 세 개를 뽑아 실제 코드와 대조하세요.

주장-근거 표 만들기

지금까지 파악한 구조에서 중요한 주장 5개를 뽑아라. 각 주장마다 근거 파일, 근거 함수 또는 설정, 아직 확인하지 못한 가정을 적어라. 근거가 약한 항목은 ‘검증 필요’로 표시해라.

그 다음 검증 필요 항목만 직접 열어봅니다. 실행 가능한 테스트가 있다면 핵심 흐름 하나를 실행하고, 없다면 로그·타입·호출부를 확인하세요. 이 과정을 거치면 “AI가 그렇게 말했다”가 아니라 “코드에서 확인했다”는 상태가 됩니다. 불확실한 답변을 줄이는 질문 방식은 LLM 환각 줄이는 실전 기법도 참고할 만합니다.

탐색 기록을 남긴다

마지막에는 ARCHITECTURE_NOTES.md 같은 임시 문서에 진입점, 핵심 흐름, 위험 요소, 미확인 항목을 짧게 기록하세요. 단, 문서가 실제 코드보다 오래된 설명이 되지 않도록 “작성일”과 “검증한 커밋”을 함께 적는 편이 좋습니다.

5. 바로 쓸 수 있는 탐색 순서

처음 보는 저장소라면 다음 순서로 진행해보세요.

  • 저장소의 실행·배포·테스트 진입점 확인
  • 주요 디렉터리와 데이터 흐름을 지도화
  • 가장 중요한 사용자 흐름 하나를 입구부터 추적
  • 핵심 데이터 구조의 변경 영향 확인
  • 정상·실패 경로를 나눠 검증
  • 주장별 근거 파일과 미확인 가정 기록
  • 작은 읽기 전용 검증 후에야 수정 작업 시작

탐색 중 컨텍스트가 길어지면 세션을 무작정 이어가기보다, 확인된 사실과 남은 질문을 요약해 새 세션에 넘기세요. 컨텍스트를 나누고 비용을 관리하는 기준은 Claude Code 토큰·비용 아끼는 법과 함께 보면 좋습니다. 좋은 탐색의 목표는 코드베이스를 전부 외우는 것이 아니라, 다음 변경을 안전하게 시작할 수 있을 만큼 구조와 불확실성을 분리하는 데 있습니다.

이 글 공유하기

같은 주제를 다룬 다른 글도 살펴보세요.