모르는 리포지토리(Repository)에 던져진 첫날. README를 읽어도 어느 파일부터 손을 대야 할지 모르겠다——이러한 "시작 단계의 망설임"을 Claude Code에게 길 안내를 맡겨 단축합니다.

이 기사에서는 처음 보는 코드를 넓게→좁게 순서로 파악하는 절차를 실제 프롬프트, @ 참조, 확인 흐름과 함께 구성합니다. 포인트는 "전부 읽게 하는 것"이 아니라, 읽는 범위를 제어하고, 직접 수정하게 하지 않으며, 이해만 얻어오는 것입니다. 마지막으로 얻은 이해를 CLAUDE.md에 고정하여 다음 세션으로 넘기는 과정까지 다룹니다.

결론: 읽는 방법에는 순서가 있다 (넓게→좁게→흐름)

처음 보는 코드를 갑자기 "이 버그 고쳐줘"부터 시작하면, AI도 사람도 길을 잃습니다. 읽는 순서를 고정합니다.

1. 넓게 … 리포지토리 전체의 지도 (구성·아키텍처·주요 모델)
2. 좁게 … 담당 기능과 관련된 파일군으로 좁히기
3. 흐름 … 하나의 처리를 입구부터 출구까지 트레이스(Trace)

각 단계에서 "무엇을 물을지" 정해져 있다면, 처음 보더라도 30분 만에 감을 잡을 수 있습니다. 차례대로 살펴보겠습니다.

0. 시작하기 전에: clone 하여 실행하기만 하면 됨

소재는 수중에 있는 임의의 리포지토리여도 상관없습니다. 루트(Root)에서 claude를 실행합니다.

$ git clone https://github.com/your-org/your-app.git
$ cd your-app
$ claude

이 시점에서는 아직 아무것도 묻지 않습니다. 먼저 "읽기만 하는 것"을 보장하는 설정(후술할 plan 모드)으로 전환한 뒤 시작합니다.

1. 넓게: 리포지토리의 지도를 그리게 하기

처음에는 입도가 큰 질문부터 시작합니다. 좁은 질문을 갑자기 던지지 말고, 전체상 → 개별로 내려가는 것이 요령입니다.

give me an overview of this codebase

돌아오는 개관은 다음과 같은 입도입니다 (상정 예시).

이 리포지토리는 Flask로 제작된 REST API입니다.
- 엔트리 포인트(Entry point): app/main.py
- 라우팅(Routing): app/api/ 하위 (users, orders)
...

지도가 나왔다면, 관심 있는 축을 하나씩 파고듭니다. 넓은 질문을 기점으로 아키텍처·데이터 모델·횡단 기능으로 내려갑니다.

explain the main architecture patterns used here
what are the key data models?
how is authentication handled?

2. 좁게: 담당 기능이 보이면 AI에게 찾게 하는 것이 아니라, 직접 범위를 지정합니다.

@ 참조로 읽을 범위를 고정합니다. @를 사용하면 파일이나 디렉토리를 직접 컨텍스트(Context)에 올릴 수 있습니다.

@app/api/orders.py 의 처리 흐름을 설명해줘
@app/models 의 데이터 구조를 요약해줘

@app/api/orders.py … 해당 파일의 전문을 컨텍스트에 포함합니다.

@app/models … 디렉토리의 파일 목록(내용이 아닌 구성)을 전달합니다.

"관련 파일을 찾는" 단계에서도 도메인 용어로 구체적으로 부탁하면 정확도가 올라갑니다.

find the files that handle order checkout
how do these checkout files work together?

3. 흐름: 하나의 처리를 입구부터 출구까지 트레이스하기

기능의 지도가 완성되었다면, 하나의 처리를 끝에서 끝까지 쫓아가게 합니다. "프론트엔드 입구 → DB까지"와 같이 경로를 명시하는 것이 요령입니다.

trace the checkout process from the API endpoint to the database

답변은 경로의 연쇄로 나옵니다 (상정 예시).

1. POST /orders/checkout → app/api/orders.py: checkout()
2. checkout() 이 OrderService.place_order() 를 호출 → app/services/order.py
3. place_order() 가 재고를 확인 → app/services/inventory.py: reserve()
...

경로가 나오면 각 스텝을 @

열어서 직접 눈으로 확인합니다. AI의 트레이스 (Trace)는 '읽는 순서의 지도'일 뿐, 정확성을 보장하는 것은 아닙니다. 지도를 따라 실제 파일을 열면 확인 작업을 빠르게 끝낼 수 있습니다.

4. 건드리지 않게 하기: plan 모드로 '읽기 전용'을 보장하기

처음 보는 코드를 파악하는 도중에 AI가 센스를 발휘해 편집을 시작하면 곤란합니다. plan 모드로 설정하면, Claude는 파일을 읽고 계획을 제안할 뿐, 승인하기 전까지는 디스크에 접근하지 않습니다.

$ claude --permission-mode plan

세션 도중에 전환하려면 Shift+Tab으로 토글할 수 있습니다. 파악 단계는 plan 모드로, 수정 단계가 되어서야 비로소 편집을 허용하도록 구분하면 실수를 줄일 수 있습니다.

5. 문맥을 오염시키지 않기: 탐색은 서브 에이전트 (Sub-agent)에게 위임하기

대규모 리포지토리를 읽게 하면, 파일 로딩으로 인해 메인 대화의 컨텍스트 (Context)가 가득 차게 됩니다. 탐색은 별도의 문맥에서 실행하고, 결론만 가져오도록 하는 것이 효과적입니다.

use a subagent to investigate how our auth system handles token refresh

서브 에이전트는 자신의 컨텍스트에서 파일을 읽고 요약본만 반환합니다. 메인 대화는 핵심 요점으로 채워지므로, 긴 분석 과정에서도 흐름이 끊기지 않습니다.

왜 위임하면 편해지는가 (보충)

처음 보는 코드를 조사할 때는 '읽어야 할 양'이 많고, 관련 파일을 차례로 열수록 메인 대화 이력이 방대해집니다. 비대해진 이력은 후반부 질문의 정확도에 영향을 미칩니다. 서브 에이전트 위임은 조사의 '읽기 작업'을 격리하고, 메인에는 결론(어느 파일에서 어떻게 구현되어 있는가)만 돌려주는 분업 방식입니다. 여러 논점을 병렬로 조사하고 싶을 때도 적합합니다.

/init으로 CLAUDE.md에 고정하기

6. 이해를 남기기: 파악하며 알게 된 것(빌드 절차·배치 규칙·주요 모델)은 세션이 끝나면 휘발됩니다. 다음의 자신과 팀을 위해 CLAUDE.md에 남깁니다. /init은 코드베이스를 분석하여 초안을 만들어 줍니다.

> /init
Analyzing codebase...
Created CLAUDE.md with build commands, project structure,
...

생성된 CLAUDE.md에 분석을 통해 파악한 '지도'를 자신의 언어로 추가합니다.

# 프로젝트 개요
- Flask 제작 REST API (app/main.py 가 엔트리 포인트)
+
...

이렇게 하면 다음 세션은 지도가 처음부터 컨텍스트에 포함된 상태로 시작할 수 있습니다. CLAUDE.md의 위치, 읽기 순서, 분할 설계 자체는 별도 기사 「CLAUDE.md를 읽기 순서에 따라 설계하기」에서 자세히 다루고 있습니다.

요약

• 처음 보는 코드는 넓게(개관) → 좁게(@로 범위 지정) → 흐름(트레이스) 순으로 파악한다
• 개관에는 보완 정보가 섞일 수 있다. @ 참조로 실제 파일에 발을 붙여 사실 관계를 확인한다
• plan 모드 (--permission-mode plan / Shift+Tab)로 파악 중에는 수정하지 못하게 한다
• 긴 조사는 서브 에이전트에게 위임하여 메인 문맥을 오염시키지 않는다
• 파악한 지도는 /init 후 추가하여 CLAUDE.md에 남기고 다음 세션으로 인계한다

도움이 되었다면 ❤️와 Zenn 팔로우로 응원해 주세요. 다음 분석 콘텐츠를 쓰는 데 큰 힘이 됩니다.

Discussion